How to Install a Userscript, Step by Step

Step 1: install a userscript manager

Before any userscript can run, you need a manager extension installed in your browser. Tampermonkey and Violentmonkey are both available from their respective browser web stores for Chrome, Firefox and Edge. Search the store for the extension by name, click install, and confirm the permissions it requests.

Without a manager, clicking a userscript link will just open or download a plain text file with no effect.

Most stores show the extension’s requested permissions before you confirm the install. A userscript manager typically asks for permission to read and change data on all websites, since that is what it needs to inject scripts wherever a @match pattern requires. This is a normal and expected request for this category of extension, not a sign of anything unusual.

Step 2: open the .user.js URL

Userscripts are distributed as plain text files ending in .user.js. On a page such as the HatScripts /userscripts hub, each script has a link or install button pointing to this file. Clicking it with a manager installed triggers the manager to intercept the file instead of downloading it as text.

If your browser downloads the file instead of opening an install tab, the manager extension may not be enabled, or your browser may be treating .user.js differently than expected. Check the extension’s icon in the toolbar to confirm it is active before trying again.

Step 3: read the install prompt

Your manager opens a confirmation tab showing the script name, description, version, author and the source code. Read this before installing, especially the list of sites it will run on and any external resources it loads. This is your chance to check the script matches what you expected.

Take a moment to skim the actual code, not just the metadata block, if you are comfortable reading JavaScript. Look for anything that sends data somewhere unexpected, or that references domains unrelated to the script’s stated purpose.

Step 4: check permissions and @match

The install page lists @match or @include rules, which define which URLs the script activates on, and @grant lines, which list which privileged APIs it can call, such as GM_setValue or GM_xmlhttpRequest. A script that only needs to run on one specific site should list a narrow @match pattern, not a broad wildcard covering every page.

Step 5: click install and enable

Clicking install adds the script to your manager’s dashboard. New scripts are enabled by default, but confirm this in the dashboard toggle list if the script does not appear to be working. Visit a page matching the script’s @match pattern and refresh it to see the script take effect.

Step 6: updating an installed script

Most managers check for updates periodically using the @updateURL and @version fields in the metadata block. You can also trigger a manual check from the dashboard. Review the diff shown before accepting an update, since a script update can change its permissions or behavior.

Understanding the metadata block fields

It helps to know what each common metadata field actually controls, since the install prompt is built directly from these lines.

• @name and @namespace identify the script uniquely so updates apply to the right installed copy
• @version is compared against the installed version to decide whether an update is available
• @match and @include define which pages the script runs on, with @match using a stricter pattern syntax
• @exclude removes specific URLs from an otherwise broader @match pattern
• @grant lists which privileged GM_ or GM. functions the script may call, and an empty @grant means it runs with no elevated access
• @run-at controls injection timing relative to page load
• @updateURL and @downloadURL point to where the manager checks for and fetches new versions

A concrete example install

Suppose you visit the HatScripts /userscripts hub and choose a script that adds a dark mode toggle to a specific site. Clicking its install link opens Tampermonkey’s confirmation tab showing @match https://example.com/*, @grant GM_setValue and GM_getValue, and no @connect entries. Since the script only reads and writes its own local settings and does not make network requests, there is nothing to be cautious about beyond confirming the @match pattern targets the right site. Clicking install adds it immediately, and visiting example.com shows the toggle without any further configuration.

Troubleshooting when nothing happens

If a script appears installed but has no visible effect, work through the following checks in order.

• Confirm the script is enabled in the manager dashboard, not just installed
• Confirm the current page URL actually matches the script’s @match or @include pattern
• Check whether the site uses a different domain or subdomain than the script expects
• Open the browser console and look for errors thrown by the script
• Confirm the manager itself is enabled for the current browser profile or incognito window
• Reload the page after making any change, since scripts run on page load, not retroactively
• Check whether another installed script conflicts with the same page, for example by both modifying the same DOM element
• Verify the script has not silently reached an @grant it lacks, which some managers report only in the console rather than visibly on the page

A second worked example: a script that needs network access

Now suppose the script you pick from the HatScripts /userscripts hub adds a price comparison badge that fetches data from a separate pricing API. The install prompt this time shows @match https://shop.example.com/*, @grant GM_xmlhttpRequest, and @connect pricing-api.example.com. Because the script requests a privileged networking function and names a specific external domain, this is worth a closer look before clicking install.

Confirm the @connect domain matches what the script’s description claims it needs, and be suspicious of a script that lists a domain unrelated to its stated purpose. Once installed, the first request to that domain may trigger a separate one-time permission prompt from the manager, distinct from the initial install confirmation, since network activity is flagged separately from installation itself.

Installing from a raw file instead of a hub link

Not every userscript you find comes from a page with an install button. Sometimes you will have a .user.js file saved locally, for example after downloading it as an attachment or exporting it from another machine. Most managers let you drag the file directly onto the dashboard, or use an Import option in the Utilities tab, which opens the same confirmation tab you would see from a web link.

The review step matters just as much here, since a locally saved file has not been through any hub’s own listing process, and you are relying entirely on your own read of the metadata block and source code.

Version and update behaviour after install

Once installed, a script with an @updateURL is checked periodically by the manager, typically once a day, and you can also force a check manually from the dashboard. Updates are not applied silently. You will see a confirmation tab similar to the original install, and it is worth reading it with the same care, since an update can add a new @grant or @connect line that was not present when you first installed the script.

Mobile installation notes

On Android, installing through Kiwi Browser or Firefox for Android follows the same steps as desktop, since both support the same extension APIs a userscript manager needs. On iOS, installation looks different: you install the manager as an app from the App Store, then enable it for Safari from the Settings app, and finally grant it permission for the specific site you want a script to run on, rather than clicking a link on a web page.

Frequently asked questions

Do I need to restart my browser after installing a script? No. Managers inject scripts on page navigation, so a normal page refresh is enough.

Can I install a userscript on a phone browser? Some mobile browsers support extensions, including certain Firefox and Kiwi Browser builds on Android, and Safari on iOS through apps like the Userscripts app. Most default mobile browsers do not support extensions at all.

What happens if two installed scripts both match the same page? Both will run. If they modify the same part of the page, the order they run in is generally the order they were installed, though this is not guaranteed across every manager version.