10/6/2015

TampermonkeyFAQ
Search

Search this page:

Tampermonkey
by Jan Biniok

Home

FAQ

Documentation

Userscript Sources

Support

Changes

Contribute

About

Forum

This section contains some of the most frequently asked questions. If you miss something, just send me a message.

Content
Q100: How do I install and uninstall Tampermonkey (TM)?
Q101: How do I work with TM?
Q102: How to install new scripts to Tampermonkey?
Q103: Is it possible to overwrite or extend a scripts includes and/or excludes? How
is this working?
Q104: What is the @user-agent tag for and how does it work?
Q105: How can I sync all scripts installed at Tampermonkey to another Chrome
browser?
Q106: How can I export and import my scripts?
Q200: Is it possible to install scripts as native Chrome extension even though
Tampermonkey is installed?
Q201: Is Tampermonkey compatible to NotScripts?
Q202: Tampermonkey missing, there is no icon and no script is running. Where are
my scripts and what happened?
Q203: Tampermonkey extension shows a warning. Why?
Q204: How can I allow Tampermonkey access to local file URIs?
Q205: How do I setup the Native Script Import?
Q206: Tampermonkey tells me that my Chrome profile is broken. What does that
mean?
Q207: My scripts are gone and Tampermonkey moans that Chrome wiped the
extension database. What's going on here?
Q300: Tampermonkey can access every page that I visit! Is TM evil?
Q301: Chrome says "Danger: Malware Ahead!". Is Tampermonkey infected with
Malware?
Q302: How do I setup userscript-triggered downloads?
Q303: Tampermonkey says one of my scripts is blacklisted. Why?
Q401: Tampermonkey slows down my computer. What can I do?
Q402: I want to use an external editor to edit my scripts. How can this be done?
Q403: How do I enable the experimental Javascript feature?
Q404: What is the unsafeWindow retrieval setting and how does it work?
Q405: Tampermonkey seems to run at every page instead of only those where
scripts are supposed to run. Why?
Q500: XYZ is my native language. How can I translate TM to XYZ?
Q501: My native language is already supported and I have no idea how to write
javascripts. How can I support you ?
Q600: Ahhh, someone wants my console output. Where can if find that?
Q700: Tampermonkey reports a problem with Dolphin.

General
Q100: How do I install and uninstall Tampermonkey (TM)?

A100: Both is pretty easy:

http://tampermonkey.net/faq.php

1/10

10/6/2015

TampermonkeyFAQ

In order to install Tampermonkey take a look at the download page here and click at one of the grey retangles. (

video tutorial)

If you want to uninstall Tampermonkey click at the Chrome menu, click at "Tools" and "Extensions". Then search for the
Tampermonkey entry and press the trash icon. ( video tutorial)
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 contribute some dollars or euros for my extraordinary work. ;) ( video tutorial)
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
script name to edit and setup your scripts. ( video tutorial)
There is second tab that allows you to modify TM'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.
Go to TMs options page and click at the edit column of the <New script> item. Enter the source and save it. ( 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 .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:

Click at the image to view full size

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

http://tampermonkey.net/faq.php

2/10

10/6/2015

TampermonkeyFAQ

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:
Code:
//==UserScript==
//@nameUA|eBay
//@namespacehttp://ebay.de/
//@version0.1
//@descriptionentersomethinguseful
//@match*://*.ebay.tld/*
//@useragentMozilla/5.0(WindowsNT6.1)AppleWebKit/537.13(KHTML,likeGecko)
Chrome/24.0.1284.0Safari/537.13
//@copyright2011+,You
//==/UserScript==

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.

http://tampermonkey.net/faq.php

3/10

10/6/2015

TampermonkeyFAQ

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:
constBLOCKING_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. (

http://tampermonkey.net/faq.php

video tutorial)

4/10

10/6/2015

TampermonkeyFAQ

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

video tutorial)

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 Opera

mfdhdgbonjidekjkjmjaneanmdmpmidf

Tampermonkey Legacy

dcgolfjdmhddbdbpipnjnakbblbojcnf

And this is where the extensions are located:

Linux
Windows XP
Windows
Vista/7/8
Windows V/7/8
(Opera Next)
Mac OS

/home/<user>/.config/google-chrome1/Default/Extensions/<extension>/
C:\Documents and Settings2\<user>\Local Settings3\Application Data4\Google\Chrome\User Data\Default\Extensions\

<extension>\
C:\Users\<user>\AppData\Local\Google\Chrome\User Data\Default\Extensions\<extension>\
C:\Users\<user>\AppData\Roaming\Opera Software\Opera Next\Extensions\<extension>\
/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?

A206:
History
This issue was earlier caused by a bug in Chrome at the chrome.storage API. Chromes internal database at Windows OSes
somehow got corrupted.
Why do I see this warning?
Nowadays the bug should be fixed but some users are still reporting that they (sometimes) see this the "broken profile" message.
Since I do not see the warning myself I can only guess what's going on and I need some help to find the root cause.
How does Tampermonkey detect that the profile is broken?
As already mentioned Tampermonkey is using Chrome's API to store values like the settings and your scripts. That's why it runs a
simple test to detect issues. It stores a value and reads it back. If an error condition is set, the read value differs from the written
one or the whole process hasn't finished within 3 minutes then TM claims that something is wrong.
How can I help?
Some users reported that this can be seen when Chrome was updated, when they move or copy files and others see it all the
time. My first guess was that maybe just the first storage hit fails. In order to workaround this I reworked Tampermonkey Beta to
re-run the test five times before assuming the worst.
http://tampermonkey.net/faq.php

5/10

10/6/2015

TampermonkeyFAQ

If you see this issue or have seen it, then please report the details at the forum. Please include information like:
Can you reproduce this issue with TM Beta?
How often have you seen this issue?
Was Chrome updated recently?
Did you run heavy file operations (copy/move) in parallel?
Does this happen only after or while your OS is still booting?
You just want to get rid of the warning?
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('#brokenprofile','nowarning')

You want to workaround the issue, whatever it takes?

OK, 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, Follow the steps above but enter this:
Code:
localStorage.setItem('#storage','sql')window.location.reload()

and press enter

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 possible 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?
http://tampermonkey.net/faq.php

6/10

10/6/2015

TampermonkeyFAQ
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.
In order to fix this issue:
Click at the image to view full
size

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.

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.

Advanced
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 https://*) 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, make sure the Config mode is at least set to Beginner, go to Settings and extend the Blacklisted
http://tampermonkey.net/faq.php

7/10

10/6/2015

TampermonkeyFAQ

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:
For example by this Facebook exclude regular expression: http://userscripts-mirror.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
http://tampermonkey.net/faq.php

8/10

10/6/2015

TampermonkeyFAQ

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:
Before getting the output you have to enable debug output.
Just right-click at the Tampermonkey icon, choose Options and set Logging Level to Debug. (

video tutorial)

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. ( video tutorial)
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.
(

video tutorial)

Environment specific questions

Q700: Tampermonkey reports a problem with Dolphin.

http://tampermonkey.net/faq.php

9/10

10/6/2015

TampermonkeyFAQ

A700:
You'll see this message if Tampermonkey detects that its scripts are successfully injected into the page but can't communicate
back to the Tampermonkey add-on. This problem is caused by a Dolphin bug. So if this problem persists, then you might want to
notify them of the problem by sending them a mail to support@dolphin.com with your Android, Dolphin and WebView version.
Possible work-arounds are listed below.
If you're using Android 5.0 or higher then make sure you're using the latest version of the WebView component.
Try to enable Dolphin Jetpack, either it's part of your Dolphin browser itself or you can download it at the Play Store
Use the (outdated) Dolphin test APK provided by the developers. Please use this APK only for testing!
Downgrade your WebView component. You can get different versions from here. Please be careful when installing APKs
from third-party pages.

Imprint | Privacy | 2010-2015 Jan Biniok

http://tampermonkey.net/faq.php

10/10