Userscripts vs Chrome Extensions: What's the Difference?

Userscripts and Chrome extensions can both change how websites look and behave. They are not the same thing, and choosing the wrong one adds unnecessary friction.

What Is a Userscript?

A userscript is a JavaScript file that runs on web pages you specify. The script sits at the top of the file, which controls which sites it runs on and when. That is the entire format: one JS file, one metadata block.

Userscripts do not run on their own. They require a userscript manager, the most common being Tampermonkey (available for Chrome, Firefox, Edge, and Safari). You install the manager as a browser extension, then add individual scripts to it. The manager handles injection, updates, and permissions.

What Is a Chrome Extension?

A Chrome extension is a packaged set of files, including a manifest.json that declares what the extension does, what permissions it needs, and what scripts to load. Extensions can include background service workers, browser action popups, options pages, content scripts, and more.

Extensions are distributed through the Chrome Web Store (or loaded unpacked during development). They have access to browser APIs that userscripts cannot reach, like modifying browser history, intercepting network requests via declarativeNetRequest, managing tabs, or showing desktop notifications.

Key Differences

	Userscript	Chrome Extension
Format	Single JS file	Folder of files with manifest
Requires	A userscript manager	Nothing (self-contained)
Distribution	Share the .js file or use Greasyfork	Chrome Web Store or direct install
Browser APIs	Limited (GM_ APIs only)	Full Chrome extension API
Setup time	Minutes	More involved

The userScripts API and the Toggle Requirement

Chrome added a native userScripts API in Manifest V3 that lets extensions run arbitrary user-provided scripts. There is an important restriction: users must manually enable this feature in chrome://extensions by turning on Developer mode, or the extension must prompt them to do so. Chrome made this a deliberate user-controlled toggle for security reasons. If your extension relies on the userScripts API, your users need to take that extra step.

Tampermonkey handles this differently because it predates the new API and uses its own injection mechanism. Most people using Tampermonkey today do not think about the API layer at all.

When to Use a Userscript

Use a userscript when you want to make a quick, personal tweak to a site and you already have Tampermonkey (or a similar manager) installed. Hiding an annoying element, redirecting links, autofilling a form field, these are good userscript use cases. The low overhead means you can write and test a script in a few minutes.

Userscripts are also easy to share: post the raw JS file and anyone with a manager can install it in one click.

When to Use a Chrome Extension

Use a Chrome extension when you need browser APIs beyond what a userscript can access, when you want to ship to users who do not have a script manager installed, or when the feature involves a popup interface, background processing, or cross-tab state.

Extensions are also the right choice if you plan to distribute something publicly. The Chrome Web Store gives your tool a proper listing, automatic updates, and user reviews.

The Middle Ground

Many developers start with a userscript to validate an idea, then graduate it to a full extension when it outgrows what a single script can do. There is no shame in starting small.

If you want to skip the file and manifest setup entirely, Extension Coder lets you describe what you want to build and generates a ready-to-load extension for you.