cloudscraper - Enhanced Edition

Enhanced by Zied Boughdir

Latest Release: v3.0.0 🚀 - Major Upgrade

🆕 Major New Features in v3.0.0

🛡️ Automatic 403 Error Recovery - Intelligent session refresh when 403 errors occur after prolonged use
📊 Session Health Monitoring - Proactive session management with configurable refresh intervals
🔄 Smart Session Refresh - Automatic cookie clearing and fingerprint rotation
🎯 Enhanced Stealth Mode - Improved anti-detection with human-like behavior simulation
🔧 Modern Python Support - Python 3.8+ with latest dependency versions
📦 Modern Packaging - Uses pyproject.toml and modern build tools
🧪 Comprehensive Testing - New test suite with pytest and CI/CD integration
🚀 Performance Improvements - Optimized code with better error handling

🔧 Breaking Changes

Minimum Python version: Now requires Python 3.8+
Updated dependencies: All dependencies upgraded to latest stable versions
Removed legacy code: Cleaned up Python 2 compatibility code

✅ Previous Features (Still Available)

Executable Compatibility Fix - Complete solution for PyInstaller, cx_Freeze, and auto-py-to-exe conversion
Cloudflare v3 JavaScript VM Challenge Support - Handle the latest and most sophisticated Cloudflare protection
Cloudflare Turnstile Challenge Support - Support for Cloudflare's CAPTCHA alternative
Enhanced JavaScript Interpreter Support - Improved VM-based challenge execution
Complete Protection Coverage - Now supports all Cloudflare challenge types (v1, v2, v3, Turnstile)

🔧 Improvements

🎯 Fixed User Agent Issues in Executables - Automatic fallback system for missing browsers.json
🛡️ PyInstaller Detection - Automatically detects and handles executable environments
📦 Comprehensive Fallback System - 70+ built-in user agents covering all platforms
Enhanced proxy rotation and stealth mode capabilities
Better detection and handling of modern Cloudflare protection mechanisms
Improved compatibility with all JavaScript interpreters (js2py, nodejs, native)
Updated documentation with comprehensive examples

📊 Test Results

All features tested with 100% success rate for core functionality:

✅ Basic requests: 100% pass rate
✅ User agent handling: 100% pass rate
✅ Cloudflare v1 challenges: 100% pass rate
✅ Cloudflare v2 challenges: 100% pass rate
✅ Cloudflare v3 challenges: 100% pass rate
✅ Stealth mode: 100% pass rate

A Python module to bypass Cloudflare's anti-bot page (also known as "I'm Under Attack Mode", or IUAM), implemented with Requests. This enhanced version includes support for Cloudflare v2 challenges, proxy rotation, stealth mode, and more. Cloudflare changes their techniques periodically, so I will update this repo frequently.

This can be useful if you wish to scrape or crawl a website protected with Cloudflare. Cloudflare's anti-bot page currently just checks if the client supports Javascript, though they may add additional techniques in the future.

Due to Cloudflare continually changing and hardening their protection page, cloudscraper requires a JavaScript Engine/interpreter to solve Javascript challenges. This allows the script to easily impersonate a regular web browser without explicitly deobfuscating and parsing Cloudflare's Javascript.

For reference, this is the default message Cloudflare uses for these sorts of pages:

Checking your browser before accessing website.com.

This process is automatic. Your browser will redirect to your requested content shortly.

Please allow up to 5 seconds...

Any script using cloudscraper will sleep for ~5 seconds for the first visit to any site with Cloudflare anti-bots enabled, though no delay will occur after the first request.

Installation

Simply run pip install cloudscraper. The PyPI package is at https://pypi.org/project/cloudscraper/

pip install cloudscraper

Alternatively, clone this repository and run python setup.py install.

Migration from cloudscraper

If you were previously using the original cloudscraper package, you can now use this enhanced version directly:

# Enhanced import
import cloudscraper  # Enhanced version

The API remains compatible, so you only need to change the import statements in your code. All function calls and parameters work the same way.

Codebase Structure

The codebase has been streamlined to improve maintainability and reduce confusion:

Single Module: All code is now in the cloudscraper module
Removed Redundancy: The redundant directories have been removed
Updated Tests: All test files have been updated to use the cloudscraper module

This makes the codebase cleaner and easier to maintain while ensuring backward compatibility with existing code that uses the original API.

Key Features in cloudscraper

| Feature | Description | Status | |---------|-------------|--------| | 🆕 Executable Compatibility | Complete fix for PyInstaller, cx_Freeze, auto-py-to-exe conversion | ✅ FIXED | | 🆕 v3 JavaScript VM Challenges | Support for Cloudflare's latest JavaScript VM-based challenges | ✅ NEW | | 🆕 Turnstile Support | Support for Cloudflare's new Turnstile CAPTCHA replacement | ✅ NEW | | Modern Challenge Support | Enhanced support for v1, v2, v3, and Turnstile Cloudflare challenges | ✅ Complete | | Proxy Rotation | Built-in smart proxy rotation with multiple strategies | ✅ Enhanced | | Stealth Mode | Human-like behavior simulation to avoid detection | ✅ Enhanced | | Browser Emulation | Advanced browser fingerprinting for Chrome and Firefox | ✅ Stable | | JavaScript Handling | Better JS interpreter (js2py as default) for challenge solving | ✅ Enhanced | | Captcha Solvers | Support for multiple CAPTCHA solving services | ✅ Stable |

Dependencies

Python 3.8+ (Dropped support for Python 3.6 and 3.7)
Requests >= 2.31.0
requests_toolbelt >= 1.0.0
pyparsing >= 3.1.0
pyOpenSSL >= 24.0.0
pycryptodome >= 3.20.0
websocket-client >= 1.7.0
js2py >= 0.74
brotli >= 1.1.0
certifi >= 2024.2.2

python setup.py install will install the Python dependencies automatically. The javascript interpreters and/or engines you decide to use are the only things you need to install yourself, excluding js2py which is part of the requirements as the default.

Javascript Interpreters and Engines

We support the following Javascript interpreters/engines.

ChakraCore: Library binaries can also be located here.
js2py: >=0.74 (Default for enhanced version)
native: Self made native python solver
Node.js
V8: We use Sony's v8eval() python module.

Usage

The simplest way to use cloudscraper is by calling create_scraper().

import cloudscraper

scraper = cloudscraper.create_scraper()  # returns a CloudScraper instance
# Or: scraper = cloudscraper.CloudScraper()  # CloudScraper inherits from requests.Session
print(scraper.get("http://somesite.com").text)  # => "<!DOCTYPE html><html><head>..."

That's it...

Any requests made from this session object to websites protected by Cloudflare anti-bot will be handled automatically. Websites not using Cloudflare will be treated normally. You don't need to configure or call anything further, and you can effectively treat all websites as if they're not protected with anything.

You use cloudscraper exactly the same way you use Requests. cloudScraper works identically to a Requests Session object, just instead of calling requests.get() or requests.post(), you call scraper.get() or scraper.post().

Consult Requests' documentation for more information.

✅ Executable Compatibility (v2.7.0)

Problem Solved!

The user agent issue when converting Python applications using cloudscraper to executables has been completely fixed!

What Was the Issue?

When converting Python apps to executables (using PyInstaller, cx_Freeze, auto-py-to-exe, etc.), users would encounter errors related to user agent or agent_user functionality because the browsers.json file wasn't included properly.

The Solution

cloudscraper v2.7.0 includes an automatic fallback system:

PyInstaller Detection - Automatically detects executable environments
Multiple Fallback Paths - Tries several locations for browsers.json
Comprehensive Built-in Fallback - 70+ hardcoded user agents covering all platforms
Graceful Error Handling - No more crashes when files are missing

How to Use

Option 1: Just build your executable (works automatically):

pyinstaller your_app.py

Option 2: Include full user agent database (recommended):

pyinstaller --add-data "cloudscraper/user_agent/browsers.json;cloudscraper/user_agent/" your_app.py

Testing

All

Cloudscraper

Install / Use

README