How to install and use FlareSolverr with Docker, Python & proxies
Cloudflare blocks a lot of scrapers before they even see a page. FlareSolverr is one of the tools people reach for when a plain HTTP client keeps getting a challenge page instead of real content.
This guide is for developers who already know the basics of scraping but have never set up FlareSolverr. You will learn what it does, how to install it, how to call its API, and where it runs into trouble.
We will also cover proxies. FlareSolverr solves the browser challenge, but the IP behind that browser still matters a lot.
Improve FlareSolverr success with clean residential and mobile proxies. Try NodeMaven from $3.50 with 750 MB included
Key takeaways
- FlareSolverr is a free, open-source proxy server that uses a real browser to solve Cloudflare and DDoS-Guard challenges.
- It runs best as a Docker container and exposes a simple REST API on port 8191.
- Sessions let you reuse a solved browser instance instead of paying the challenge cost on every request.
- FlareSolverr cannot solve CAPTCHAs on its own. It only handles JavaScript and browser fingerprint checks.
- The IP reputation behind FlareSolverr affects how often Cloudflare challenges you in the first place.
- Residential proxies reduce challenge frequency far more than datacenter IPs, especially on strict sites.
What is FlareSolverr?
FlareSolverr is an open-source proxy server built to get past Cloudflare and DDoS-Guard protection. It sits between your scraper and the target site, and it exposes a REST API that looks a lot like a normal HTTP request.
Under the hood, it drives a real Chrome browser through Selenium with an undetected driver. That matters because Cloudflare’s checks look at browser behavior, not just headers.
Typical use cases include:
- Scraping sites protected by Cloudflare’s managed challenge or JS challenge
- Grabbing a clearance cookie to reuse in a lightweight HTTP client afterward
- Automating access to sites that block plain requests libraries like requests or httpx
Good to know: FlareSolverr is a proxy layer, not a full scraping framework. You still write your own scraping logic. FlareSolverr just hands you the HTML once the challenge is out of the way.
How FlareSolverr works
The flow is straightforward once you see it laid out.
- Incoming request. Your script sends a POST request to FlareSolverr’s local API with a target URL.
- Browser launches. FlareSolverr opens a Chrome instance (or reuses one from an active session).
- Cloudflare challenge. The browser navigates to the URL and waits while Cloudflare runs its checks.
- Cookies issued. Once the challenge clears, Cloudflare sets a clearance cookie in the browser.
- Session handling. If you used a session, the browser and its cookies stay alive for reuse.
- HTML returned. FlareSolverr sends back the final page HTML, headers, cookies, and the user agent it used.
That last part matters. If you reuse the cookies in a different HTTP client, you need to match the user agent FlareSolverr reports, or Cloudflare throws the challenge again.
When should you use FlareSolverr?
FlareSolverr is not the right tool for every scraping job. It is slower and heavier than a plain HTTP client because it runs a full browser per request or session.
| Good fit | Poor fit |
| Sites behind Cloudflare’s JavaScript or Managed Challenge | Sites with no bot protection at all |
| Low to medium volume scraping jobs | High volume scraping that requires thousands of requests per minute |
| Obtaining a Cloudflare clearance cookie for reuse in subsequent requests | Sites protected by hard CAPTCHAs such as hCaptcha or reCAPTCHA |
| Occasional access to protected pages or stubborn API endpoints | Real time or latency sensitive workflows |
For large scraping jobs, a lighter approach (rotating proxies plus a lean HTTP client, only falling back to FlareSolverr for challenged requests) usually performs better than routing everything through a browser.
Installing FlareSolverr
Docker is the recommended install path. The image already bundles the browser, so you skip a long dependency chain.
Docker
This pulls the image, exposes port 8191, and restarts the container automatically if it crashes or the host reboots.
Docker Compose
Run docker compose up -d in the same folder to start it. Compose is worth using once you add more environment variables, since it keeps your config in one file instead of a long CLI command.
Verifying the installation
A working install returns a JSON object with a solution field containing the page HTML, status code, and cookies. If you get a connection error, check that port 8191 is actually mapped and not blocked by a firewall.
Key configuration options
| Variable | What it does |
| LOG_LEVEL | Controls logging verbosity. Set it to debug when troubleshooting issues. |
| PROXY_URL | Sets a default proxy for all requests unless a different proxy is specified for an individual request or session. |
| PROXY_USERNAME / PROXY_PASSWORD | Defines the authentication credentials used with the default proxy configured in PROXY_URL. |
| TZ | Sets the browser’s timezone and timestamps in logs. Matching it to your proxy location helps create more consistent browser fingerprints. |
| HEADLESS | Runs the browser in headless mode by default. Disable it only when debugging locally and you need to see the browser window. |
| TEST_URL | Specifies the URL FlareSolverr checks during startup to verify that the browser is working correctly. Change it if the default URL is blocked in your region. |
Using the FlareSolverr API
FlareSolverr exposes one endpoint, /v1, and you tell it what to do through a cmd field in the request body.
GET request
POST request
Add a postData field formatted as application/x-www-form-urlencoded
Python example
The response gives you the rendered HTML, the cookies Cloudflare set, and the exact user agent string the browser used. Keep all three together if you plan to make follow-up requests with a different HTTP client.
Watch out: if you reuse the clearance cookie with a mismatched user agent, Cloudflare shows the challenge again. Always pair the cookie with the reported user agent.
Power your FlareSolverr workflows with clean residential and mobile proxies. Try NodeMaven for $3.50 with 750 MB included
Managing sessions
Every request without a session spins up a fresh browser, solves the challenge, then throws the browser away. That works, but it is slow and wasteful if you are hitting the same site repeatedly.
Sessions keep one browser instance alive across multiple requests, so you solve the challenge once and reuse it.
Creating a session
Reusing a session
Destroying a session
Always destroy sessions once you are done with them. An idle browser still holds memory, and running too many at once will slow down or crash the host machine.
Using proxies with FlareSolverr
FlareSolverr solves the browser side of the challenge. It does nothing about the IP reputation behind that browser, and Cloudflare weighs IP reputation heavily when deciding whether to show a challenge at all.
A datacenter IP with a history of scraping traffic gets challenged constantly, no matter how well the browser behaves. A clean, real-user IP gets waved through far more often.
| Proxy type | IP source | Best for |
| Datacenter | Hosting providers and cloud data centers | High speed, low cost, and websites with little or no anti-bot protection |
| Residential | Real home internet connections | Websites with strict bot detection, Cloudflare-protected sites, and large-scale web scraping |
| ISP (Static Residential) | ISP-assigned IPs hosted on dedicated infrastructure | Long-running sessions that require a stable IP address with residential-level trust |
| Mobile | Mobile carrier networks (4G/5G) | Mobile-first platforms, social media automation, and websites that trust IPs shared by real mobile users |
You set a proxy per request or per session using the proxy field, with the scheme included in the URL:
This is where a proxy provider like NodeMaven can make a real difference. NodeMaven offers a pool of 30M+ residential IPs across 190+ countries. Every IP goes through real-time quality filtering, helping ensure you receive clean, high-trust IPs for your scraping sessions.
For FlareSolverr users, two features are especially useful. Sticky sessions let you keep the same IP for up to seven days, making it easy to maintain a consistent identity across multiple requests. You can also target proxies by country, city, or ZIP code, allowing your traffic to match the expected visitor location and reducing the chance of geo-based blocks.
Reduce Cloudflare challenges with high-quality proxies. Start your NodeMaven trial for $3.50 with 750 MB included
Common FlareSolverr errors and fixes
| Error | Likely cause | How to fix it |
| Timeout / Challenge not solved | The maxTimeout value is too low, or the Cloudflare challenge takes longer than expected. | Increase the maxTimeout value. Check the host’s CPU and memory usage to ensure FlareSolverr has enough resources. |
| 403 Forbidden | The proxy IP has a poor reputation, or the website introduced stricter anti-bot protection. | Switch to a clean residential proxy and verify you’re running the latest version of FlareSolverr. |
| 503 Service Unavailable | The FlareSolverr container is overloaded, restarting, or temporarily unavailable. | Reduce the number of concurrent sessions and review the container logs for errors. |
| Browser crash | The host doesn’t have enough memory, or too many browser instances are running at once. | Limit parallel sessions and allocate more RAM or CPU resources to the container. |
| Session expired | The session was deleted, timed out, or the browser process unexpectedly stopped. | Create a new session and add retry logic to automatically recover from expired sessions. |
| Proxy authentication failed | The proxy username or password is incorrect, or the proxy configuration isn’t supported for the request. | Verify your proxy credentials and, if needed, configure the proxy when creating the session instead of on individual requests. |
FlareSolverr Limitations
FlareSolverr is genuinely useful, but it is worth being honest about where it falls short.
- CAPTCHAs: FlareSolverr does not solve hCaptcha, reCAPTCHA, or Cloudflare Turnstile CAPTCHAs on its own. It can detect a CAPTCHA prompt but will not clear it without an external solver, and built-in solver support has been unreliable.
- Browser fingerprinting: Advanced anti-bot systems look at far more than the Cloudflare challenge, and a stealth browser is not invisible forever.
- TLS fingerprinting: Some detection happens at the TLS handshake level, which is outside what FlareSolverr controls.
- Memory usage: Every active session is a real Chrome process. Ten sessions means ten browsers running at once.
- Scalability: Because of the memory cost, FlareSolverr does not scale the same way a lightweight HTTP-based scraper does.
Pair FlareSolverr with trusted proxies for higher success rates. Start your NodeMaven trial for $3.50 with 750 MB included
Best practices
- Reuse sessions instead of solving the challenge on every single request.
- Rotate IPs for high-volume jobs so no single address takes all the traffic.
- Use residential proxies on sites with strict Cloudflare configurations, since IP reputation shapes how often you get challenged.
- Set realistic headers and let FlareSolverr’s reported user agent flow through to any follow-up requests.
- Tune concurrency to your host’s available RAM. Fewer parallel browsers beat frequent crashes.
- Adjust timeouts based on how slow the target site’s challenge tends to be.
- Match proxy location to the site’s expected traffic, especially for geo-sensitive platforms.
FlareSolverr alternatives
| Tool | Best when |
| FlareSolverr | You need a free, open-source solution to solve Cloudflare challenges and are comfortable managing your own infrastructure. |
| Playwright | You want full control over browser automation and are willing to build your own stealth and anti-bot logic. |
| Puppeteer | You’re working in a Node.js environment and need direct control over a Chromium browser. |
| Nodriver | You prefer a lightweight, modern Python library designed for undetected browser automation. |
| ZenRows | You want a managed scraping API that takes care of browser rendering, proxies, and anti-bot bypass. |
| ScrapFly | You need a scraping API with built-in anti-bot handling, browser rendering, and structured data extraction. |
FlareSolverr wins on cost since it is free and self-hosted. Managed services like ZenRows and ScrapFly cost more but remove the maintenance burden of running your own browser infrastructure.
Conclusion
FlareSolverr handles the browser side of a Cloudflare challenge well, especially for low to medium volume scraping and one-off access to stubborn endpoints. It is not built for CAPTCHA solving, and it is not the lightest option for very high-volume jobs.
The IP behind FlareSolverr matters just as much as the tool itself. Pairing it with a clean residential proxy pool, sticky sessions where you need continuity, and sensible concurrency limits will get you a lot further than running it on a flagged datacenter IP.
If Cloudflare challenges keep showing up no matter what you try, check your proxy’s reputation before assuming FlareSolverr is broken. That is usually where the real problem is hiding.
