0
# CloudScraper
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: cloudscraper  
7
- **Language**: Python
8
- **Installation**: `pip install cloudscraper`
9
- **Python Requirements**: Python 3.8+
10

11
## Core Imports
12

13
```python
14
import cloudscraper
15

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

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

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

26
# Session alias (same as create_scraper)
27
scraper = cloudscraper.session()
28
```
29

30
Alternative imports for direct class access:
31

32
```python
33
# Direct class imports
34
from cloudscraper import CloudScraper, CipherSuiteAdapter
35
from cloudscraper.user_agent import User_Agent
36
from cloudscraper.stealth import StealthMode
37
from cloudscraper.proxy_manager import ProxyManager
38

39
# Exception imports
40
from cloudscraper.exceptions import (
41
    CloudflareException, CloudflareLoopProtection, CloudflareIUAMError,
42
    CloudflareChallengeError, CloudflareTurnstileError, CloudflareV3Error,
43
    CaptchaException, CaptchaServiceUnavailable, CaptchaTimeout
44
)
45

46
# Challenge handler imports
47
from cloudscraper.cloudflare import Cloudflare
48
from cloudscraper.cloudflare_v2 import CloudflareV2
49
from cloudscraper.cloudflare_v3 import CloudflareV3
50
from cloudscraper.turnstile import CloudflareTurnstile
51

52
# Interpreter imports
53
from cloudscraper.interpreters import JavaScriptInterpreter
54

55
# CAPTCHA solver imports
56
from cloudscraper.captcha import Captcha
57
```
58

59
## Basic Usage
60

61
```python
62
import cloudscraper
63

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

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

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

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

80
## Architecture
81

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

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

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

93
## Capabilities
94

95
### Core Scraper Functions
96

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

99
```python { .api }
100
def create_scraper(sess=None, **kwargs) -> CloudScraper: ...
101
def get_tokens(url: str, **kwargs) -> tuple[dict, str]: ...
102
def get_cookie_string(url: str, **kwargs) -> tuple[str, str]: ...
103

104
class CloudScraper:
105
    def __init__(self, **kwargs): ...
106
    def request(self, method: str, url: str, *args, **kwargs): ...
107
```
108

109
[Core Scraper](./core-scraper.md)
110

111
### Challenge Handling
112

113
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.
114

115
```python { .api }
116
class Cloudflare:
117
    def is_Challenge_Request(resp) -> bool: ...
118
    def Challenge_Response(self, resp, **kwargs): ...
119

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

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

128
class CloudflareTurnstile:
129
    def is_Turnstile_Challenge(resp) -> bool: ...
130
    def handle_Turnstile_Challenge(self, resp, **kwargs): ...
131
```
132

133
[Challenge Handling](./challenge-handling.md)
134

135
### JavaScript Interpreters
136

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

139
```python { .api }
140
class JavaScriptInterpreter:
141
    def eval(self, jsEnv: str, js: str): ...
142
    def solveChallenge(self, body: str, domain: str) -> str: ...
143

144
# Available interpreters: js2py, nodejs, v8, chakracore, native
145
```
146

147
[JavaScript Interpreters](./javascript-interpreters.md)
148

149
### Captcha Solving
150

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

153
```python { .api }
154
class Captcha:
155
    def getCaptchaAnswer(self, captchaType: str, url: str, siteKey: str, captchaParams: dict): ...
156
    def solveCaptcha(self, captchaType: str, url: str, siteKey: str, captchaParams: dict): ...
157

158
# Supported providers: 2captcha, anticaptcha, 9kw, capmonster, capsolver, deathbycaptcha
159
```
160

161
[CAPTCHA Solving](./captcha-solving.md)
162

163
### Stealth Mode and Anti-Detection
164

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

167
```python { .api }
168
class StealthMode:
169
    def apply_stealth_techniques(self, method: str, url: str, **kwargs): ...
170
    def set_delay_range(self, min_delay: float, max_delay: float): ...
171
    def enable_human_like_delays(self, enabled: bool): ...
172
    def enable_randomize_headers(self, enabled: bool): ...
173
```
174

175
[Stealth Mode](./stealth-mode.md)
176

177
### Proxy Management
178

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

181
```python { .api }
182
class ProxyManager:
183
    def __init__(self, proxies, proxy_rotation_strategy: str = 'sequential', ban_time: int = 300): ...
184
    def get_proxy(self) -> dict: ...
185
    def report_success(self, proxy: dict): ...
186
    def report_failure(self, proxy: dict): ...
187
```
188

189
[Proxy Management](./proxy-management.md)
190

191
### User Agent and Browser Emulation
192

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

195
```python { .api }
196
class User_Agent:
197
    def __init__(self, browser=None, **kwargs): ...
198
    def loadUserAgent(self, **kwargs): ...
199
    @property
200
    def headers(self) -> dict: ...
201
    @property  
202
    def cipherSuite(self) -> list: ...
203
```
204

205
[User Agent Management](./user-agent.md)
206

207
## Exception Handling
208

209
CloudScraper defines comprehensive exception hierarchies for different error conditions:
210

211
```python { .api }
212
# Cloudflare-specific exceptions
213
class CloudflareException(Exception): ...
214
class CloudflareLoopProtection(CloudflareException): ...
215
class CloudflareCode1020(CloudflareException): ...
216
class CloudflareIUAMError(CloudflareException): ...
217
class CloudflareChallengeError(CloudflareException): ...
218
class CloudflareSolveError(CloudflareException): ...
219
class CloudflareCaptchaError(CloudflareException): ...
220
class CloudflareCaptchaProvider(CloudflareException): ...
221
class CloudflareTurnstileError(CloudflareException): ...
222
class CloudflareV3Error(CloudflareException): ...
223

224
# CAPTCHA-related exceptions  
225
class CaptchaException(Exception): ...
226
class CaptchaServiceUnavailable(CaptchaException): ...
227
class CaptchaAPIError(CaptchaException): ...
228
class CaptchaAccountError(CaptchaException): ...
229
class CaptchaTimeout(CaptchaException): ...
230
class CaptchaParameter(CaptchaException): ...
231
class CaptchaBadJobID(CaptchaException): ...
232
class CaptchaReportError(CaptchaException): ...
233
```
234

235
## Types
236

237
Common types used throughout the CloudScraper API:
238

239
```python { .api }
240
# Configuration types
241
BrowserConfig = dict[str, Any]  # Browser fingerprinting options
242
ProxyConfig = dict[str, Any]    # Proxy configuration options  
243
StealthConfig = dict[str, Any]  # Stealth mode configuration
244
CaptchaConfig = dict[str, Any]  # CAPTCHA solver configuration
245

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