camoufox drives the Camoufox browser through Playwright. On every launch it draws a complete device identity from fpgen, a model of real-world traffic, checks that the parts agree with each other, and hands it to the browser, which spoofs it in C++. With a proxy and geoip=True it also matches timezone, locale, geolocation and the WebRTC IP to the proxy's exit IP.

The TypeScript package (typescript/) is a port of this one with the same options. Notes for AI coding agents are in AGENTS.md.

Install

pip install -U "camoufox[geoip]"
camoufox fetch

camoufox fetch installs the browser build this release is paired with, and fpgen's model, pinned by sha256. Without it, the first launch downloads both. Run fetch as the user that owns the Python environment if the browser will run as someone else, for example while building a Docker image. camoufox remove deletes everything that was downloaded.

Usage

Camoufox returns ordinary Playwright objects, so existing Playwright code works once the launch is changed.

Sync and async

from camoufox.sync_api import Camoufox

with Camoufox(headless=True) as browser:
    page = browser.new_page()
    page.goto("https://example.com")

import asyncio
from camoufox.async_api import AsyncCamoufox

async def main():
    async with AsyncCamoufox(headless=True) as browser:
        page = await browser.new_page()
        await page.goto("https://example.com")

asyncio.run(main())

Proxy with a matching location

from camoufox.sync_api import Camoufox

with Camoufox(
    proxy={"server": "http://proxy.example.com:8080", "username": "user", "password": "pass"},
    geoip=True,
) as browser:
    page = browser.new_page()
    page.goto("https://example.com")

geoip=True looks up the exit IP through the proxy, then sets timezone, locale, geolocation and the WebRTC IP from it. Pass an IP string instead to skip the lookup.

Persistent profile

from camoufox.sync_api import Camoufox

with Camoufox(persistent_context=True, user_data_dir="profiles/alice") as context:
    page = context.new_page()
    page.goto("https://example.com")

With persistent_context=True the context manager yields a BrowserContext, not a Browser.

One browser, many identities

NewContext() gives each context its own identity (navigator, screen, WebGL, fonts, voices, audio seed, timezone, WebRTC IP), applied through add_init_script before any page script runs.

from camoufox.sync_api import Camoufox, NewContext

with Camoufox(headless=True, canvas_noise=True) as browser:
    alice = NewContext(browser, os="windows")
    bob = NewContext(
        browser,
        os="macos",
        proxy={"server": "http://proxy.example.com:8080", "username": "user", "password": "pass"},
    )
    alice.new_page().goto("https://example.com")
    bob.new_page().goto("https://example.com")

AsyncNewContext() is the async twin.

Canvas noise belongs to the browser, not the context (see The canvas on another OS). On a browser without it, every context claims the host's OS and GPU too, since its canvas renders there. Contexts with other OSes, like the ones above, need canvas_noise=True.

The canvas on another OS

A page can draw a canvas or a WebGL scene and read the pixels back. Those pixels come from the real OS, driver and GPU, whatever the identity claims.

• On the host's OS, the launcher starts the browser once, unspoofed and with the same display, reads the GPU Firefox reports, and the identity claims it. The pixels then agree with the identity. A host that renders in software (no GPU driver, as on most servers) keeps a drawn GPU: it reads as a machine whose driver failed to load.
• On another OS, or with another GPU (webgl_config, a preset's GPU, or a host GPU fpgen never recorded), the pixels would show the real one. Camoufox then turns on the canvas protection of privacy.resistFingerprinting, and only that: canvas and WebGL readback return random data, as in LibreWolf, Tor Browser and Mullvad Browser. Stock Firefox does not do this, so the launch prints a LeakWarning; the browser reads as a privacy-hardened Firefox rather than a stock one.

canvas_noise=True turns the protection on for any OS, canvas_noise=False never.

WebGPU follows the same rule. navigator.gpu exists only where Firefox on the claimed device has it (Windows and Apple Silicon Macs), and the adapter is the host's only when the identity claims the host's GPU. Otherwise requestAdapter() returns null, as Firefox does for a blocked or software GPU.

Headless modes

Remote server

Run Camoufox in one process and connect from any language Playwright supports:

from camoufox.server import launch_server

launch_server(headless=True, geoip=True, port=1234, ws_path="camoufox")

It prints the websocket endpoint. Connect with playwright.firefox.connect("ws://localhost:1234/camoufox"). A persistent context cannot be served.

Your own Playwright instance

NewBrowser() launches on a Playwright instance you already have, and launch_options() returns the keyword arguments for playwright.firefox.launch():

from playwright.sync_api import sync_playwright
from camoufox import NewBrowser, launch_options

with sync_playwright() as playwright:
    browser = NewBrowser(playwright, os="linux", headless=True)
    browser.close()

    browser = playwright.firefox.launch(**launch_options(os="linux", headless=True))
    browser.close()

Prefer NewBrowser(): it also defaults new pages to no_viewport when the window size is spoofed, and to the host's own color scheme and motion settings.

Launch options

Camoufox, AsyncCamoufox, NewBrowser, AsyncNewBrowser, launch_server and launch_options all take these keyword arguments. Any other keyword is passed to Playwright's firefox.launch() (or launch_persistent_context()).

NewBrowser and AsyncNewBrowser also take persistent_context and from_options (a dict from launch_options() to use as is).

CLI

camoufox <command>, or python -m camoufox <command>.

set and fetch read builds from these repositories (repos.yml):

https://github.com/user-attachments/assets/992b1830-6b21-4024-9165-728854df1473

Which browser build is used

Each release of this package is paired with the one browser build it was built and tested with. camoufox fetch installs that build and every launch uses it, even when other builds are installed and even when the paired build is a prerelease. A launch with the paired build missing downloads it first, so upgrading the package never runs a browser it was not tested with.

camoufox set overrides the pairing. The choice is kept, and each launch warns that the build differs from the paired one. camoufox set --release goes back. The browser launch option overrides it for one launch, the same way: the named build must already be installed, and nothing is downloaded.

Every browser release declares the interface it speaks, and the package refuses one it cannot drive: sync leaves it out, fetch refuses it, and a launch fails, each saying which package upgrade is needed. Once a sync has seen such a build, every launch warns that the package needs upgrading.

A development checkout (installed from the repository, not from PyPI) is paired with nothing and follows its channel, official/stable by default.

Development

From the repository root:

python3 -m venv .venv
.venv/bin/pip install -r ci/requirements.txt -e 'python[geoip]'
.venv/bin/python python/scripts/pin-fpgen-model.py
.venv/bin/python -m ci.run_pythonlib

ci.run_pythonlib runs python/tests/, the same job CI runs. Which suite covers which change is in AGENTS.md.

Licence

MIT (LICENSE). The browser itself is MPL-2.0.