How to Use Tampermonkey: A Beginner's Guide to Your First Userscript

People often send me the same kind of message. They want a button that a site doesn't have. Or they want a list of items copied from a page into a spreadsheet. Someone told them a userscript can do it.

They're right. A userscript is the cheapest way to change how a site works, even if you don't own it. You don't need a lot of tools to start. The install takes seconds. Your first script takes a few minutes, mostly because of one setting that trips up almost everyone.

Here's the full process, step by step. It's the same order I use when I walk a client through it on a call. If you searched for "how to use tamper monkey" (with a space), you're in the right place too.

What Is a Userscript?

A userscript is a small piece of JavaScript. Your browser adds it to certain web pages each time you visit them.

Every page you load already runs JavaScript. A userscript just adds your own code on top.

Tampermonkey is a userscript manager. It stores your scripts. It decides which sites each script runs on. Then it runs them at the right time. Without a user script manager, you'd have to paste your code into the browser console by hand on every visit.

Keep one thing in mind. Your script only runs in a tab you have open. It's not a server. It doesn't run on a timer. It stops when you close the tab. For many small jobs, that's all you need.

How to Install the Tampermonkey Extension

Open the Chrome Web Store.
Search for the Tampermonkey extension.
Click Add to Chrome.

That's it. There's nothing to set up.

The same browser extension works in Chrome, Microsoft Edge, Safari, Firefox, Opera and Brave. The steps are almost the same in each one. Only the names of some settings change. On Microsoft Edge, Safari, Opera and the rest, look for the same toggles in that browser's extension settings.

Next, pin the icon to your toolbar. You'll use it a lot. Digging through the puzzle-piece menu each time gets old fast.

Enable Developer Mode (The Step Most People Miss)

Most people skip this step. It's the main reason first scripts don't work.

New versions of Chrome and Edge make you turn on user scripts yourself. Here's how:

Go to chrome://extensions.
Enable developer mode with the toggle in the top right.
Click Details under the extension.
Turn on Allow user scripts.

Why does this step exist? Running your own code on a site is powerful. So the browser makes you say yes on purpose. Chrome explains this in its guide to the userScripts API and its developer-mode rule.

A quick fix to common advice (including an old version of this article): Allow access to file URLs is a different setting. It only matters for local file:/// pages on your own computer. It does not make scripts work on normal websites. If you turn it on and expect your script to run on a shopping site, you'll stay stuck.

https://www.youtube.com/watch?v=_IOakqqczSE

How to Use a Tampermonkey Script: Make Your First One

Click the extension icon. Choose Create a new script. An editor opens with a template already in it.

Replace the text with this short script. It's small, so you'll know right away if it worked:

JavaScript

// ==UserScript==

// @name         Link counter

// @match        https://example.com/*

// @grant        none

// ==/UserScript==




const links = document.querySelectorAll('a');

console.log('Links on this page:', links.length);

Now click File → Save. The script is saved inside the manager. It's not a file on your desktop, so you don't need to move anything.

Look at document.querySelectorAll. I use it in almost every scraping script I write. It finds every element that matches a CSS selector. If you learn just one browser tool, learn this one. I still check MDN's guide to querySelectorAll.

The Top Block Decides If Your Script Runs

The block of comments at the top matters. The manager reads it first.

@name is the name you'll see in the dashboard.
@match is the most important line. It tells the manager which pages the script is for. Set it to https://example.com/* and the script runs on every page of that site, and nowhere else. If this line is wrong, your code won't run, even if it's perfect.
@grant none means the script doesn't need any extra powers, so it runs fast. You'll change this later if you want to save data between visits or talk to other sites.

The official Tampermonkey guide to these settings lists every option. Skim it once so you know what's there.

Installing Scripts Made by Others

You don't have to write every script yourself. Sites like Greasy Fork have thousands of free userscripts. Any popular userscript there installs in one click.

Before you confirm, the script installation screen shows you the code. It also shows which sites the script will run on. Take a look.

Scripts you install this way can get automatic updates. The manager checks for new versions on its own. Fixes show up without you doing a thing.

Back Up Your Scripts with Cloud Storage

Once you have a few scripts, back them up. Open the dashboard settings and find the sync option. It saves your scripts to cloud storage. You can use Google Drive, Dropbox, OneDrive or WebDAV.

Sync also helps if you use more than one computer. Turn it on at each one and use the same account. Your scripts will follow you.

Open the Site, Refresh, and Check

Go to the site in your @match line. Was the tab already open before you saved? Then refresh it. Scripts only load when the page loads, so an old tab won't see your new script.

Most people ask me about two kinds of jobs:

Shopping sites. The goal is to copy product names and prices into a list.
Sites with odd layouts, like Pinterest. The goal is to add a button the site doesn't have.

Both work the same way. Match the URL. Find the elements. Do something with them.

Press F12 to open the console and see your console.log message. A green badge with a number on the extension icon means a script matched this page.

When Your Userscript Doesn't Run

Nothing happened? Don't worry. That's normal. It's almost always one of five things.

Fixes to Try, in Order

Check your @match line. A missing /* at the end is the top cause. So is http when the site uses https.
Make sure the script is turned on in the dashboard.
Check developer mode and the user scripts toggle again. Browser updates can turn them off.
Refresh the right way. Reload the tab. Don't just click back to it.
Wait for the page to finish. Many sites load their content a bit later. Your script may run before anything is there. For a quick test, delay your code by two seconds. For a lasting fix, use a MutationObserver to wait until the elements show up.

Still Stuck? Check the Console

Errors show up in the console with a line number. Cannot read properties of null means the element wasn't on the page when your script looked. That's a timing problem or a selector problem. It's rarely anything worse.

When a Userscript Is the Wrong Tool

I'll be direct, because this saves people money. A script extension like this is great for tasks you do while sitting at your browser. It's the wrong tool when a job needs to:

run overnight,
run on a schedule,
cover thousands of pages, or
run with no one at the computer.

For those jobs, switch to Python and Playwright. Playwright runs a browser on its own. It can save data straight to a database or a Google Sheet. See Playwright's getting-started guide to learn more. I also compare the two in the DatafetchPro guide to browser automation services.

Stay safe: Never run a userscript from a forum without reading it first. It can see everything you're logged in to.

A Note on the Sites You Scrape

Can you scrape a certain site? That depends on its terms of service and its robots.txt file. That choice is yours, not mine. RFC 9309, the robots.txt standard, explains what the file is and how to read it.

I'll build the tool and tell you honestly what's possible. The choice about each site stays with you.

Want Someone to Build It for You?

Maybe you tried all of this and your script still won't run. Or it runs, then breaks each time the site changes. At that point, hiring help often costs less than another weekend of fixing bugs.

I build userscripts, Chrome extensions, no-code browser macros, and full Python and Playwright tools. I sell only through Fiverr.