* Pin Firefox 157.0 Camoufox beta.33 is built on Firefox 157.0 (was 156.0.1). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * e2e: expect exactly the identity's input kinds from enumerateDevices() The probe asserted a non-empty pre-grant device list. Stock Firefox lists one entry per input kind the machine has and no outputs, so a speaker-only identity (about 6% of Windows draws) correctly lists nothing. Firefox 157.0's UA bump re-seeded the Windows preset onto such a machine, and 156.0.1 returns the same empty list for it. Compare against the kinds the config claims instead: it still fails on an empty list for a mic/camera identity, and it now also catches a wrong or missing kind, a host device leaking through, or an enumerateDevices() error. Gate-Change: Firefox 157.0's version in the UA re-seeds the Windows preset's media-device draw (pythonlib fingerprints.py from_preset -> identity_seed); verified the same empty list on 156.0.1-beta.32 and 157.0 for the no-mic/no-camera identity. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * Keep independent window placement with the WM, which Firefox 157 stopped doing Firefox 157 landed bug 2070008, which deleted the Unix special case in AppWindow::SizeShell(): bool positionSet = !mIgnoreXULPosition; #if defined(XP_UNIX) && !defined(XP_MACOSX) // don't override WM placement on unix for independent, top-level windows if (!parentWindow) positionSet = false; #endif so a top-level window now takes the position persisted in the profile's XUL store instead of leaving placement to the window manager. That makes window.screenX/screenY a function of leftover profile state, and a page can read it. Measured on this branch before the fix, same identity, same Xvfb: throwaway profile screenX 4 screenY 4 persistent profile screenX 26 screenY 0 v156.0.1-beta.32 reports 0/0 for both, so the two session types were indistinguishable and are no longer. fingerprint-injection.patch only answers GetScreenX/GetScreenY from the config when window.screenX is set, and the launcher does not draw it for every identity, so the real position shows through whenever it is absent. A position that varies with profile type correlates a user's fresh and persistent sessions, and it moves the browser rect MouseDispatch.js measures (docs/input-dispatch.md). Nobody places an automation browser's window by hand, so there is no UX here to gain and determinism to lose. Restores the guard for independent windows only; dependent windows are still placed relative to their parent, as upstream intended before and after. Both profile types report 0/0 again. Caught by typescript/tests/e2e.test.ts:506 in CI, which asserts a persistent profile presents the same device as a throwaway one. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * Pin Firefox 157.0.1 Camoufox beta.33 is built on Firefox 157.0.1 (was 157.0). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * Pin Firefox 158.0 Camoufox beta.33 is built on Firefox 158.0 (was 157.0.1). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * Port the Playwright bootstrap patch to Firefox 158 Firefox 158 moved the code under six hunks: - Bug 2072511 replaced HeadlessWidget::mCompositorWidget with a generic CompositorWidgetDelegate so the compositor can live in the GPU process. The screencast snapshot listener now reaches the in-process HeadlessCompositorWidget through AsHeadlessCompositorWidget(). - Bug 2071024 added movementX/movementY to SynthesizeMouseEventData and changed the mMovement coalescing check; jugglerEventId and the drag event synthesis sit beside the new code. - Bug 1688932 took bit 25 of nsIWebBrowserChrome's chrome flags for CHROME_MEDIA_PIP. JUGGLER_WINDOW_EXPLICIT_SIZE keeps bit 26, the last free one. - Bug 2070965 made UserAgentOverride an nsCString, which moved the context of the BrowsingContext field-namespace hunk. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * Refresh camoufox-window-module.patch context for Firefox 158 Bug 2070772 removed PartnerLinkAttribution.sys.mjs from browser/modules, so the module list hunk applied only with fuzz. The change is the same. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * Port config.patch to Firefox 158's top-level moz.build Bug 2070828 appended the SBOM GeneratedFile block to the end of the top-level moz.build, where config.patch adds the lw directory. The lw directory is still appended last. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * Port the worker userAgent override to Firefox 158's nsCString Bug 2070965 made WorkerNavigator::GetUserAgent take an nsCString, so the navigator.userAgent override assigns the UTF-8 config value directly instead of converting it to UTF-16. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * Port font-hijacker.patch to Firefox 158's gfx/thebes/moz.build Bug 2070824 appended license declarations to gfx/thebes/moz.build after the line the camoucfg include followed. The include is still appended at the end of the file. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * Port the network geolocation override to Firefox 158 Bug 2060572 moved the request's logging into the try block and made it throw first when geo.provider.network.url is unset. The CAMOU_CONFIG coordinates are now chosen before that check, so a configured location is reported without depending on the provider URL, as on Firefox 156. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * Port the per-context userAgent to Firefox 158's nsACString getters Bug 2070965 made Navigator::GetUserAgent and WorkerNavigator::GetUserAgent return UTF-8 and collapsed the window's custom user agent lookup. The per-context value is still checked first in both getters and is converted from the UTF-16 it is stored as. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * Refresh screen-spoofing.patch context for Firefox 158 nsRFPService::GetSpoofedStorageLimit, next to the declaration the patch changes, now returns int64_t, so the hunk applied only with fuzz. The change is the same. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * Refresh sessionstore-popup-close-crash.patch context for Firefox 158 Firefox 158 documented SessionStore.maybeDontRestoreTabs with a JSDoc block, so the guard applied only with fuzz. The guard is unchanged. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * Port webrtc-ip-spoofing.patch's include to Firefox 158 Bug 2072208 removed NS_PRINTING and the nsIPrintSettings.h include that followed xpcpublic.h in nsGlobalWindowInner.cpp. WebRTCIPManager.h is still included after xpcpublic.h. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * Qualify webgl-spoofing's dom names in ClientWebGLContext.cpp ClientWebGLContext.cpp declares no 'using namespace mozilla::dom'. It compiled on Firefox 157 only because CanvasImageCache.cpp, earlier in the same unified dom/canvas chunk, did. Bug 2048943 removed that directive ahead of renaming nsRange to dom::Range, so the patch now names RoverfoxStorageManager, WorkerPrivate and WebGLParamsManager with their dom:: namespace. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * Record Firefox 158.0's content-accessible files and chrome names The contentaccessible-parity guard compares a build against what stock Firefox of the same version exposes to pages, and refuses a manifest recorded from another release. Regenerated with scripts/gen-contentaccessible-manifest.py from the official 158.0 Linux x86_64 build (BuildID 20261007201254). Among the changes, Firefox 158 no longer registers the extra-themes-previews resource host (bug 1990883 removed colorways). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * Claim EXT_polygon_offset_clamp where Firefox 158 exposes it Bug 1854003 added EXT_polygon_offset_clamp to WebGL1 and WebGL2 wherever the GL backend clamps polygon offsets (GLFeature::polygon_offset_clamp: GL 4.6, ARB_ or EXT_polygon_offset_clamp). fpgen's records come from Firefox 146, so no identity claimed it, and stock-gpu-parity found stock 158.0 exposing it on this Linux host where Camoufox did not. - Windows: ANGLE's D3D11 backend sets polygonOffsetClampEXT from feature level 10_0 (renderer11_utils.cpp), which WebGL2 needs, so devices with WebGL2 claim it. - Linux: Mesa (radeonsi, llvmpipe on this host, in GL and GLES contexts) and NVIDIA's GL 4.6 driver expose it. Recordings from a desktop GL profile, marked by EXT_depth_clamp (96.6% of Linux records), claim it; the GLES-only records keep what the device reported. - macOS: release builds keep webgl.disable-angle and run WebGL on CGL's GL 4.1, which lacks it. Metal ANGLE is Nightly-only (bug 2072535). Both launchers place it in Firefox's alphabetical extension order. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * Expect EXT_polygon_offset_clamp from the backends Firefox 158 adds it on The converter and draft-extension tests hard-coded Firefox 156's backend extensions. The GTX 980 Linux fixture's expected lists now include EXT_polygon_offset_clamp in Firefox's order, and the Windows device with WebGL2 expects it beside EXT_depth_clamp; every other assertion is unchanged. A new test derives the expectation for 100 draws per OS from each draw itself: Windows devices with WebGL2, Linux desktop GL recordings, never macOS. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Gate-Change: Firefox 158 (bug 1854003) exposes EXT_polygon_offset_clamp where GLFeature::polygon_offset_clamp holds, and ANGLE D3D11 sets it from feature level 10_0; verified in the 158.0 source (dom/canvas/WebGLExtensions.cpp, gfx/gl/GLContextFeatures.cpp, third_party/angle renderer11_utils.cpp) and by stock-gpu-parity against stock 158.0 on this host * Follow Firefox 158's WebSocket frame callbacks in Juggler Bug 1719394 added the HTTP channel ID to nsIWebSocketEventListener.frameReceived and frameSent, ahead of the frame. Juggler's listener still took (serialID, frame), so it read the channel ID as the frame, found no opCode and dropped every frame: Playwright's framereceived and framesent events never fired (test_websocket.py::test_should_emit_frame_events and test_should_reject_wait_for_event_on_close_and_error failed on 158 and pass on 156.0.1). The listener now takes the new argument. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * Key Juggler's pending promises by their Debugger.Object Bug 2044184 removed Debugger.Object.promiseID in Firefox 158. Juggler keyed the promises it awaits by it, so every pending promise shared the key undefined: a second awaited evaluate overwrote the first, which then never resolved. Playwright waits that poll in the page (waitForElementState, selectText waiting for visibility) hung whenever another evaluate returning a promise ran meanwhile. The Debugger.Object is unique per promise within the debugger and serves as the key instead. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * Keep the environment out of forked children's command lines Firefox's setproctitle() marks the end of the old argv space so the kernel shows only the new title, then copies the environment strings right after the title, inside that space. When an environment string's null lands on the marker, the kernel shows the whole space: the title followed by the environment. Whether it does depends only on the length of the install path and of the environment, so it is rare in stock Firefox. The Firefox 158 package at the parity harness's path hit it on the RDD process, whose /proc/PID/cmdline then ended in the launching shell's environment instead of 'rdd'. The marker is set again after the copy; it lies outside /proc/PID/environ, which is unchanged. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
camoufox (Python)
The Python launcher for the Camoufox anti-detect browser.
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
| Requirement | Value |
|---|---|
| Python | 3.10 or newer |
| Playwright | below 1.63 (installed as a dependency) |
geoip extra |
needed for geoip=; downloads the GeoIP All-in-One database, refreshed once it is a week old |
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.
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, 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")
NewContext argument |
Effect |
|---|---|
preset |
Use this fingerprint preset dict instead of an fpgen draw. |
os |
"windows", "macos" or "linux" for the drawn identity. On a browser without canvas noise, the host's OS, and anything else raises ValueError. |
ff_version |
Firefox major version claimed in the User-Agent. Defaults to the browser's own. |
webrtc_ip |
IPv4 or IPv6 address WebRTC reports. |
proxy |
Per-context proxy, in Playwright's format. Unless webrtc_ip and timezone_id are both given, they are looked up from the proxy's exit IP, and InvalidIP is raised if the lookup fails. |
geolocation |
{"latitude": ..., "longitude": ...}; also grants the geolocation permission. |
| anything else | Passed to Playwright's new_context(), overriding the generated value. |
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 ofprivacy.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 aLeakWarning; 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
headless= |
What runs | Notes |
|---|---|---|
False (default) |
A normal window | Needs a display. |
True |
Firefox headless | Camoufox patches the headless tells it knows about. |
"virtual" |
A headed browser on a private Xvfb display | Linux only, needs Xvfb and setpriv (util-linux). Handled by Camoufox, AsyncCamoufox, NewBrowser and launch_server. The display is 1x1 unless CAMOUFOX_VIRTUAL_DISPLAY_SIZE (e.g. 1920x1080x24) says otherwise. Xvfb has no GPU: canvas and WebGL render in software. |
"virtual-gpu" |
A headed browser on a private, headless Xorg server bound to one GPU | Linux only, needs Xorg and the card's driver. Canvas and WebGL render on the card. Handled like "virtual". See The GPU display. |
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=(orCAMOUFOX_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:deviceids (10de:2c02) or a vendor name (nvidia). With several GPUs and no selector the launch raisesAmbiguousGpuSelection;GpuNotFoundandNoGpuFoundmean what they say.python -m camoufox gpu-xorg-configlists 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/X11and needsallowed_users=anybodyandneeds_root_rights=yesin/etc/X11/Xwrapper.config. Stock Debian and Ubuntu shipallowed_users=console, which refuses a launch from ssh, systemd or a container. One command installs Xorg and the wrapper (withapt-get; elsewhere it says what to install), sets those two lines and installs the card's config. It is safe to run again: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.python -m camoufox gpu-setup 0000:01:00.0 | sudo shgpu-xorg-configprints 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 andGpuSoftwareFallbackis raised;require_gpu=Falsewarns 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
DISPLAYand the X11 backend, and nothing that chooses a GL driver. These prefs default on, andfirefox_user_prefswins:gfx.webrender.all,layers.acceleration.force-enabled,gfx.x11-egl.enabled,gfx.canvas.acceleratedandgfx.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()).
| Option | Type | Default | Effect |
|---|---|---|---|
os |
str or list[str] |
fpgen's real-world mix | "windows", "macos", "linux", or a list to pick from. |
headless |
bool, "virtual" or "virtual-gpu" |
False |
See Headless modes. |
gpu |
str or int |
CAMOUFOX_GPU, or the only GPU |
The card for headless="virtual-gpu". See The GPU display. Not taken by launch_options. |
require_gpu |
bool |
True |
With headless="virtual-gpu", fail the launch when the browser does not render on the card; False warns. Not taken by launch_options. |
proxy |
dict |
none | Playwright proxy: server, username, password, bypass. |
geoip |
bool or str |
none | True finds the public IP (through proxy if set); a string uses that IP. Sets timezone, locale, geolocation and the WebRTC IP. Without a proxy, also decides whether IPv6 stays on. Needs the geoip extra. |
geoip_db |
str |
the camoufox set --geoip choice |
GeoIP database name, e.g. "GeoIP AIO by daijro". |
locale |
str or list[str] |
from geoip, else the drawn identity's |
Locale(s), e.g. "en-US" or ["fr-FR", "en-US"]. The first is used for Intl. |
humanize |
bool or float |
off | Human cursor movement. A number caps one movement at that many seconds (default cap 1.5). |
screen |
camoufox.fingerprints.Screen |
the real display when headed | Bounds the generated screen: Screen(max_width=1920, max_height=1080). |
window |
(int, int) |
generated | Fixed outer window size. |
fonts |
list[str] |
none | Extra font families on top of the OS's own. |
custom_fonts_only |
bool |
False |
Use only fonts, not the OS fonts. Warns: the font set no longer matches the OS. |
addons |
list[str] |
none | Paths to extracted Firefox addons (folders with a manifest.json). |
exclude_addons |
list[DefaultAddons] |
none | Default addons to leave out, e.g. [DefaultAddons.UBO]. |
block_images |
bool |
False |
Block image loading. Warns: some WAFs detect it. |
block_webrtc |
bool |
False |
Disable WebRTC entirely. |
block_webgl |
bool |
False |
Disable WebGL. Warns: many WAFs check for it. |
webgl_config |
(vendor, renderer) |
drawn | Use one GPU fpgen has recorded for Firefox on os (see camoufox.webgl.firefox_gpus); any other pair raises ValueError. Needs os. |
canvas_noise |
bool |
on for another OS or GPU | Random canvas and WebGL readback, as in LibreWolf. Warns. See The canvas on another OS. |
disable_coop |
bool |
False |
Turn off Cross-Origin-Opener-Policy so elements in cross-origin iframes (such as the Turnstile checkbox) can be clicked. Warns. |
main_world_eval |
bool |
False |
Allow page.evaluate("mw:...") and mw: init scripts to run in the page's own world. |
allow_addon_new_tab |
bool |
False |
Let addons open tabs. |
enable_cache |
bool |
False |
Keep Firefox's page and request caches. Uses more memory. |
pin_cpu_cores |
bool |
False |
Linux and Windows: pin the browser to as many cores as navigator.hardwareConcurrency claims, so a page timing parallel workers measures the same number. Costs CPU and serializes concurrent launches. |
fingerprint |
fpgen fingerprint dict |
drawn | Use this fpgen fingerprint instead of drawing one. Warns. |
fingerprint_preset |
bool or dict |
None |
Opt into a recorded real-device preset instead of fpgen: True picks a random bundled one, a dict uses that one. |
ff_version |
int |
the browser's own | Firefox version to claim. Warns: a mismatch with the engine is detectable. |
config |
dict |
none | Raw Camoufox properties (properties.json). Overrides the generated identity; manual identity keys warn. |
firefox_user_prefs |
dict |
none | Extra Firefox prefs. |
args |
list[str] |
none | Extra browser command-line arguments. |
env |
dict |
a copy of the environment | Environment variables for the browser. |
executable_path |
str or Path |
the installed build | Use this binary. CAMOUFOX_EXECUTABLE_PATH sets it too. Raises with browser. |
browser |
str |
the paired build | Launch another installed build: "official/beta.20", "beta.20" or "134.0.2-beta.20". Never downloads; warns like camoufox set. |
virtual_display |
str |
none | Use an existing X display, e.g. ":99". |
i_know_what_im_doing |
bool |
False |
Silence the leak warnings above. |
debug |
bool |
False |
Print the config sent to the browser. |
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>.
| Command | Options | What it does |
|---|---|---|
fetch [VERSION] |
Install the paired build (or, after set, the latest in the chosen channel), or VERSION without making it active. Syncs first. |
|
sync |
--spoof-os auto|mac|win|lin, --spoof-arch auto|x86_64|i686|arm64 |
Refresh the list of available builds from every repository. |
set [SPECIFIER] |
--geoip, --release |
Pin a build (official/stable/134.0.2-beta.20) or follow a channel (official/stable). No specifier opens a picker. --geoip picks the GeoIP database instead; --release goes back to the paired build. |
active |
Print the active build. A build that is chosen but not downloaded is marked (not fetched). |
|
list [installed|all] |
--path |
List installed builds, or every available one, as a tree. |
remove [VERSION] |
--select, -y/--yes |
Remove one build, pick one interactively, or (with no argument) the whole data directory. |
version |
Package versions (Camoufox, fpgen, Playwright), the active build and whether it is the latest in its channel, the GeoIP database, and storage paths and sizes. | |
path |
Print the data directory (~/.cache/camoufox on Linux). |
|
test [URL] |
--executable-path PATH |
Open a headed browser with the Playwright inspector. |
server |
Start a Playwright server with default options and print its websocket endpoint. | |
gpu-setup [GPU] |
Print the root script that sets this machine up for headless="virtual-gpu" on the card GPU names (or CAMOUFOX_GPU). Run it with | sudo sh. |
|
gpu-xorg-config [GPU] |
Print the Xorg config headless="virtual-gpu" needs for the card GPU names (or CAMOUFOX_GPU). |
set and fetch read builds from these repositories (repos.yml):
| Name | Repository |
|---|---|
| Official | daijro/camoufox |
| CoryKing | coryking/camoufox |
| JWriter20 | JWriter20/camoufox |
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.