Camoufox in Python: Setup, Proxies and Where It Stops
Camoufox is an open-source Firefox build that changes fingerprint values inside the browser engine rather than patching them with injected JavaScript, and it ships a Python library that speaks the Playwright API. That combination is what makes it interesting for scraping: a page that inspects navigator, screen, WebGL or fonts sees values that behave like native ones, and Playwright's own helpers stay out of the page.
This guide walks through a working setup: installing the library and the patched browser, running a first scraper against a bot-detection page, keeping a proxy's exit IP, timezone and locale in agreement, clicking a Cloudflare Turnstile checkbox, reusing a clearance profile, panning Google Maps, and saving a login session. It closes with the limits that decide whether Camoufox is the right tool for a given target.
Before you start, decide what you are actually testing. A fingerprint problem, an IP reputation problem and a stalled automation pipe all look like "blocked" from the outside, and they need different fixes. The checklist and failure table below are there to keep those three apart.
What Camoufox is, and what it is not
Camoufox patches Firefox at the C++ level, so spoofed properties such as navigator, screen, WebGL, fonts, audio and geolocation still report as native code when a page inspects them. The Python package drives that browser through the Playwright API, which means existing Playwright locators and waits carry over; only the launcher changes.
The mechanism matters more than the feature list. Playwright controls Chromium over the Chrome DevTools Protocol, which leaves traces a page can look for. For Firefox it uses a separate protocol called Juggler, and Camoufox patches Juggler so Playwright works on an isolated copy of the page. Site scripts cannot see the helpers Playwright would normally inject, and input events pass through Firefox's native handlers. Chromium stealth plugins try to hide the same traces with JavaScript after the fact, which is itself detectable.
Two things Camoufox is not. It is not a commercial anti-detect browser with profiles, a desktop app and per-seat pricing; it is a library plus a patched browser that you drive from code. And it is not a CAPTCHA service. It can make a checkbox clickable, but it does not solve puzzles for you.
Install the library and the patched browser
Installation is two downloads: pip brings the Python library, and a separate fetch command pulls the patched Firefox build where the stealth work lives. In a fresh virtual environment on Python 3.10 or newer, the short version is three commands: install the package with the geoip extra, fetch the browser, then confirm what you ended up with.
The geoip extra supplies what Camoufox needs to map a proxy's exit IP onto a consistent timezone, locale and location. Its lookup database (MaxMind GeoLite2, 43.4 MB in the tested environment) arrives with the browser during the fetch step. Plan for the download size: the macOS build expands to 639 MB and the Linux build to 1.2 GB, and the macOS fetch took a little over 30 minutes on the tested connection. Fetch once per machine or bake it into your Docker image; never fetch at scraper startup.
Two installation traps are worth knowing before you debug anything else. First, Python 3.9 does not fail; it quietly resolves to an older library line that predates the version manager, fingerprint presets and per-context identities. If the version command later reports that older release, your interpreter is the reason. Second, install the package under its own name, not the similarly named fork that writes to the same import; whichever you installed last wins.
On a slim Linux server or container the browser also needs GTK, X11 and audio libraries, plus Xvfb if you want the virtual display mode. The Dockerfile in the accompanying module shows a tested Debian bookworm setup, including a guard line after the fetch. That guard exists because the fetch looks up releases through GitHub's API, and when that API rate-limits you it can exit successfully without installing a browser, which Docker then caches as an empty layer. If you build often, supply a GitHub token for the fetch step.
For production, pin both halves: the browser build with the version manager and the Python package in your requirements file. A new browser build should not change how your scraper behaves until you decide to test it.
A first scraper: read a bot-detection page
A better first target than a quotes site is a page whose whole job is catching bots. BrowserScan runs a set of automation checks and labels each one Normal or Robot, so the data you scrape is the verdict on your own browser. The scraper in the accompanying module reads 17 of those checks.
The launcher is the only Camoufox-specific part, and each argument earns its place. Headless mode is patched so it does not advertise itself. The operating-system list tells Camoufox which platforms it may impersonate; it picks one per launch and generates a matching user agent, platform, fonts and GPU. The screen cap stops a scraper from rendering a 4K layout. Humanized mouse movement applies whenever your code clicks or hovers.
Notice what is missing: no user agent string, no navigator values, no window size, no config dictionary. Camoufox generates those as one consistent set, and hardcoding them is the fastest way to break that consistency.
Two practical notes from building it. BrowserScan's class names are hashed and change between deployments, so anchor on the visible heading text and walk up to the card instead. And a role-based wait can match more than one element when an FAQ heading contains the same word; adding an exact match fixes the strict-mode violation.
On the captured run, all 17 checks came back Normal with a Firefox 152 user agent that matched the engine underneath. Stock Playwright Firefox and Chromium, run headless from the same machine, both reported WebDriver: Robot. The property behind that flag returned true in the stock browsers and false in Camoufox, because it is removed at the engine level rather than patched over with JavaScript.
If your stack is already built on Playwright, you do not have to rewrite it around this launcher. The library can return its executable path, arguments, preferences and fingerprint environment as a dictionary you can hand to a plain Playwright Firefox launch, and the same dictionary is what Playwright-based frameworks expect as launch options.
Scaling out: one process per worker
The async API uses the same launcher under a different import and is the right starting point for more than a handful of pages, or for running Camoufox inside an async web framework. It is also where Playwright habits mislead you.
The textbook pattern, one browser with pages created from parallel coroutines, stalled on the first navigation until the timeout fired. Creating pages one at a time and then navigating them concurrently worked on a laptop but timed out on every page inside a Linux container, even after raising shared memory. Both failures trace to the same place: every tab's commands travel over one automation pipe, and that pipe can go unresponsive while the browser process stays alive.
The version that worked on both machines gives each worker its own Camoufox process and one page. That is heavier than tabs, and it is still the right trade for Camoufox, because it also matches how stealth should be structured: one browser, one fingerprint, one proxy.
The error handling is not boilerplate. In an earlier version, one timed-out page raised inside a worker, the worker task died, and the queue waited forever for URLs nobody was left to process. Catching the failure per URL keeps the worker alive and produces a retry list.
Timings from both machines, including launch time, are in the worker-timing table. Each run collected all 100 quotes across the 10 pages. On a job this small, gains level off beyond three browsers, since every additional browser adds a few seconds of launch overhead. Across a crawl of thousands of pages that overhead fades and RAM becomes the constraint, so set the worker count to fit your memory.
Proxies and geoip: make the location story agree
A proxy swaps out your IP address, but every other location signal a page can read stays as it was, and that mismatch is what exposes most proxied scrapers. A fingerprint claiming Windows and US English alongside a timezone taken from the machine's real location describes a device no real person uses.
Everything location-flavored has to agree with the exit IP: timezone, locale, Accept-Language, geolocation coordinates and the IP that WebRTC reports. The geoip option lines those up, and Camoufox warns if you pass a proxy without it.
The setup is three steps: install with the geoip extra, pass the proxy as a dictionary, and confirm the timezone the page returns matches the exit IP. Step three is not a formality. On the tested build, geoip computed the right timezone for a New York exit but the page kept reporting the machine's own timezone, headless and headful, on macOS and in a Debian container. Passing the same value as Playwright's timezone setting applied it immediately. Until that is fixed, look up the exit IP once, pin geoip to that IP, and pass the timezone yourself. Pinning also stops the fingerprint from drifting if the lookup and the launch take different routes, and a sticky proxy session ensures the IP you looked up is the IP your page loads from.
SOCKS5 works with one limit: the browser refuses to launch when the proxy requires a username and password. Use the provider's HTTP endpoint, switch the account to IP allowlisting, or run a small unauthenticated local forwarder that authenticates upstream for you. The older WebRTC leak concern is addressed on this build when geoip is set; blocking WebRTC entirely also stops the leak, but a browser with no WebRTC API is unusual, so treat that as a fallback for proxies you cannot geolocate.
Launching a whole browser per proxy is heavy. The per-context constructor creates a browser context with its own fingerprint and proxy inside one process, and it looks up the exit IP through that proxy to set the context timezone. It has its own trap: unlike the main launcher it does not default the fingerprint version to the running browser, and the fingerprint dataset stops at an older Firefox major version. Launched without extra arguments, a context reported a Firefox 150 user agent on a Firefox 152 engine. Pass the major version read from the running browser, not a two-part version string, which produces a user agent no real Firefox sends. If the context's IP lookup fails it carries on silently with no timezone set, so check the timezone from inside the page.
A flawless fingerprint on a bad IP still gets blocked. Anti-bot systems score IP reputation and network owner separately from what the browser reports, and datacenter ranges start low. The proxy-type table sets out the fit for each kind. The second decision is whether the IP stays put: use sticky sessions whenever state is tied to the IP, including logins, clearance cookies, multi-step flows and any launch where you looked up the exit IP. Rotate between contexts or browsers, not within one, because a single page load pulls dozens of resources and a page whose images arrive from five cities does not look human.
One bandwidth note: residential traffic is billed per gigabyte, and the obvious saving, blocking images, draws a warning about WAF detection issues. Lean on the bundled ad blocker instead.
Fingerprints, humanization and headless mode
Many older setups configure the browser by hand: a dictionary of navigator and window values, a hardcoded user agent, and a flag to silence the warnings. On the current build that pattern works against you. A hand-written dictionary with an old Firefox user agent produced four warnings before the page loaded, and then the page reported a user agent from one Firefox version on an engine from another, an outer window larger than the screen, a hand-picked CPU count, and a touch-point value silently dropped.
Part applied, part ignored, and the applied parts contradict each other. Consistency is the whole game, and the replacement is shorter: tell Camoufox which operating systems you will impersonate and how big a screen to allow, then let the fingerprint generator produce everything else as one consistent device drawn from real-world traffic distributions. If you would rather use fingerprints captured from real devices, a preset switch swaps generated values for bundled ones.
A few more options are worth knowing, and the launch-option table records how each behaved. Pinning a WebGL vendor and renderer pair works, but only use combinations valid for the chosen OS. Excluding the bundled ad blocker launches cleanly and helps when a site breaks without its scripts. Disabling WebGL and blocking images both draw warnings that map closely to checks anti-bot vendors run. Fixing the window size is a debugging tool, not a default, because a fixed size is itself a fingerprinting signal.
Headless mode is less of a detection difference than most guides suggest. On the tested build, windowed, headless and virtual-display modes all scored 0% on the headless check and 6% "like headless" in every run, because Camoufox patches headless Firefox to report itself like a windowed browser. The virtual display mode exists as insurance: it runs a real windowed Firefox inside an in-memory display, so no headless code path is left to detect. On a Linux server it costs one package and nothing else, and the browser manages the display itself. Do not copy that setting to macOS, where it stops the launch; choose the mode from the platform when the same code runs on both.
Clicking a Cloudflare Turnstile checkbox
Cloudflare's Turnstile checkbox lives inside a cross-origin iframe. Firefox's cross-origin opener policy handling keeps automation from interacting with that frame properly, and disabling that handling lets a click reach the checkbox. The explanation is easy to repeat and hard to believe without seeing it, so the captured test ran it on a live managed challenge with a "Verify you are human" checkbox.
Seven runs changed only that one setting. With it on, four of four runs passed in under two and a half seconds and the clearance cookie was set every time. With it off, none of three runs passed and the page was still on the interstitial after 30 seconds. That is about as clean an A/B result as live anti-bot testing gets.
The docs' example clicks fixed coordinates in a fixed window, and the first working version did too. Fixed coordinates depend on a fixed window, and a fixed window is its own fingerprinting risk. Without it, the window size changes each launch, and the checkbox frame moved by hundreds of pixels between runs. The version worth keeping finds the challenge frame and clicks relative to it.
The wait before clicking matters more than it looks. Clicking the instant the frame attached, before the widget inside it was ready, passed one run in four; with a short wait it passed every run.
The surprise was humanization. You would assume human-like cursor movement helps with a "verify you are human" checkbox. On this challenge it did not change whether the click passed, but it caused a failure no timeout could catch: in three of thirteen runs the click stalled inside the mouse call, past every Playwright timeout, and the process had to be killed from outside. Keep humanization off for a single checkbox click. Turn it on for multi-step flows on sites that score mouse behavior, and run those jobs under a watchdog that can kill the whole process, because a stalled click will not raise.
Disabling the cross-origin handling is not free either. Camoufox warns it can be detected by sophisticated WAFs, which is why the snippet acknowledges that. Turn it on for the pages where you need to click a challenge, not for every launch.
Reusing a Cloudflare clearance profile
A demo page isolates one behavior. A real protected site is where you find out whether the pieces hold together. On the captured run, a fresh browser was sent to a Cloudflare page before the company profile appeared.
The approach runs in two phases. Phase one solves the challenge a single time inside a browser profile written to disk. Phase two loads that same profile, which brings the clearance cookie with it, so later runs skip the checkbox. A persistent context keeps cookies, local storage and cache in a folder rather than throwing them away when the browser shuts down.
Phase one runs windowed on purpose, so that if the automatic click does not clear the challenge you can solve it by hand inside a 60-second window. It also pins the operating system, because phase two has to present the same user agent. On the captured run the automatic click did the job and both Cloudflare cookies were present.
Before building a scraper on top of that profile, confirm the cookie landed where you expect. Firefox keeps cookies in a SQLite file, and reading it directly still works. One change from older guides: the current Firefox stores the expiry column in milliseconds, so a query that skips the conversion returns blank dates. The clearance cookie was listed as valid for a year; the bot-management cookie expires after 30 minutes of inactivity. As the reuse tests show, the one-year date is the most it can last, not a promise.
Phase two opens the same profile headless and reads the page. The selectors come from the live page; several from the original article still worked, and the framework-generated classes it relied on are gone.
Then the profile was deliberately broken, and the results are in the clearance-survival table. Three lessons came out of it. The clearance followed the user agent, not only the cookie jar: changing the operating system changed the user agent and the stored cookie was challenged as if it belonged to someone else. An expiry date is not a lifespan: after a mismatch and a quick burst of repeat visits, the cookie with a one-year expiry stopped working even with the correct user agent, and the fix was to rerun phase one rather than wait. And the profile survives a change of environment, not a change of machine: a container on the same laptop and IP reused it fine, but clearance is tied to the device it was issued to, so run phase one on the server that will run phase two.
If you run both phases through a proxy, use a sticky session and keep the same exit IP across them.
Panning Google Maps for more listings
Google Maps exercises a different kind of target from the earlier examples: a large interactive single-page application whose contents shift as the viewport moves, so the scraper has to react to change rather than read one static document. The script is split into two halves for that reason. The first half supplies three helpers — one dismisses the consent interstitial, one turns result cards into records, and one records a signature of the visible list so a refresh can be detected. Parsing leans on accessible labels wherever Google provides them rather than on generated class names: the rating and review count are read from a single role=img label written for screen readers, of the form 4.7 stars 6,967 Reviews, which tends to outlive hashed classes such as MW4etd. The consent helper chooses Reject all, which reaches the map just as reliably as accepting and is the more privacy-preserving option for an automated browser. The second half loads the search, records the first batch of cards, ticks the Update results when map moves checkbox, and then moves the viewport north repeatedly until 15 distinct restaurants are on hand. Panning works because of a hint Google gives assistive technology: the map canvas carries a label stating that arrow keys pan the map, so the script focuses that element and sends arrow keys. Each pair of presses shifted the map north, which the latitude in the URL confirmed as it climbed, while the results travelled from Midtown through the Upper West Side to the Bronx. Two design choices keep the loop trustworthy. It waits for the list itself to change instead of sleeping for a fixed interval, so it proceeds the moment results refresh; on the captured run the first pan left the list unchanged, and the script panned again rather than logging duplicates. It also de-duplicates on the place link, since adjacent map views overlap and appending every card would overstate the total. From start to finish the run took 25 seconds and wrote 15 unique restaurants, each with a rating and a review count, to results.json. In the captured headless run the map tiles appeared black while the results panel was fully populated; that has no bearing on the scraper, because every field is taken from the results panel.
Saving and validating a login session
Certain data sits behind a sign-in: dashboards, saved searches, exports scoped to an account. The approach below applies to any site where the account is yours and its terms permit automated access, so review those terms before aiming it at a live service. The captured test ran against a public practice site that accepts any credentials, so every line can be executed without putting a real account at risk. The clearance walkthrough makes it tempting to log in inside the same persistent profile. That was the first attempt, and it broke in a way that is easy to overlook. The practice site authenticates with a session cookie that carries no expiry date, and browsers discard such cookies on shutdown. The profile directory came back after the restart; the session cookie did not, and the page offered the login link again. Many real sites authenticate exactly this way, including plenty that offer no remember-me option. The lesson is not to depend on the profile for authentication. Capture the cookies yourself once signed in and reinstate them at the next launch, session cookies included, since the browser would otherwise drop them on exit. Credentials belong in environment variables so they never land in source code or a repository. The saved cookie file deserves the same care as a password: it holds live authentication cookies, so keep it out of version control and never leave it on a machine you share. A stored session can also lapse silently. The site may sign you out after a period, invalidate sessions when you log in elsewhere, or rotate cookies after a password change. A scraper that simply assumes it is authenticated will cheerfully collect the logged-out version of every page. That is why the script never takes the saved file at face value: it loads a page and looks for something only a signed-in visitor would see before any scraping begins, and when that check fails it signs in again and rewrites the saved cookies. The four-run validation table shows this recovery path in action, including a deliberately corrupted cookie. Choose a check suited to your site. A good one is inexpensive, unique to authenticated users, and sits on a page you were going to load regardless: an element only signed-in users see, a redirect to a login URL, or a response from an account endpoint. If validation fails more than once in succession, halt and raise an alert rather than retrying indefinitely, because a burst of login attempts from an automated browser is precisely the pattern account-security systems are built to catch.
Where Camoufox stops
Up to this point the focus has been making Camoufox work. This section covers where it stops working, since a tool whose boundaries you have not mapped can let you down on the target that matters most. For detection reports, the project asks for one comparison: run unmodified Firefox through Playwright from the same IP, which tells a browser-side failure apart from an IP-side one. The pass-and-fail table applies that comparison to every test with a pass/fail outcome. Two omissions there are intentional: DataDome, Akamai and Kasada went untested, because no public test page was available that could be hit repeatedly with permission. For those vendors, the maintainers' detection tracking issue gathers dated, versioned reports. The partial fingerprint score represents the realistic ceiling of spoofing. Even with IP, timezone and language aligned, the detection page still noted that the underlying browser did not match the operating system and user agent it claimed. Long before any HTML arrives, the TLS handshake discloses which browser engine is connecting, condensed into a JA3 or JA4 fingerprint, and the HTTP/2 settings add a second fingerprint. Camoufox alters neither. Its TLS and HTTP/2 fingerprints match stock Firefox exactly and differ from Chromium. That cuts both ways. The upside is that the network layer offers an authentic Firefox handshake, something most plain HTTP-client scrapers cannot claim. The downside is that a Camoufox session can never present a Chrome handshake at that layer. Where a target's rules anticipate Chrome, setting a Chrome user agent inside Camoufox only widens the inconsistency, and no Camoufox option repairs it. For targets that need no JavaScript at all, a client that impersonates browser TLS directly is the lighter route. Camoufox also provides no CAPTCHA solver. The Turnstile results are the favourable case: one checkbox, clickable once the cross-origin handling is disabled, with no puzzle behind it. When Cloudflare escalates to an interactive challenge, or a site relies on another CAPTCHA vendor, nothing built in will help. The choices are to solve once by hand and persist the session, or to connect a solver service. Firefox's modest market share becomes a signal at scale. Anti-bot systems also ask whether your traffic resembles everyone else's. At a few hundred requests that is immaterial; at a million requests a day from one network, all Firefox, you stand out statistically even if every session is flawless. Finally, the maintainers describe the browser as possibly unsuitable for production. The rough-edges table lists what was encountered on the tested build and the workaround for each. None of it argues against using Camoufox; it argues for treating an upgrade like a dependency change: pin the browser and the package, rerun a short canary suite against every new build, and keep a watchdog around any job that clicks.
A pre-launch consistency checklist
Run this before you trust any Camoufox launch against a protected target. Each line maps to a failure that was actually observed, not a hypothetical.
- Interpreter and package. Confirm Python 3.10 or newer and that the version command reports the library line you intended. A silent downgrade on an older interpreter is the first thing to rule out.
- Browser build. Confirm the fetched browser is installed, not just that the fetch exited successfully. Pin the build you tested.
- Exit IP. Look up the exit IP through the proxy once, and pin geoip to that value so the fingerprint cannot drift between lookup and launch.
- Timezone. Read the timezone from inside the page and compare it with the exit IP's timezone. If they disagree, pass the timezone explicitly; do not assume geoip applied it.
- Locale and language. Confirm the page reports the language you expect for that exit IP.
- WebRTC. Confirm the IP the page learns over WebRTC is the proxy's exit IP, not your real one.
- User agent versus engine. Confirm the user agent's major version matches the running browser. This is the trap in per-context launches and in hand-written config dictionaries.
- Session stickiness. If state is tied to the IP, use a sticky session and keep the same exit IP across every phase of the job.
- Clearance reuse. If you reuse a clearance profile, keep the same operating system and user agent, and run both phases on the same machine.
- Click jobs. Run any job that clicks under a process-level watchdog, because a stalled click does not raise.
Four failures that look the same and are not
When a Camoufox job stops returning data, the cause is usually one of four things. Diagnosing which one saves you from changing the wrong setting.
An anti-bot block looks like a challenge page, a 403, or a 429. The page loads and shows an interstitial, or the response status tells you the request was refused. The fix is on the identity side: IP reputation, session stickiness, user agent consistency, or a fresh clearance run. Changing your fingerprint settings will not help if the IP is the problem.
A stalled automation pipe looks like a navigation or a click that never completes, with no timeout firing. The browser process is alive and the page may even be rendered, but commands stop travelling. This is the failure behind parallel page creation, concurrent tabs in a container, and the humanized click that hung past every timeout. The fix is structural: one process per worker, create pages one at a time, keep humanization off single clicks, and wrap click jobs in a watchdog.
A stale session looks like a successful page load with logged-out content. Nothing errors; the data is just thin or missing. The fix is to validate the session on every run against something only a signed-in user sees, and to re-authenticate when the check fails rather than retrying blindly.
A version mismatch looks like a detection score that is worse than expected while everything else is configured correctly. The page sees a user agent from one Firefox version on an engine from another, or a two-part version string no real browser sends. The fix is to read the major version from the running browser and pass that, and to stop hand-writing fingerprint dictionaries.
Frequently asked questions
| Tool | Browser engine | How it's driven | Latest release (as of Sep 2026) | Strength | Best for |
|---|---|---|---|---|---|
| Camoufox | Firefox (patched) | Playwright API over Juggler | 0.5.6, Sep 6, 2026 | Engine-level fingerprint spoofing | Fingerprint-heavy targets, a Firefox identity |
| Patchright | Chromium | Drop-in Playwright replacement | 1.62.3, Sep 2, 2026 | Patches Playwright's CDP leaks with no API changes | Existing Playwright code that needs a Chrome identity |
| Nodriver | Chrome | Async, direct CDP, no WebDriver | 0.50.3, May 13, 2026 | Lean async control of a real Chrome | Async Chrome scraping where you manage the IP layer |
| SeleniumBase UC Mode | Chrome | Selenium-based, with a newer CDP Mode for stealth | 4.54.4, Sep 13, 2026 | Built-in CAPTCHA click helpers | Checkbox CAPTCHAs, teams already on Selenium |
| Playwright stealth plugins | Mostly Chromium | JavaScript patches over Playwright | Python playwright-stealth 2.0.3, Apr 2026 | Easiest to add to existing code | Low-protection targets |
Release dates and versions are a September 2026 reference; check current releases before choosing a tool.
| Your Python | What pip install camoufox gives you |
|---|---|
| 3.9 | camoufox 0.4.11, from January 2025 |
| 3.10 or newer | camoufox 0.5.6, from September 2026 |
No error or warning is printed on 3.9; check python -m camoufox version if you are unsure.
| SOCKS5 setup | Result |
|---|---|
| No authentication ( socks5://127.0.0.1:1090 ) | Page loaded through the proxy |
| Username and password | BrowserType.launch: Browser does not support socks5 proxy authentication |
Observed on the September 2026 build; the browser refuses to launch when SOCKS5 credentials are supplied.
| Setup | IP the page learned over WebRTC |
|---|---|
| No proxy | My real public IP |
| HTTP proxy with geoip set | The proxy's exit IP |
| SOCKS5 proxy with geoip set | The proxy's exit IP |
| HTTP proxy without geoip | No public candidate at all |
| block_webrtc=True | RTCPeerConnection does not exist |
Measured with a STUN request run from inside the page on Firefox 152.
| Proxy type | Where the IPs come from | Fit for Camoufox |
|---|---|---|
| Datacenter | Cloud and hosting providers | Unprotected sites and testing only; flagged by ASN on most protected targets |
| ISP (static residential) | Residential ISP ranges hosted in data centers | Logins and long sessions that need one stable, clean IP |
| Residential | Real home connections | The default for Cloudflare- and DataDome-protected targets |
| Mobile | Carrier networks, often shared by many real users behind one IP | Hardest targets; blocking one IP risks blocking real customers |
A general fit guide; IP reputation is scored per target, so test against the site you actually need.
| Session setting | Exit IPs across 4 requests |
|---|---|
| Rotating (no session ID) | 4 different IPs |
| Sticky (session ID set) | The same IP, 4 times |
Observed through one US gateway; session identifiers are provider-specific.
| Option | What it does | What I saw |
|---|---|---|
| webgl_config=("Apple", "Apple M1, or similar") with os="macos" | Pins a WebGL vendor and renderer pair | The page reported exactly that pair. Only use combinations valid for the chosen OS |
| exclude_addons=[DefaultAddons.UBO] (with from camoufox import DefaultAddons ) | Removes the bundled uBlock Origin | Launched cleanly, no warning. Useful when a site breaks without its scripts |
| block_webgl=True | Disables WebGL | Warning: "Many WAFs will check if WebGL is enabled" |
| block_images=True | Skips image downloads | Warning: "reported to cause detection issues on major WAFs" |
| window=(1280, 720) | Fixes the window size | Camoufox's docs warn that a fixed size can lead to fingerprinting; keep it for debugging |
Warnings are Camoufox's own; they map closely to checks anti-bot vendors run.
| Setting | Where it runs | CreepJS "headless" score in my runs | When to use it |
|---|---|---|---|
| headless=False | Any desktop | 0% (macOS) | Debugging and solving a challenge by hand the first time |
| headless=True | macOS, Windows, Linux | 0% (macOS and Linux) | Most scraping, anywhere |
| headless="virtual" | Linux only | 0% (Linux) | Linux servers, as insurance against future headless detection |
All three also scored 6% "like headless" in every run; headless="virtual" raises VirtualDisplayNotSupported on macOS.
| Change on the reuse run | Result |
|---|---|
| Same profile, same os="windows" , headless on macOS | HTTP 200, data extracted |
| Same profile copied into a Debian container with headless="virtual" , same public IP | HTTP 200, data extracted |
| Same profile, os="macos" (a different user agent) | Challenged again, HTTP 403 |
| Back to os="windows" after that, within a few minutes | Challenged again, HTTP 429 |
| Phase one rerun, then phase two | HTTP 200, data extracted |
Single-site observations from September 2026; clearance can be revoked early regardless of the expiry date.
| Test | What it checks | Camoufox 0.5.6, Firefox 152 | Stock Playwright Firefox, same IP |
|---|---|---|---|
| CreepJS (headless) | Headless and stealth tells | 0% headless | 33% headless |
| BrowserScan bot detection | 17 automation checks read by the scraper | 0 flagged | WebDriver: Robot |
| NopeCHA Cloudflare demo | Managed challenge with Turnstile | Passed with disable_coop (every run) | No clickable checkbox rendered, not passed |
| Crunchbase company profile | Cloudflare Turnstile on a real site | Passed on the first click, reused for later runs | No clickable checkbox rendered, not passed |
| BrowserScan through a US residential proxy | Location and fingerprint consistency | Timezone and IP matched; 75% to 80% authenticity | Not run |
| TLS fingerprint ( tls.peet.ws ) | JA3, JA4, HTTP/2 | Identical to stock Firefox | Reference |
DataDome, Akamai and Kasada were not tested; the maintainers' detection tracking issue collects dated reports for those vendors.
| What I hit | Where it's covered | Workaround |
|---|---|---|
| geoip computed the timezone but didn't apply it | Proxy section | Pass timezone_id or use NewContext() |
| NewContext() reported Firefox 150 on the 152 engine | Proxy section | ff_version=browser.version.split(".")[0] |
| Creating pages from parallel coroutines hung ( #553 ) | Async section | Create pages one at a time |
| Concurrent tabs failed in a Linux container (related: #719 ) | Async section | One Camoufox process per worker |
| mouse.click() hung with humanize=True , past every timeout | Turnstile section | humanize=False for single clicks, plus a process-level watchdog |
| Python 3.9 silently installs the 2025 release | Install section | Python 3.10+ and a pinned version |
Reported by the maintainers as possibly unsuitable for production; pin both halves and rerun a short canary suite on each upgrade.
Frequently asked questions
Can Camoufox bypass Cloudflare Turnstile?
For the checkbox challenge, yes in the tests behind this guide. With disable_coop=True, a click on the Turnstile frame passed on a Cloudflare demo and on Crunchbase, and the cf_clearance cookie could be reused later. Clearance is tied to the device it was issued to and, in these tests, to the user agent; Cloudflare can revoke it early, and no setup is guaranteed.
Can Camoufox bypass DataDome?
Sometimes, depending on the deployment, but no public DataDome test page was available to verify it. DataDome scores IP reputation, behaviour and TLS, and Camoufox's TLS fingerprint is a standard Firefox profile it cannot change. Expect to need clean residential or mobile IPs and session continuity, and plan on a managed scraping API for hard DataDome sites.
Can I use Camoufox with Node.js or JavaScript?
Partly, and only as an experiment. A JavaScript port is maintained separately and labels itself experimental; its most recent release, 0.12.0, arrived in July 2026. A second route exists on the Python side: the library can expose Camoufox as a Playwright server, and any Playwright client, including a JavaScript one, can connect to that server. Between the two, the Python library is the integration that sees the most active development, so treat JavaScript support as viable for prototyping rather than as a drop-in replacement.
{
"name": "ScrapingBee",
"description": "Example post details.",
"Growth Score": 77,
"CB Rank": 207768,
"Heat Score": 48,
"industries": [
"Computer",
"Developer APIs",
"Software",
"Web Design"
]
}
| Browsers | macOS (Apple Silicon) | Debian container |
|---|---|---|
| 1 | 8.4s | 8.4s |
| 3 | 5.6s | 5.0s to 5.3s |
| 5 | 6.7s | 5.3s |
Measured on a ten-page job; every run returned all 100 quotes from all 10 pages.
| disable_coop | Mode | Runs | Passed the challenge | cf_clearance cookie |
|---|---|---|---|---|
| True | Headless and headful | 4 | 4 of 4, in 1.9 to 2.3 seconds | Set every time |
| Not set | Headless and headful | 3 | 0 of 3, still on "Just a moment..." after 30 seconds | Never set |
Run on the NopeCHA Cloudflare demo with humanize=True and a fixed 1280-by-720 window.
| humanize | Runs | Passed | Hung inside mouse.click() |
|---|---|---|---|
| False | 11 | 11 | 0 |
| True | 13 | 10 | 3 |
In the hung runs no Playwright timeout fired; the process had to be killed from outside.
| Run | State before the run | What the script did |
|---|---|---|
| 1 | No session.json | Logged in, saved cookies |
| 2 | Valid saved session | Skipped login |
| 3 | Session cookie value corrupted | Detected the bad session, logged in again, saved new cookies |
| 4 | Fresh saved session | Skipped login |
Tested against a public practice site that accepts any credentials.