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. It reads the build's release with one GitHub API call and exits non-zero when it installs nothing. On a shared CI runner, set GITHUB_TOKEN to raise GitHub's API rate limit. 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.

Without a proxy, sites can reach this machine over IPv6. IPv6 stays on when the machine's IPv6 address geolocates where the IPv4 identity does. Otherwise, the browser behaves as on an IPv4-only network, and a LeakWarning says why.

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, 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 browser's own OS also decides some things for all its contexts. A browser launched as Windows on a Linux or macOS host (os="windows", or drawn so) computes Math as the Windows CRT does and uses Windows' keyboard shortcuts (on a Linux host; on macOS only the editor caret style), middle-click and scrollbars (docs/HOST-PARITY.md). Those are browser settings, so a macOS context on it has them too, and a Windows context on a browser launched as another OS has the host's. NewContext does not refuse the mix. Pass os at launch for the OS whose behaviour matters, or use one browser per OS.

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

The GPU display

from camoufox.sync_api import Camoufox

with Camoufox(headless="virtual-gpu", gpu="0000:01:00.0", os="linux") as browser:
    page = browser.new_page()

• The card is named, never guessed. gpu= (or CAMOUFOX_GPU) takes a PCI address, which is the stable choice, or an index in PCI address order, a render or card node (renderD128, /dev/dri/card1), vendor:device ids (10de:2c02) or a vendor name (nvidia). With several GPUs and no selector the launch raises AmbiguousGpuSelection; GpuNotFound and NoGpuFound mean what they say. python -m camoufox gpu-xorg-config lists the GPUs when the choice is ambiguous.
• Without root, set the machine up once per card. Xorg then runs through the setuid Xorg.wrap, which takes a config only from /etc/X11 and needs allowed_users=anybody and needs_root_rights=yes in /etc/X11/Xwrapper.config. Stock Debian and Ubuntu ship allowed_users=console, which refuses a launch from ssh, systemd or a container. One command installs Xorg and the wrapper (with apt-get; elsewhere it says what to install), sets those two lines and installs the card's config. It is safe to run again:

  python -m camoufox gpu-setup 0000:01:00.0 | sudo sh
  

  A launch that fails for want of any of this ends its error with that command. The settings let any local user start a root X server. gpu-xorg-config prints just the card's config. As root, nothing is installed: a temporary config is used instead.
• It leaves your desktop alone. The server drives no monitor, shares the current VT and exits when the browser closes. If the active VT changes while it starts, the launch switches back, stops the server and raises GpuVtTakeover.
• The launch checks the browser renders on the card. A page draws WebGL and the launch waits up to 30 s (CAMOUFOX_GPU_WAIT_S) for the kernel to account GPU work to the browser. If it never does, the browser is closed and GpuSoftwareFallback is raised; require_gpu=False warns instead. There is no fallback to Xvfb.
• The identity claims that card. On the host's OS the identity claims the GPU Firefox reports, read on this display, so it is the card's and not the desktop's (see The canvas on another OS).
• The browser gets DISPLAY and the X11 backend, and nothing that chooses a GL driver. These prefs default on, and firefox_user_prefs wins: gfx.webrender.all, layers.acceleration.force-enabled, gfx.x11-egl.enabled, gfx.canvas.accelerated and gfx.canvas.accelerated.force-enabled.

Every error here is a VirtualDisplayError.

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.