[opensourcedex]

UserAgent-Switcher is a free, open source browsers & extensions project written in JavaScript and released under MPL-2.0. It has 1,543 GitHub stars, 200 forks and 150 open issues, and was last pushed 3 days ago. On this registry it ranks #116 of 150 tracked projects in Browsers & Extensions, with 5 head-to-head comparisons available. It gained 22 stars over the last 30 tracked days.

What is UserAgent-Switcher?

UserAgent-Switcher is a highly configurable, MPL-2.0 licensed browser extension for Chrome, Firefox, Edge, and Opera that spoofs the User-Agent string in HTTP request headers and in the JavaScript navigator objects that pages read, so anyone testing, researching, or deliberately reshaping their browser identity gets one consistent identity across every detection path.

What it is

UserAgent-Switcher is a JavaScript WebExtension published under the Mozilla Public License 2.0. It lives in the browser-extension ecosystem, with store listings for Chrome, Firefox, Edge, and Opera, and it modifies both the User-Agent sent in request headers and the JavaScript properties that expose the same information, including navigator.userAgent, navigator.appVersion, and navigator.platform. It also handles modern browser identification mechanisms such as Client Hints headers and the navigator.userAgentData object, so the spoofed identity holds across both legacy and current detection methods.

The problem it solves is inconsistency. A browser ships one fixed User-Agent string, and changing it in one place rarely changes it everywhere: header-level overrides can leave the JavaScript-visible values mismatched, which makes a spoofed identity easy to detect and unreliable for testing. UserAgent-Switcher applies the same identity to headers, navigator objects, and Client Hints together, and it lets that identity vary by context rather than globally. Rules can be scoped to a specific hostname, to an individual browser tab, or, on Firefox, to a container, and a User-Agent can be drawn at random from a user-defined list. The project carries 1,513 stars, 190 forks, and 150 open issues on GitHub.

Key capabilities

  • Modifies HTTP request headers in parallel with JavaScript navigator properties, covering navigator.userAgent, navigator.appVersion, and navigator.platform.
  • Supports Client Hints headers and the navigator.userAgentData object alongside the classic User-Agent string.
  • Applies User-Agent rules per specific hostname rather than globally.
  • Assigns different User-Agents to individual browser tabs.
  • Uses Firefox's container feature for a distinct User-Agent per container, a capability not yet available on manifest v3.
  • Randomizes selection from a user-defined User-Agent list.
  • Imports and exports User-Agent lists for backup or transfer between setups.

Who uses it and how

  • Users on Chrome, Firefox, Edge, and Opera install it from each browser's official add-on store, so no build step or developer tooling is required.
  • Developers and testers load the source directly: as an unpacked extension through chrome://extensions, edge://extensions, or opera://extensions with Developer mode enabled, or as a temporary add-on in Firefox.
  • Users who need separate identities per Firefox container rely on the container-scoped rules to keep each container's User-Agent distinct.
  • Teams and individuals who maintain curated User-Agent lists use the import and export functions to move lists between browsers or machines.

Getting started

The extension installs from the official add-on stores for Chrome, Firefox, Edge, and Opera. For development or the latest unstable code, load the source manually as an unpacked extension, selecting the directory that contains manifest.json at its root.

How it compares

No list of paid products or similar tools is provided in the facts for this project, so it stands alone in this registry on those axes. Readers should evaluate it on its own merits: open source under MPL-2.0, distributed through browser vendor stores, and with no named alternative documented in the repository metadata.

When to use it — and when not to

There is no server, database, or mail service to operate here: the extension runs inside the browser, so the operational burden is limited to installing it and maintaining User-Agent lists. Users should not choose it if they need Firefox container-scoped spoofing on manifest v3, since the README states that combination is not yet available. The repository also shows 150 open issues and a README that defers detailed usage instructions to an external guide, so anyone needing fully self-contained documentation should read that guide before committing.

project readme (upstream, from github) — read inline

UserAgent-Switcher

A highly configurable browser extension for spoofing your User-Agent string.

UserAgent-Switcher modifies both the User-Agent in your browser's request headers and relevant JavaScript navigator properties (e.g., navigator.userAgent, navigator.appVersion, navigator.platform). It also supports modern browser identification mechanisms such as Client Hints headers and the navigator.userAgentData object, ensuring consistent and comprehensive spoofing across all detection methods.

Key Features

  • Comprehensive Spoofing: Modifies both HTTP request headers and JavaScript navigator objects.
  • Granular Control:
    • Spoof User-Agent per specific hostname.
    • Set different User-Agents for individual browser tabs.
    • Utilize Firefox's container feature for distinct User-Agents per container (not available on manifest v3 yet).
  • Randomization: Option to randomly select a User-Agent from a user-defined list.
  • Easy Import/Export: Manage your User-Agent lists with simple import and export functionality.

Demo / Review

See the extension in action:

User-Agent Switcher and Manager - Browser Extension Review

(Video: "User-Agent Switcher and Manager - Browser Extension Review")

Installation - Official Releases

You can install the latest stable version from your browser's official add-on store:

Usage

For detailed instructions on how to use the extension, including configuration options and features, please visit: UserAgent-Switcher Usage Guide

Manual Installation (from Source Files)

If you have cloned or downloaded the source files from this repository, you can manually install the extension in your browser. This is useful for development, testing the latest (potentially unstable) code, or if you prefer to install extensions directly from source.

For Chromium-based Browsers (Google Chrome, Microsoft Edge, Opera)

The process for these browsers involves loading the extension as an "unpacked extension":

  1. Get the Source: Ensure you have the extension's source files (including manifest.json at the root of the extension's directory structure) on your local machine. If you've cloned this repository, these files are typically in the main or a src/ directory. If there's a build process (e.g., npm run build), run it first to generate the distributable files, typically in a dist/ or build/ folder.
  2. Open Browser Extensions Page:
    • Chrome: Navigate to chrome://extensions
    • Edge: Navigate to edge://extensions
    • Opera: Navigate to opera://extensions
  3. Enable Developer Mode:
    • Look for a toggle switch labeled "Developer mode" (usually in the top-right or bottom-left corner of the extensions page) and turn it on.
  4. Load Unpacked Extension:
    • Once Developer Mode is enabled, a button like "Load unpacked" will appear. Click it.
    • A file dialog will open. Navigate to and select the directory containing the extension's source files (the folder that has the manifest.json directly inside it). Click "Select Folder" or "Open."

The UserAgent-Switcher extension should now be loaded and active. If you make changes to the source code, you'll typically need to return to the extensions page and click a "Reload" icon or button for the extension to apply the changes.

For Mozilla Firefox

Method 1: Load Temporary Add-on (for Development/Testing)

This method allows you to load the extension directly from the source files. It will remain installed until you restart Firefox or manually remove it.

  1. Get the Source: Ensure you have the extension's source files (including manifest.json at the root of the extension's directory structure) on your local machine.
  2. Open Firefox.
  3. Navigate to Debugging Tools: Type about:debugging into the Firefox address bar and press Enter.
  4. Select "This Firefox": In the left-hand sidebar, click on "This Firefox".
  5. Load Add-on: Click the "Load Temporary Add-on..." button.
  6. Select Manifest File: Navigate to the directory where you have the extension's source code and select the manifest.json file (or any file within the extension's root directory). Click "Open."

The UserAgent-Switcher extension should now be loaded. If you make changes to the source code, you can click the "Reload" button next to the extension's entry on the about:debugging page.

Method 2: Package as an .xpi File and Install (More Persistent Local Install)
  1. Prepare Files:
    • Ensure all necessary source files are present, with manifest.json at the root.
    • If this repository uses a build process, run it first.
  2. Create a ZIP Archive:
    • Navigate to the directory containing the finalized extension files.
    • Select all files and subfolders inside this directory. The manifest.json file must be at the root level within the ZIP archive.
    • Compress the selected items into a ZIP archive (e.g., user_agent_switcher.zip).
  3. Rename to .xpi: Change the file extension from .zip to .xpi (e.g., user_agent_switcher.xpi).
  4. Install in Firefox:
    • Open Firefox and go to the Add-ons Manager (about:addons or Ctrl+Shift+A / Cmd+Shift+A).
    • Click the gear icon (⚙️) on the Extensions panel.
    • Select "Install Add-on From File..."
    • Locate and select your .xpi file and click "Open." Confirm the installation.

Important Considerations for Manual Installation (from Source):

  • Extension ID Consistency: For stable development and testing (especially if your extension uses storage or needs a consistent ID for APIs):
    • Chromium-based browsers: You can add a "key" field to your manifest.json. This is a Base64 encoded public key. If the key field is present when loading an unpacked extension, Chrome/Edge/Opera will derive a consistent ID. Without it, the ID may change if the path to the extension folder changes.
    • Firefox: Ensure the manifest.json includes a unique add-on ID via the browser_specific_settings.gecko.id field (e.g., "id": "user-agent-switcher@your-domain.com").
  • Persistence: Loading an unpacked extension (Chromium) or as a temporary add-on (Firefox) typically means the extension is active for the current session or until manually reloaded/removed. The Firefox .xpi method provides a more permanent installation for that browser.
  • Packaging for Distribution: If you intend to distribute the extension more widely outside of simply loading the source files:
    • Chromium-based browsers: Extensions are packaged into .crx files, often handled through the respective web stores (Chrome Web Store, Microsoft Edge Add-ons, Opera addons).
    • Firefox: Extensions are packaged as signed .xpi files, typically distributed via addons.mozilla.org (AMO).
    • Signing is a crucial step for official distribution to ensure security and integrity. Standard browser versions often restrict or warn against installing unsigned extensions from outside their official stores.

Contributing

Contributions are welcome! If you have ideas for improvements, new features, or have found a bug, please feel free to:

  1. Open an issue in the repository to discuss the change or report the bug.
  2. Fork the repository and submit a pull request with your changes.

Please ensure any contributions align with the project's coding style and goals.

License

This project is licensed under the Mozilla Public License 2.0 (MPL-2.0).

You can find a copy of the license in the LICENSE file in this repository or at https://www.mozilla.org/en-US/MPL/2.0/.

Frequently asked questions

Is UserAgent-Switcher free to use?

UserAgent-Switcher is open source under the MPL-2.0 licence. There is no licence fee and no seat count — you can self-host it or, where the project offers one, pay a vendor for a managed version instead.

What does UserAgent-Switcher do?

A User-Agent spoofer browser extension that is highly configurable

What is UserAgent-Switcher written in?

UserAgent-Switcher is primarily written in JavaScript. Its source is publicly available at https://github.com/ray-lothian/UserAgent-Switcher, and it has 1,543 GitHub stars.