or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

captcha-solving.mdchallenge-handling.mdcore-scraper.mdindex.mdjavascript-interpreters.mdproxy-management.mdstealth-mode.mduser-agent.md
tile.json

tessl/pypi-cloudscraper

Enhanced Python module to bypass Cloudflare's anti-bot page with support for v1, v2, v3 challenges, Turnstile, proxy rotation, and stealth mode.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/cloudscraper@3.0.x

To install, run

npx @tessl/cli install tessl/pypi-cloudscraper@3.0.0

index.mddocs/

CloudScraper

Enhanced Python module to bypass Cloudflare's anti-bot page with support for v1, v2, v3 challenges, Turnstile CAPTCHA, proxy rotation, and stealth mode. CloudScraper extends the requests library with sophisticated challenge-solving capabilities, making it possible to scrape websites protected by Cloudflare's anti-bot systems.

Package Information

  • Package Name: cloudscraper
  • Language: Python
  • Installation: pip install cloudscraper
  • Python Requirements: Python 3.8+

Core Imports

import cloudscraper

# Create a scraper instance (recommended)
scraper = cloudscraper.create_scraper()

# Alternative: direct class instantiation
scraper = cloudscraper.CloudScraper()

# Module-level convenience functions
tokens, user_agent = cloudscraper.get_tokens('https://example.com')
cookie_string, user_agent = cloudscraper.get_cookie_string('https://example.com')

# Session alias (same as create_scraper)
scraper = cloudscraper.session()

Alternative imports for direct class access:

# Direct class imports
from cloudscraper import CloudScraper, CipherSuiteAdapter
from cloudscraper.user_agent import User_Agent
from cloudscraper.stealth import StealthMode
from cloudscraper.proxy_manager import ProxyManager

# Exception imports
from cloudscraper.exceptions import (
    CloudflareException, CloudflareLoopProtection, CloudflareIUAMError,
    CloudflareChallengeError, CloudflareTurnstileError, CloudflareV3Error,
    CaptchaException, CaptchaServiceUnavailable, CaptchaTimeout
)

# Challenge handler imports
from cloudscraper.cloudflare import Cloudflare
from cloudscraper.cloudflare_v2 import CloudflareV2
from cloudscraper.cloudflare_v3 import CloudflareV3
from cloudscraper.turnstile import CloudflareTurnstile

# Interpreter imports
from cloudscraper.interpreters import JavaScriptInterpreter

# CAPTCHA solver imports
from cloudscraper.captcha import Captcha

Basic Usage

import cloudscraper

# Create a scraper that handles all Cloudflare challenge types
scraper = cloudscraper.create_scraper()

# Make requests just like with requests library
response = scraper.get('https://example.com')
print(response.text)

# POST requests work the same way
data = {'key': 'value'}
response = scraper.post('https://example.com/api', data=data)

# Use with sessions for multiple requests
response1 = scraper.get('https://example.com/page1')
response2 = scraper.get('https://example.com/page2')  # Reuses session

Architecture

CloudScraper is built on top of the requests library and follows a modular architecture:

  • CloudScraper: Main session class extending requests.Session with challenge detection and solving
  • Challenge Handlers: Specialized modules for different Cloudflare protection types (v1, v2, v3, Turnstile)
  • JavaScript Interpreters: Multiple backends for executing JavaScript challenges (js2py, nodejs, v8, etc.)
  • Captcha Solvers: Integration with external CAPTCHA solving services (2captcha, anticaptcha, etc.)
  • Stealth Mode: Anti-detection techniques including human-like delays and browser fingerprinting
  • Proxy Management: Intelligent proxy rotation with failure handling and ban management

This design enables CloudScraper to handle modern Cloudflare protection while maintaining compatibility with the familiar requests API.

Capabilities

Core Scraper Functions

Main CloudScraper class and convenience functions for creating configured scraper instances, extracting tokens, and making requests with automatic challenge solving.

def create_scraper(sess=None, **kwargs) -> CloudScraper: ...
def get_tokens(url: str, **kwargs) -> tuple[dict, str]: ...
def get_cookie_string(url: str, **kwargs) -> tuple[str, str]: ...

class CloudScraper:
    def __init__(self, **kwargs): ...
    def request(self, method: str, url: str, *args, **kwargs): ...

Core Scraper

Challenge Handling

Comprehensive support for all Cloudflare challenge types including legacy v1, modern v2, advanced v3 JavaScript VM challenges, and Turnstile CAPTCHA alternatives with automatic detection and solving.

class Cloudflare:
    def is_Challenge_Request(resp) -> bool: ...
    def Challenge_Response(self, resp, **kwargs): ...

class CloudflareV2:
    def is_V2_Challenge(resp) -> bool: ...
    def handle_V2_Challenge(self, resp, **kwargs): ...

class CloudflareV3:
    def is_V3_Challenge(resp) -> bool: ...
    def handle_V3_Challenge(self, resp, **kwargs): ...

class CloudflareTurnstile:
    def is_Turnstile_Challenge(resp) -> bool: ...
    def handle_Turnstile_Challenge(self, resp, **kwargs): ...

Challenge Handling

JavaScript Interpreters

Multiple JavaScript execution backends for solving Cloudflare challenges, including pure Python, Node.js, V8, and ChakraCore interpreters with automatic fallback and error handling.

class JavaScriptInterpreter:
    def eval(self, jsEnv: str, js: str): ...
    def solveChallenge(self, body: str, domain: str) -> str: ...

# Available interpreters: js2py, nodejs, v8, chakracore, native

JavaScript Interpreters

Captcha Solving

Integration with external CAPTCHA solving services for handling challenges that require human verification, supporting multiple providers with configurable options.

class Captcha:
    def getCaptchaAnswer(self, captchaType: str, url: str, siteKey: str, captchaParams: dict): ...
    def solveCaptcha(self, captchaType: str, url: str, siteKey: str, captchaParams: dict): ...

# Supported providers: 2captcha, anticaptcha, 9kw, capmonster, capsolver, deathbycaptcha

CAPTCHA Solving

Stealth Mode and Anti-Detection

Advanced techniques for avoiding detection including human-like behavior simulation, request timing randomization, header manipulation, and browser fingerprint rotation.

class StealthMode:
    def apply_stealth_techniques(self, method: str, url: str, **kwargs): ...
    def set_delay_range(self, min_delay: float, max_delay: float): ...
    def enable_human_like_delays(self, enabled: bool): ...
    def enable_randomize_headers(self, enabled: bool): ...

Stealth Mode

Proxy Management

Intelligent proxy rotation with multiple strategies, automatic failure detection, temporary banning of failed proxies, and success rate tracking for optimal performance.

class ProxyManager:
    def __init__(self, proxies, proxy_rotation_strategy: str = 'sequential', ban_time: int = 300): ...
    def get_proxy(self) -> dict: ...
    def report_success(self, proxy: dict): ...
    def report_failure(self, proxy: dict): ...

Proxy Management

User Agent and Browser Emulation

Comprehensive browser fingerprinting and user agent management with support for multiple browsers, platforms, and device types, including automatic fallback for executable environments.

class User_Agent:
    def __init__(self, browser=None, **kwargs): ...
    def loadUserAgent(self, **kwargs): ...
    @property
    def headers(self) -> dict: ...
    @property  
    def cipherSuite(self) -> list: ...

User Agent Management

Exception Handling

CloudScraper defines comprehensive exception hierarchies for different error conditions:

# Cloudflare-specific exceptions
class CloudflareException(Exception): ...
class CloudflareLoopProtection(CloudflareException): ...
class CloudflareCode1020(CloudflareException): ...
class CloudflareIUAMError(CloudflareException): ...
class CloudflareChallengeError(CloudflareException): ...
class CloudflareSolveError(CloudflareException): ...
class CloudflareCaptchaError(CloudflareException): ...
class CloudflareCaptchaProvider(CloudflareException): ...
class CloudflareTurnstileError(CloudflareException): ...
class CloudflareV3Error(CloudflareException): ...

# CAPTCHA-related exceptions  
class CaptchaException(Exception): ...
class CaptchaServiceUnavailable(CaptchaException): ...
class CaptchaAPIError(CaptchaException): ...
class CaptchaAccountError(CaptchaException): ...
class CaptchaTimeout(CaptchaException): ...
class CaptchaParameter(CaptchaException): ...
class CaptchaBadJobID(CaptchaException): ...
class CaptchaReportError(CaptchaException): ...

Types

Common types used throughout the CloudScraper API:

# Configuration types
BrowserConfig = dict[str, Any]  # Browser fingerprinting options
ProxyConfig = dict[str, Any]    # Proxy configuration options  
StealthConfig = dict[str, Any]  # Stealth mode configuration
CaptchaConfig = dict[str, Any]  # CAPTCHA solver configuration

# Response types
ChallengeResponse = Any         # HTTP response from challenge solving
TokenDict = dict[str, str]      # Cloudflare tokens dictionary
CookieString = str              # Cookie header value
UserAgent = str                 # User agent string