Tampermonkey® by Jan Biniok

Table of Contents

General

Q100: How do I install and uninstall Tampermonkey?

A100 Both is pretty easy:

  • In order to install Tampermonkey take a look at this video:

  • If you want to uninstall Tampermonkey then please check this video:

Q101: How do I work with Tampermonkey?

A101 Tampermonkey is a browser extension. A browser extension is a small software program that extends the functionality of a web browser. These extensions are designed to add specific features or functionality to the browser, such as ad blocking, password management or, in this case, userscript injection.

  1. One common feature of browser extensions is the ability to add an icon next to the URL in the browser's address bar (Tampermonkey icon). In some browsers you have to manually pin the icon to see it all the time. Clicking on the icon opens a popup menu, which provides information about the running scripts and a link to open the extension settings.

  2. The background page is another important part of a browser extension. This is a hidden webpage that runs in the background of the browser, allowing the extension to perform tasks or functions without the need for user interaction. This includes things like checking for updates, syncing data, or processing information.

  3. Finally the options page allows to configure Tampermonkey and manage your userscripts. The first tab shows all installed scripts. Click at the script name to edit and setup your scripts. ( video tutorial)

There is second tab that allows you to modify Tampermonkey's settings. Tip: adjust the "Config mode" options to see more settings. ( video tutorial)

The third tab offers script import and export functionality to Zip files and JSON documents.

Q102: How to install new scripts to Tampermonkey?

A102 There are different ways to achieve this:

  • Go to this page to learn about the different script sources. If you found a page then search for a script, open the script's page and click at the install button. ( video tutorial)

  • Search GitHub Gist and Github for userscripts. Then click it at the "view raw" link. ( video tutorial)

  • You can also search for scripts at your preferred search engine. Then search for a link that ends up on ".user.js" and click it

  • If you have a URL to a script, just paste it to Chrome's Omnibox.

  • In the Tampermonkey dashboard, click on the "Add a new script" button. This will open a new editor window where you can write or paste your userscript. Enter the code for your userscript in the editor window. Make sure to include the correct metadata at the top of the script, as this is required for Tampermonkey to recognize it. The metadata should include the @name, @match and @description fields, which specify the name of the script and the URL pattern that it should run on.

    Once you have entered your userscript code, click on the "Save" button to save it. Your userscript will now appear in the list of installed scripts in the Tampermonkey dashboard. ( video tutorial)

  • Go to Chromes extensions page, enable the "Allow access to file URLs" checkbox at the Tampermonkey item, create a file with the file extensions ".user.js" and drag-and-drop it to Chrome.

Q103: Is it possible to overwrite or extend a scripts includes and/or excludes? How is this working?

A103 Sure, just go to the options page and click at the script's name you want to modify. A new tab is opened that shows the script's source code.

includes editor

Click at the "settings" tab (1) to get the *cludes editor shown at the image above.

Now you can select i.e. a entry from the "Original includes" section (2) and add them as exclude by clicking at "Add as User excludes" (3). The entry now appears at the "user excludes" section (5) and the script will not run at this page anymore.

If you want to make a script run at a page it originally shouldn't you have to use the "Original excludes" section (4). Again select a entry, click a the button bellow the section and the entry will appear at "User includes".

You can also add, edit or remove entries that are manually added by using the buttons (6) below the according User section ("User includes", "User matches" and "User excludes").

If you want to override the orginal includes completely just uncheck the checkbox (7) in front of the according heading. For example you have to uncheck "Original includes" if you want to disable the directive htt*://*facebook.com/*.

Q105: How can I sync all scripts installed at Tampermonkey to another browser?

A105 It is very easy to sync your scripts. Please follow this procedure to enable the sync feature:

  1. Go to Tampermonkey's Dashboard and select the "Settings" tab
  2. now set the "Config Mode" to either "Beginner" or "Advanced"
  3. search for the "Script Sync" section and
  4. Choose your favorite sync service (see below)
  5. Finally you need to "Enable Script Sync" and press the "Save" button

Tampermonkey supports the following sync services:

  • Google Drive You need a Google Account in order to use this service. Once enabled Google asks whether Tampermonkey is allowed to store data at a special folder which solely contains app data.
  • Dropbox A Dropbox account is needed for this. Once enabled Dropbox asks whether Tampermonkey is allowed to store data to your Dropbox. Note: if this service is enabled Tampermonkey will not run scripts at several Dropbox related URLs anymore!
  • WebDAV You can use any WebDAV server, but you may need to enter credentials to access it. Please also have a look at TamperDAV. It contains some proprietary features which speed up the process and allows script editing with your own external editor. Note: Tampermonkey will not run scripts at the server's URLs anymore!
  • Browser Sync If it's available for your browser, then it uses your browser's internal service to transfer information between all Tampermonkey instances. Please note that you have to be signed in to your browser and that the amount of data that can be synced is very limited. That's why Tampermonkey needs a publicly accessible URL to sync your scripts. To be clear on that: only scripts that are downloaded from a web server or that contain a valid @downloadURL tag are processed. For that purpose both, the http and https protocol can be used.

Q106: How can I export and import my scripts?

A106 Import and export of scripts is pretty simple. Just go to TM's Dashboard/Options page. If you see a 'Utilities' tab then go there, otherwise set the 'Config Mode' to either 'Beginner' or 'Advanced' in order to see it. At this tab there are different sections depending on your Tampermonkey version and browser support:

  • Cloud: You can import and export zip files via cloud service. Please check Q105 for the cloud service list.
  • Zip: You can import and export zip files from and to your harddisk. Please click 'Export' to save a zip file or 'Choose File' to select an archive for import.
  • File: You can import and export JSON text files from and to your harddisk. Please click 'Export' to save such a file or 'Choose File' to select a file for import.
  • Textarea: You can import and export zip files from and to a text area input element. Please click 'Export' to fill the textarea and copy its value or 'Import' after you've pasted a JSON document.
  • URL: In case Tampermonkey is unable to detect (due to a failing script URL detection or because it's disabled) a userscript, then you can force Tampermonkey to import it from this URL here.

Chrome Extension

Q200: Is it possible to install scripts as native Chrome extension even though Tampermonkey is installed?

A200 Yes it is. If you want to install a script just click at the install link. Tampermonkey now asks you whether to install the script in Tampermonkey or native in Chrome.

install dialog;

Q203: Tampermonkey extension shows a warning. Why?

A203 Tampermonkey checks whether HTTP headers like "user-agent" or "referer" can be modified by userscripts. If now another extension like a user agent spoofer or an script blocker like ScriptNo modifies this request too the warning is displayed. This should not occur that often when the option "Allow HTTP headers to be modified by scripts" is set to "Yes" (Default) or even never if it is set to "No".

failed to modify

Q204: How can I allow Tampermonkey access to local file URIs?

A204 File access for Tampermonkey is only available at Chrome and derivates. In order to enable it open Google Chrome and click on the "More" icon (the three dots) in the top-right corner of the window. From the menu, select "More tools" and then click on "Extensions".

This will open the Chrome extensions page (chrome://settings/), which shows a list of all the extensions that are installed in your browser. Find Tampermonkey and click on the "Details" link to the right of its name.

On the extension's details page, scroll down to the "Permissions" section. Here, you will see a list of all the permissions that the extension has been granted. To enable file access, you will need to check the box next to the "Allow access to file URLs" permission. ( video tutorial)

Q205: Where is the extension data located?

A205 The location where a Google Chrome extension's data is stored varies depending on the operating system. On Windows, the data is stored in the following location:

C:\Users\[USERNAME]\AppData\Local\Google\Chrome\User Data\Default\Extensions\[EXTENSION_ID]

Replace [USERNAME] with the name of the user who is logged in to the computer, and [EXTENSION_ID] with the unique ID of the extension. This ID can be found in the extension's details page in Chrome, under the "ID" section.

On Linux, the data is stored in the following location:

/home/[USERNAME]/.config/google-chrome/Default/Extensions/[EXTENSION_ID]

Again, replace [USERNAME] with the name of the user who is logged in, and [EXTENSION_ID] with the extension's ID.

On MacOS, the data is stored in the following location:

/Users/[USERNAME]/Library/Application Support/Google/Chrome/Default/Extensions/[EXTENSION_ID]

Here, [USERNAME] should be replaced with the current user's name, and [EXTENSION_ID] should be replaced with the extension's ID.

Please note that the exact location of the data may vary depending on the specific version of the operating system and the Chrome browser that you are using. For example google-chrome or Google\Chrome might also be chromium, Opera Next or another string depending on you browser. If you are unable to find the data at the above locations, you may need to search for the Extensions folder manually on your system.

Extension IDs:

Tampermonkey dhdgffkkebhmkfjojejmpbldmpobfkfo
Tampermonkey Edge iikmkjmpaadaobahmlepeloendndfphd
Tampermonkey Beta gcalenpjmijncebpfijmoaglllgpjagf
Tampermonkey Edge Beta fcmfnpggmnlmfebfghbfnillijihnkoh
Tampermonkey Opera mfdhdgbonjidekjkjmjaneanmdmpmidf

Q206: Tampermonkey tells me that my Chrome profile is broken. What does that mean?

A206 If your Chrome browser profile has a corrupted extension storage, you can try the following steps to repair it:

  • First, back up your browser profile folder. Q205 explains how to access it.
  • Then open Google Chrome and click on the "More" icon (the three dots) in the top-right corner of the window. From the menu, select "More tools" and then click on "Extensions".
  • On the Extensions page, click on the "Remove" button next to the name of each extension that you want to remove. This will remove the extension and its data from your browser.
  • Once you have removed all the extensions that you want to delete, close the Chrome browser and restart your computer.
  • After restarting your computer, open the Chrome browser again and go to the Extensions page. Re-install any extensions that you removed in step 2.
  • If the problem persists, you can try creating a new Chrome profile. To do this, click on the "More" icon in the top-right corner of the window and select "Settings". On the Settings page, scroll down to the bottom and click on "Advanced".
  • In the "Advanced" section, click on the "People" section and then click on "Add person". Follow the prompts to create a new user profile in Chrome.
  • Once the new profile has been created, you can install your extensions and try using them again. This should fix any problems with corrupted extension storage in your original profile.

Q207: My scripts are gone and Tampermonkey moans that Chrome wiped the extension database. What's going on here?

A207 In order to solve the issue described above at Q206 Chrome now tries to automatically correct any corruption by removing corrupted parts. Depending on the severity of the corruption it might restore some data, otherwise the database is just empty. Since this can also affect Tampermonkey's data it tries to detect this process and notify you of the possible loss of all or some settings and scripts.

Q208: My scripts are only executed after several reloads, the console prints "pagejs missing".

A208 This is caused by a bug in Chromium that causes Tampermonkey's content scripts to run in the wrong order. Unfortunately the order matters and due to timing constraints it is not possible to wait longer for the other content script than already done. This bug "only" happens when the extension is updated from a previous stable version lower than 4.18. To fix the issue simply:

  • Disable Tampermonkey extension
  • Restart browser (make sure that all browser processes are gone, better restart the computer)
  • Enable Tampermonkey extension
  • Restart browser

Disabling the extension seems to cleanup things and the content scripts are executed in the right order again.

If it still doesn't work, then please

  • export your settings and scripts (you can try importing them into the BETA version first to be on the safe side) and
  • re-install Tampermonkey and
  • import the backup again.

Security

Q300: Tampermonkey can access every page that I visit! Is Tampermonkey evil?

A300 ...like any other chrome extension that has https and http access! This includes extensions like AdBlock, ScriptSafe, Avast Online Security and due to the fact that it is not displayed explicitly when they are downloaded, any userscript that is installed as native Chrome extension.

If you're interested in this, you can find the access information a the right column of every extension at the Chrome store by searching for "This extension can access". Tampermonkey needs to be able to run at every page, because it doesn't know at what pages your userscripts will run and therefore needs to be able to inject them into every page.

But you're right, userscripts and extensions can harm your privacy and your computer. Nevertheless I think more evil is that Chrome does not display at what pages a userscript wants to run on when install it is installed as native extension. From this point of view Tampermonkey even can bring you some security back, at least if you believe me, that I'm not interested in any of your data. If not, you can open the console (Ctrl-Shift-J) and choose the network tab to investigate what network communication is done. :)

Q301: Chrome says "Danger: Malware Ahead!". Is Tampermonkey infected with Malware?

A301 No, Tampermonkey is not infected. Chrome shows this message because the options page tries to load a favicon from a page that Google suspects to be evil. So this just means that you have script installed that has such an malicious page in its @includes and Tampermonkey loads the favicons from there to give you an overview where your scripts will run.

DangerClick at the image to view full size

In order to fix this issue please configure another "Favicon Service" like "Google" or "DuckDuckGo";

Q302: How do I setup userscript-triggered downloads?

A302 First, please notice that downloading files to your harddisk may be security relevant! Malware might have an easy job once it is downloaded. So please make sure that you only allow the download of non-executable files.

There are a few steps necessary to enable the download feature: ( video tutorial)

  • Go to the options page
  • Scroll down to the "Downloads" section
  • Double-check the "Whitelisted File Extensions" setting to not contain file extensions of executable files
  • Select "Browser API" at the "Download Mode" option
  • A notification may come up, you need to click at it and to click "confirm" at the permission grant dialog

Note: Even though GM_download is a powerful function, it's finally more or less just convenience for the userscript autors.

Q303: Tampermonkey says one of my scripts is blacklisted. Why?

A303 This happens cause you either added the source URL to the "Manual Userscript and @require Blacklist" or it was added to the list maintained by me. You can find the list including the reason for blackisting at the GitHub repo.

If you still want the script to run then you can either increase the "Severity Level" or disable the remote list this way:

  • Go to the options page
  • Make sure "Config Mode" is set to Beginner or higher
  • Scroll down to the "BlackCheck" section
  • Modify the "Blacklist Source" or "Severity Level"

Note: If you're a script author and think I made a mistake, then just send me an email or open an issue at GitHub.

Q304: What permissions are necessary to run Tampermonkey and why?

A304 Tampermonkey requires the following permissions. Some of them might be optional at some browsers and need to be granted only when used.

  • "notifications" for GM_notification, Tampermonkey related notifications
  • "tabs" to find the active tab and navigate, create and close tabs in general
  • "idle" to not show update notifications if your playing a game
  • "webNavigation" install userscripts, check URLs for matching scripts
  • "webRequest webRequestBlocking" install userscripts, check URLs for matching scripts, modify request details for GM_xmlhttpRequest
  • "storage" to store your userscripts
  • "unlimitedStorage" to store many of your userscripts 🤓
  • "contextMenus" for @run-at context-menu
  • "chrome://favicon/" to easily get the favicons of pages
  • "clipboardWrite" for GM_setClipboard
  • "cookies" GM_xmlhttpRequest, GM_cookies
  • "<all_urls>" to run your userscripts at every page and to allow them to modify the page
  • "downloads" GM_downloads, storing Tampermonkey backups

In Chrome these permissions translate to:

  • Read your browsing history
  • Display notifications
  • Modify data you copy and paste

Especially the first one looks a little bit strange. In fact it's not possible for Tampermonkey to get access to your browser history when it is installed. In theory Tampermonkey could access the history of all currently open tabs and store "new" history once installed, but this is neither needed nor done. However, because of this fact the Chrome team maybe thought that printing a too broad warning is better than a too flat one. There also is a bug report for this.

In Firefox this translates to

  • Access your data for all websites
  • Input data to the clipboard
  • Download files and read and modify the browser’s download history
  • Display notifications to you
  • Access browser tabs
  • Store unlimited amount of client-side data
  • Access browser activity during navigation

Q305: I'm using Chrome and Tampermonkey keeps coming back after uninstallation. Why is this?

A305 Chrome has a "feature" that allow third-party software (which is not related to me) to instruct Chrome to install extensions. There are legit use-cases like a desktop software that needs an extension being installed, but also malware can make use of this.

That's why please check the preferences file and/or Windows registry keys and remove all unwanted entries.

If the entries re-appear, then the problematic software is still at your PC!

Windows users please open the registry editor and check these two keys:

32-bit Windows HKEY_LOCAL_MACHINE\Software\Google\Chrome\Extensions
64-bit Windows HKEY_LOCAL_MACHINE\Software\Wow6432Node\Google\Chrome\Extensions

Tampermonkey's (stable) ID is dhdgffkkebhmkfjojejmpbldmpobfkfo.

Important: I'd suggest to check your system for malware and viruses.

Advanced

Q400: How to I view and edit values stored by a userscript

A400 Open Tampermonkey's Dashboard and click at the script's name. Click at the "Storage" if present and check or modify the stored data as needed. If there is no "Storage" tab, then the script has no data stored (yet).

Q401: Tampermonkey slows down my computer. What can I do?

A401 This is a known issue caused by the iframe support of Tampermonkey (and by the way Greasemonkey too ;)). In order to avoid Tampermonkey to check and most probably run scripts at unwished iframes you can do a lot of different things:

  • Avoid No global includes Try not to use scripts that @include all pages (http://* and https://*) cause these scripts will run at every tab, every frame and every advertisement. Note: Tampermonkey outlines such scripts by this icon <i class= *"fa fa-globe fa-lg"* aria-hidden="true"> at their sites column.

  • Make Tampermonkey not run at social buttons Open TM's options page, make sure the "Config mode" is at least set to "Beginner", go to "Settings" and extend the "Blacklisted Pages" text area like this

    *://apis.google.com/_/+1/*button*
    *://www.facebook.com/plugins/*
    *://platform.twitter.com/widgets/*
    
  • Exclude advertisements You can try your own excludes based on this:

    *://*.doubleclick.*/*
    *://*advertising*
    *://*banner*
    

Q402: I want to use an external editor to edit my scripts. How can this be done?

A402 There are multiple possible ways:

  • Chrome (and derivates users) can export and @require the local copy
    • Open Tampermonkey's dashboard, open the script and copy its content.
    • Create a local file and paste the content
    • Remove all content from the script inside Tampermonkey except the "UserScript" header
    • Add a @require tag with the path to the local file that you want to include in the script. For example, if the file is located at C:\Users\[USERNAME]\Documents\myscript.js, you would add the following line to the script:
      // @require       file://C:/Users/[USERNAME]/Documents/myscript.js
      
    • Finally enable local file access.
  • You can try TamperDAV
  • You can try the Tampermonkey Editors extension to edit the script at vscode.dev

Q403: How do I enable the experimental Javascript feature?

A403

This is pretty simple. Just go to chrome://flags.

unsafeWindow_flags

Now a page with all experimental Chrome featues is shown - search for 'Javascript'.

unsafeWindow_experimental

Click 'Enable' and 'Relaunch now' at the bottom of the page.

unsafeWindow_relaunch

Q404: What @sandbox value should I use?

A404 @sandbox supports the following values: "raw", "JavaScript" and "DOM"

  • "raw" access means that a script for compatibility reasons always needs to run in page context. At the moment this mode is the default if @sandbox is omitted.
  • "JavaScript" access mode means that this script needs unsafeWindow access. At Firefox a special context is created which should also bypass all remaining CSP issues. Execution in page context is used as fallback at other browsers.
  • "DOM" access mode means that the script only needs DOM and no direct unsafeWindow access. If enabled these scripts are executed inside the extension context or at any other enabled context otherwise.

There is also an option to configure the available sandbox modes which can be used by userscripts. Attention: any option that enables "DOM" mode is potentially unsecure. Userscripts that run in extension context have almost full extension permissions and can even modify and install new userscripts.

Q405: Tampermonkey seems to run at every page instead of only those where scripts are supposed to run. Why?

A405 Unfortunately Chrome does not allow code injection into frames at the right time. That's why Tampermonkey needs to be injected into every page, because only pre-defined content scripts will be executed at document-start for sure. After the injection, it asks the main application whether to run a script at this URL, and if not, it unloads itself to free all resources. You can help to improve this and tell the Chrome developers how important this feature is for you by starring this and this issue at Chrome's bug tracker.

Just login with you Google Account and click at the star in front of the issue heading. Thanks.

Support Development

Q500: XYZ is my native language. How can I translate Tampermonkey to XYZ?

A500 Thanks! :) This is pretty easy.

Just clone or fork the i18n repository from Github, apply your changes and send me the file or create a pull request.

More information how internationalization of extensions works can be found at Google's Extension Development Documentation.

Tip: you can attach an additional file called about.txt that will be delivered from now on with the extension.

Q501: My native language is already supported and I have no idea how to write javascripts. How can I support you ?

A501 You can use Tampermonkey and report bugs if you've found one, make a small contribution or give Tampermonkey a 5-star rating here.

Thanks. 😅

Debugging

Q600: Where can if find Tampermonkey's console output?

A600 Before getting the output you have to enable debug output. Just click at the Tampermonkey icon, choose "Dashboard", select the "Settings" tab and set "Logging Level" to "Debug"". ( video tutorial)

There are 3 different consoles that Tampermonkey might write log messages to.

  • First the background page console which can accessed this way:

    In Google Chrome, go to the extensions page by clicking on the "More" icon (the three dots) in the top-right corner of the window, selecting "More tools", and then clicking on "Extensions". On the extensions page, find the extension that you want to access the background page console for, and click on the "Details" link to the right of its name. On the extension's details page, click on the "background page" link under the "Inspect views" section. This will open the background page in a new window or tab. ( video tutorial)

    In Firefox, go to the extensions page by clicking on the "More" icon (the three minuses) in the top-right corner of the window, selecting "Add-ons and Themes". Click at the gear icon at the upper right corner and choose "Debug Add-ons". On the debugging page find the Tampermonkey entry and click "Inspect". Finally select the "Console" tab.

  • The second one is the option page console.

    You can open it this way: right click at the Tampermonkey icon and choose "Dashboard". At the new tab press "Ctrl-Shift-J" or "F12" and select the "Console" tab.

  • Last but not least every web page has a console.

    This one can be opened by "Ctrl-Shift-J" when viewing the page. ( video tutorial)