loading...

Please wait...
Tampermonkey
by Jan Biniok
Home
Support
Changes
Donate
About
This section contains some of the most frequently asked questions. If you miss something, just send me a message.
Content
General

Q100: Where can I get Tampermonkey (TM)?

A100:
There are different versions of TM. most probably it's the best to take a look at the download page here.

Q101: How do I work with TM?

A101:
TM consists of 4 different parts:
  • the button A mouse clicks opens the context menu, a right mouse click opens the alternative context menu created by chrome itself
  • the context menu The context menu show what scripts are currently running. You can enable or disable then by clicking at the green/red LED icon.Additionally there are some extra links to the TamperFire page (if enabled at the options), a forced scripts update check and a button to easily donate some dollars or euros for my extraordinary work. ;)
  • the options page You can open this at the alternative context menu by clicking at options. The first tab shows all installed scripts. Click at the icon at the table to perform some actions like moving, editing and deleting a script.The second tab allows you to modify TM's settings . You can also enable some disabled features like TamperFire.The third tab offers script import and export functionality. For your first experiments use the "Export to document" and "Open File" Buttons and follow the displayed instructions. The "SandboxFS" is a folder of your chrome's profile folder. Use this button only to backup your scripts locally. The Textarey can be used to backup or restore some data manually.
  • the TamperFire page This one is only viewable if TamperFire is enabled. You can open it by clicking at the first entry of the context menu ("x scripts available"). The "Available userscripts" tab can be used to search for userscripts for manually entered URLs. The settings tab displays some information about the TamperFire database and allows forced updates.

Q102: How to install new scripts to Tampermonkey?

A102:
There are different ways to achieve this:
  • Goto userscripts.org, greasyfork.org or openuserjs.org. Search for a script, open the script's page and click at the install button.
  • Search GitHub Gist for userscripts. Then click it at the view raw link.
  • 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.
  • Goto TMs options page and click at the edit column of the <New script> item. Enter the source and save it.
  • Goto Chromes extensions page, enable the Allow access to file URLs checkbox at the Tampermonkey item, create a file with the file ending .tamper.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. 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/*".

Q104: What is the @user-agent tag for and how does it work?

A104:
Sometimes pages use a string that is sent by your browser to determine the layout or feature set that will be show to you. For example if you using Chrome on Linux it is almost impossible to sell an item on eBay cause it is not possible to upload images. So what can TM do for you now?Just install this script that overwrites your user-agent string to look like a Windows Chrome and everything will be working fine again:
Image Image
Code:
// ==UserScript==
// @name       UA | eBay
// @namespace  http://ebay.de/
// @version    0.1
// @description  enter something useful
// @match       *://*.ebay.tld/*
// @user-agent Mozilla/5.0 (Windows NT 6.1) AppleWebKit/537.13 (KHTML, like Gecko) Chrome/24.0.1284.0 Safari/537.13
// @copyright  2011+, You
// ==/UserScript==
This screen shots show the eBay page one time with this script running and without:Note: you can get user-agent strings and test your settings here: http://www.useragentstring.com/ and http://www.useragentstring.com/pages/useragentstring.php

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

A105:
It is very easy to sync your scripts but there is one limitation: Tampermonkey can only sync scripts that are installed from a remote source. This source can be any URL that is accessible by both of your Chrome browsers.

Please follow this procedure to enable the sync feature:
  • First, make sure you're signed in to Chrome at both browser instances
  • then go to TM's Dashboard/Options page and select the 'Settings' tab
  • now set the 'Config Mode' to either 'Beginner' or 'Advanced'
  • search for the 'TESLA' section and select 'Chrome Sync' at the 'Type' field.
  • Finally you need to 'Enable TESLA' and press the 'Save' button
Note: Since the amount of data that can be synced is very limited Tampermonkey needs a publicly accessible URL to sync your scripts to the other Tampermonkey instances. Therefore 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 Utilties tab then go there, otherwise set the 'Config Mode' to either 'Beginner' or 'Advanced' in order to see it.
At this tab there is a button Export to file that saves your scripts to your Download folder and a Choose File button to (re-)import your scripts.
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. TM now asks you whether to install the script in TM or native in Chrome.
Click at the image to view full size

Q201: Is Tampermonkey compatible to NotScripts?

A201:
Yes it is, but due to the fact that NotScripts destroys the whole javascript environment at the page context you have to either allow embedded scripts at every page a userscript should run on or add an options to the NotScripts configuration file. This can be done by simply adding the following code to CHANGE__PASSWORD__HERE.js.
Code:
const BLOCKING_MODE = "WHITELIST_ALLOW_TOP_LEVEL";
You can find more information here.

Q202: Tampermonkey missing, there is no icon and no script is running. Where are my scripts and what happened?

A202:
In order to show native userscripts at the options page Tampermonkey's permissions have changed to include the "management" permission. Chrome automatically disables extensions that need more permissions after an update, but show a bar like this: To re-enable Tampermonkey do the following steps:
  • Click the wrench icon on the browser toolbar.
  • Select "Tools".
  • Select "Extensions".
  • On the Extensions page, click Enable for Tampermonkey to re-enable it
Now a dialog like this should appear and you can double check the new permissions.

Q203: Tampermonkey extension shows a warning. Why?

A203:
TM 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"

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

A204:
Local file access can be given to an extension at the extension management page. Go to the settings page (chrome://settings/) and choose extensions at the left.

Now search for the Tampermonkey entry and enable the "Allow access to file URIs" checkbox.

Click at the image to view full size

Q205: How do I setup the Native Script Import?

A205:
Tampermonkey can help you to import your previously as an extension installed userscripts. The only things that TM needs to know is where it should search for the source of that extensions.

The following table will help you to identify your browser profile folder at your operating system. So just open your file manager an check what path fits for your system!

There are two wildcards that you have to know:
  • <user> is your user name
  • <extension> is the ID of the Tampermonkey extension you're using:

    Tampermonkey dhdgffkkebhmkfjojejmpbldmpobfkfo
    Tampermonkey Beta gcalenpjmijncebpfijmoaglllgpjagf
    Tampermonkey Beta Operamfdhdgbonjidekjkjmjaneanmdmpmidf
    Tampermonkey Legacy dcgolfjdmhddbdbpipnjnakbblbojcnf
And this is where the extensions are located:

Linux /home/<user>/.config/google-chrome1/Default/Extensions/<extension>/
Windows XP C:\Documents and Settings2\<user>\Local Settings3\Application Data4\Google\Chrome\User Data\Default\Extensions\<extension>\
Windows Vista/7/8 C:\Users\<user>\AppData\Local\Google\Chrome\User Data\Default\Extensions\<extension>\
Windows V/7/8
(Opera Next)
C:\Users\<user>\AppData\Roaming\Opera Software\Opera Next\Extensions\<extension>\
Mac OS /Users/<user>/Library/Application Support/Google/Chrome/Default/Extensions/<extension>/
1 might also be chromium
2 'Documents and Settings' might also be a localized name like 'Dokumente und Einstellungen'
3 'Local Settings', 'Lokale Einstellungen', ...
4 'Application Data', 'Anwendungsdaten', ...

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

Q206:
Ok, let me summarize this issue:

a) Why?

This issue is caused by a bug in Chrome at the chrome.storage API. Chromes internal database at Windows OSes somehow gets corrupted.

Tampermonkey recently (version 3.5.3630) switched to chrome.storage cause it is readable in normal and in incognito mode. So please don't give TM a bad rating when it forgets your scripts as a result of the data corruption.

And you can do me another favor: log-in to your Google account and vote for this issue to show the Chromium developers the importance. Thanks.

b) Recovery Method 1

The easiest solution is to create a new browser profile and to avoid to the use of Windows System Restore (as it seems that this can cause the database corruption).

If you want to export the script data from the version installed before 3.5.3630 you can follow the steps below and use the export function to backup your scripts for a later import.

c) Recovery Method 2

If creating a new profile is not an option I can tell you how to make TM use the earlier storage again, but there are major disadvantages:
  • Every time TM starts in incognito mode the (incognito) config will be emtpy!
  • This way is not heavily tested by me
  • When a new TM version is released it's possible that you need to run some other commands in order to get your data back.
You still want to go that way? Alright, here are the instructions:
  • right click at the TM icon and choose 'Manage' to open the extensions page (chrome://extensions/).
  • enable the 'Developer Mode' at the upper right if not already done and
  • search the page for the Tampermonkey entry
  • click at the 'background.html' link and
  • select the 'Console' tab
  • at the bottom of the window (where the cursor is blinking) insert:
    Code:
    localStorage.setItem('#storage', 'sql'); window.location.reload()
    and press enter
d) Just want silence?

If you merely want to get rid of the broken profile warning you can
  • disable TM (it can't work properly anyway) or
  • follow the steps above but enter this:
    Code:
    localStorage.setItem('#brokenprofile', 'nowarning');

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 TM's data it tries to detect this process and notify you of the pissible loss of all or some settings and scripts.
Security

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

A300:
...like any other chrome extension that has https and http access!
This includes extensions like AdBlock, NotScripts, Smooth Gestures 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, cause I don't know at what pages your userscripts will run and therefore TM must be able to inject them at 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 TM even can bring you some security back, tt 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.

Click at the image to view full size
In order to fix this issue:
  • note down what URL is mentioned at the warning page,
  • click at 'Advanced' and allow Chrome to continue,
  • then check your scripts step by step which one includes the page mentioned at the warning page and
  • finally remove this @include at the editor.
Advanced

Q400: I want to edit/view the values stored by a userscript. How can I do that?

A400:
Right-Click at the TM icon and choose "Manage", enable the Developer Mode if not already done and search for the Tampermonkey entry. Click at the "background.html" link and choose "Resources". Now there is a tree view at the left side, choose "Databases", "tmStorage" and "config". Now all config entries will be displayed.You can alter them by clicking at "tmStorage" again and typing some SQL commands at the right part of the window.
Some useful commands:
  • 'DROP TABLE config' - removes all data and resets TM to factory defaults
  • 'SELECT * FROM config' - show all rows
  • 'SELECT * FROM config WHERE name LIKE "TamperScript"' - shows the Tamperscript config entry

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

A401:
This is a known issue caused by the iframe support of TM (and by the way Greasemonkey too ;)). In order to avoid TM to check and most probably run scripts at unwished iframes you can do a lot of different things:
  • No global includes!!!
    Try not to use scripts that @include all pages (http://* and http://*) cause these scripts will run at every tab, every frame and every advertisement.
    Note: Tampermonkey outlines such scripts by this icon at their sites column.

  • Make TM not run at social buttons
    Open TM's options page, goto Settings and extend the Forbidden Pages text area:
    For example by this Facebook exclude regular expression: http://userscripts.org/guides/395
    and/or by others like:

    *://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:
Please take a look at the tutorials section to learn how to achieve this: http://forum.tampermonkey.net/viewtopic.php?p=1832#p1832

Q403: How do I enable the experimental Javascript feature?

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

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

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

Q404: What is the unsafeWindow retrieval setting and how does it work?

A404:
The unsafeWindow object allows userscripts to access Javascript objects of the page they're running on. So if you, for example, play a browser game the userscript may start an action by running a Javascript function automatically that you in normal have to start by a click at some button.

Unfortunately in Chrome 27 (or to be more accurate: since WebKit 537.35) the common way to retrieve the unsafeWindow is not working anymore.

But not every userscripts needs this type of interaction, some scripts just inject stylesheets (i.e. the scripts from userstyles.org) and other add some actions that don't need the page's Javascript (i.e. the Webcomic Reader).

Finally the correct answer of the question, what option should be set for the 'unsafeWindow retrieval method', depends on the scripts you're using and maybe the pages you're visiting. After setting the "Config Mode" to "Beginner", you can choose between 4 different options that will be described below.
  • Native
    This is the most secure option. If no unsafeWindow can be retrieved the safe window will be used, but scripts will not be able to access the page's Javascript objects.
    All scripts that are able to run as extension in Chrome will work.
  • Unsafe
    Tampermonkey can inject the scripts into the page context. By doing this they can access anything that the page's Javascript can access and additionally they have a reference to the GM_* functions.
    Before you now say "Good, I'll use this option" - wait!
    Although Javascript should be elaborated enough to not leak this powerful GM_* references to the page's functions, I can not guarantee this. Another downside is, the execution contexts are the same. This can cause i.e. the page's Jquery to be overwritten by a userscript requiring Jquery too and bad written userscripts may leak global variables and functions to the page context.
  • Sandbox
    This option runs the execution environment at the page context but wraps the scripts into a separated world so that global variables and required scripts like JQuery can not break the page. Please note that this is a very new implementation and it therefore still might contain bugs or trigger issues. Nevertheless, this seems to be the way to go in the future.
    If you discover a problem, please file a bug report here.
  • Auto
    'Auto' uses the 'Sandbox' option at the moment.

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 specific frames.
That's why as long as frames should be supported, Tampermonkey needs to be injected into every page. After the injection it asks the main application if a script is supposed to run at that URL and then 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 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 TM 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 TM and report bugs if you've found one, make a small contribution or give Tampermonkey a 5-star rating here. Thanks. :)
Debugging

Q600: Ahhh, someone wants my console output. Where can if find that?

A600:
There are 3 different kinds of consoles in TM.
  • First the background page console. The background page is the main part of TM. You can get the output this way: right click at the TM icon and choose "Manage", enable the Developer Mode if not already done and search for the Tampermonkey entry. Click at the "background.html" link and select the "Console" tab.
  • The second one is the option page console. You can open it this way: right click at the TM icon and choose "Options". At the new tab press "Ctrl-Shift-J" 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.
tbc... :-D