Proxies Pricing Open App

How to Use Cloudscraper in 2025

8 min read

If you've ever hit a wall while scraping a website and been met with the message "Checking your browser before accessing...", you've already encountered Cloudflare's anti-bot defenses. And if you’re here, you're likely wondering how to get around it.

Cloudflare has steadily leveled up its security game—throwing more JavaScript challenges, browser fingerprinting, and bot-detection tactics into the mix. But tools have evolved too. Enter Cloudscraper: a Python-based library built to handle exactly these kinds of obstacles.

This guide walks you through how to use Cloudscraper in 2025—step by step. Whether you're just testing the waters or scaling a full scraping operation, everything you need to know is here.

Why You Can Trust This Guide

Cloudflare's defenses are nothing like they were a few years ago. The stakes are higher, the barriers smarter. That’s exactly why this guide exists. Every tip here is rooted in real-world testing and updated for Cloudscraper and Cloudflare as they stand in 2025.

You’re not getting recycled advice—you’re getting insights tailored to the current threat landscape and bot protections. If you’ve struggled to get past Cloudflare recently, this guide is your starting point.

Step 1: Install Cloudscraper and Its Dependencies

Before using Cloudscraper, we need to set up our environment properly. Cloudscraper requires Python and a few dependencies to work effectively.

First, make sure you have Python 3.9 or higher installed on your system. Then, create and activate a virtual environment:

# Create a virtual environment
python -m venv cloudscraper_env

# Activate the environment
# On Windows
cloudscraper_env\Scripts\activate
# On macOS/Linux
source cloudscraper_env/bin/activate

Now, install Cloudscraper with pip:

pip install cloudscraper -U

The -U flag ensures you get the latest version, which is crucial since Cloudflare frequently updates its protection mechanisms.

In 2025, Cloudscraper requires a JavaScript interpreter to solve Cloudflare's JavaScript challenges. The default is a native Python solver, but for better results, I recommend installing Node.js as well:

# Install Node.js (platform dependent)
# For Debian/Ubuntu
sudo apt install nodejs

# For macOS using Homebrew
brew install node

# For Windows, download the installer from https://nodejs.org/

For parsing HTML responses, you'll also want to install BeautifulSoup:

pip install beautifulsoup4

Step 2: Create Your First Cloudscraper Request

Now that we have all the necessary components installed, let's create a basic Cloudscraper script to test our setup.

Create a new Python file (e.g., cloudscraper_test.py) and add the following code:

import cloudscraper
from bs4 import BeautifulSoup

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

# Perform a GET request to a Cloudflare-protected website
# (Replace with your target URL)
url = "https://example.com"
response = scraper.get(url)

# Check if the request was successful
if response.status_code == 200:
    print("Request successful!")
    
    # Parse the HTML content with BeautifulSoup
    soup = BeautifulSoup(response.text, 'html.parser')
    
    # Extract and print the page title
    title = soup.title.string
    print(f"Page title: {title}")
else:
    print(f"Request failed with status code: {response.status_code}")
    print(response.text)

This simple script creates a Cloudscraper instance, makes a GET request to your target website, and extracts the page title if successful. If you're familiar with the Python Requests library, you'll notice that Cloudscraper follows a similar API, making it easy to use if you've worked with Requests before.

Run this script to test if Cloudscraper can bypass Cloudflare on your target website:

python cloudscraper_test.py

Step 3: Configure Browser and JavaScript Interpreters

By default, Cloudscraper uses a generic browser configuration and its native JavaScript interpreter. However, in 2025, Cloudflare has become more sophisticated at detecting automation. To improve your success rate, you should customize these settings.

Configuring Browser Settings

Specify browser parameters when creating your Cloudscraper instance:

# Create a Cloudscraper instance with browser configuration
scraper = cloudscraper.create_scraper(
    browser={
        'browser': 'chrome',  # Options: chrome, firefox
        'platform': 'windows',  # Options: windows, darwin (macOS), linux, android, ios
        'desktop': True,  # True for desktop browser, False for mobile
        'mobile': False   # True for mobile browser, False for desktop
    }
)

Different websites may respond better to different browser configurations, so it's worth experimenting with various combinations.

Selecting a JavaScript Interpreter

Cloudscraper supports several JavaScript interpreters to solve Cloudflare's challenges:

# Create a Cloudscraper instance with a specified JavaScript interpreter
scraper = cloudscraper.create_scraper(
    interpreter='nodejs'  # Options: 'native' (default), 'nodejs', 'js2py', 'chakracore', 'v8'
)

In 2025, 'nodejs' is often the most effective interpreter for solving complex Cloudflare challenges because it provides the most complete JavaScript environment. However, each interpreter has its strengths and weaknesses:

  • 'native': The default Python-based solver. Fast but limited in handling complex challenges.
  • 'nodejs': More powerful but requires Node.js to be installed.
  • 'js2py': Pure Python interpreter, slower but doesn't require external dependencies.
  • 'chakracore': Microsoft's JavaScript engine, good performance on Windows.
  • 'v8': Google's high-performance JavaScript engine, good for complex challenges.

You can combine both browser and interpreter configurations:

scraper = cloudscraper.create_scraper(
    browser={
        'browser': 'chrome',
        'platform': 'windows',
        'desktop': True,
        'mobile': False
    },
    interpreter='nodejs'
)

Step 4: Implement Proxy Support

Using proxies with Cloudscraper is essential in 2025, especially for large-scale scraping operations. Proxies help distribute your requests across different IP addresses, reducing the risk of being blocked.

Basic Proxy Setup

To use a proxy with Cloudscraper, create a dictionary with the protocol and proxy server details:

import cloudscraper

# Define proxy details
proxy = {
    'http': 'http://proxy_ip:proxy_port',
    'https': 'http://proxy_ip:proxy_port'
}

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

# Make a request using the proxy
response = scraper.get('https://example.com', proxies=proxy)

Authenticated Proxies

If your proxy requires authentication, include the username and password in the proxy URL:

proxy = {
    'http': 'http://username:password@proxy_ip:proxy_port',
    'https': 'http://username:password@proxy_ip:proxy_port'
}

Rotating Proxies

For more advanced scraping operations, you can implement proxy rotation:

import cloudscraper
import random

# Define a list of proxies
proxy_list = [
    {
        'http': 'http://proxy1_ip:proxy1_port',
        'https': 'http://proxy1_ip:proxy1_port'
    },
    {
        'http': 'http://proxy2_ip:proxy2_port',
        'https': 'http://proxy2_ip:proxy2_port'
    },
    {
        'http': 'http://proxy3_ip:proxy3_port',
        'https': 'http://proxy3_ip:proxy3_port'
    }
]

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

# Function to make a request with a random proxy
def make_request(url):
    random_proxy = random.choice(proxy_list)
    try:
        response = scraper.get(url, proxies=random_proxy)
        return response
    except Exception as e:
        print(f"Error with proxy {random_proxy}: {e}")
        # Try with a different proxy if the first one fails
        return make_request(url)

# Use the function
response = make_request('https://example.com')
print(response.status_code)

Important Note: When using proxies with Cloudscraper, always use the same proxy for the entire session. Cloudflare tracks the IP address used to solve the initial challenge, and switching proxies mid-session may trigger additional security measures.

Step 5: Handle CAPTCHAs and Advanced Challenges

In 2025, Cloudflare increasingly uses CAPTCHAs and advanced challenges to block automated access. Cloudscraper can integrate with third-party CAPTCHA solving services to handle these challenges.

Setting Up CAPTCHA Solvers

Cloudscraper supports several CAPTCHA solving services, including 2captcha, AntiCaptcha, and CapSolver. Here's how to set up 2captcha:

import cloudscraper

# Create a Cloudscraper instance with CAPTCHA solver configuration
scraper = cloudscraper.create_scraper(
    captcha={
        'provider': '2captcha',
        'api_key': 'your_2captcha_api_key'
    }
)

# Make a request
response = scraper.get('https://example.com')

If you're using proxies, you can prevent sending your proxy details to the CAPTCHA service:

scraper = cloudscraper.create_scraper(
    captcha={
        'provider': '2captcha',
        'api_key': 'your_2captcha_api_key',
        'no_proxy': True  # Don't send proxy details to the CAPTCHA service
    }
)

Handling Advanced Challenges

For websites with particularly strong protection, combine multiple approaches:

import cloudscraper
import time

# Create a sophisticated Cloudscraper instance
scraper = cloudscraper.create_scraper(
    browser={
        'browser': 'chrome',
        'platform': 'windows',
        'desktop': True,
        'mobile': False
    },
    interpreter='nodejs',
    captcha={
        'provider': '2captcha',
        'api_key': 'your_2captcha_api_key'
    },
    delay=10  # Add delay (in seconds) for challenging sites
)

# Function to make a request with retries
def make_request_with_retry(url, max_retries=3):
    for attempt in range(max_retries):
        try:
            response = scraper.get(url)
            if response.status_code == 200:
                return response
            else:
                print(f"Attempt {attempt+1} failed with status code: {response.status_code}")
                time.sleep(5)  # Wait before retry
        except Exception as e:
            print(f"Attempt {attempt+1} failed with error: {e}")
            time.sleep(5)  # Wait before retry
    
    raise Exception(f"Failed to access {url} after {max_retries} attempts")

# Use the function
try:
    response = make_request_with_retry('https://example.com')
    print("Success!")
except Exception as e:
    print(f"Error: {e}")

Step 6: Troubleshoot Common Errors

Even with the best configuration, you may encounter errors when using Cloudscraper. Here are some common issues and how to resolve them.

Module Not Found Error

If you see ModuleNotFoundError: No module named 'cloudscraper', ensure that:

  • Cloudscraper is installed in your active Python environment
  • You're using the correct Python interpreter

Cloudflare Bypass Failure

If Cloudscraper cannot bypass Cloudflare (indicated by 403 Forbidden responses or Cloudflare challenge errors), try the following:

Add delays between requests:

import time

scraper = cloudscraper.create_scraper()
scraper.get('https://example.com')
time.sleep(5)  # Wait 5 seconds between requests
scraper.get('https://example.com/page2')

Use a different browser configuration:

scraper = cloudscraper.create_scraper(
    browser={
        'browser': 'firefox',  # Try firefox instead of chrome
        'platform': 'linux',  # Try a different platform
        'mobile': True  # Try mobile instead of desktop
    }
)

Try a different JavaScript interpreter:

scraper = cloudscraper.create_scraper(interpreter='nodejs')  # or 'v8', 'chakracore', etc.

Update to the latest Cloudscraper version:

pip install cloudscraper -U

CAPTCHA Errors

If you encounter CAPTCHA-related errors:

  1. Verify your CAPTCHA provider API key is correct
  2. Check your account balance with the CAPTCHA provider
  3. Try a different CAPTCHA provider

JavaScript Interpreter Errors

If you see errors related to JavaScript interpreters:

  1. Ensure the interpreter is installed correctly (e.g., Node.js for 'nodejs')
  2. Try a different interpreter
  3. Fallback to the 'native' interpreter, which doesn't require external dependencies

Step 7: Scale Your Scraping Operation

Once you have Cloudscraper working reliably for individual requests, you might want to scale your operation to scrape multiple pages or websites.

Scraping Multiple Pages

Here's an example of scraping multiple pages with error handling and respect for rate limits:

import cloudscraper
from bs4 import BeautifulSoup
import time
import random

# Create a Cloudscraper instance
scraper = cloudscraper.create_scraper(
    browser={
        'browser': 'chrome',
        'platform': 'windows'
    },
    interpreter='nodejs'
)

# List of URLs to scrape
urls = [
    'https://example.com/page1',
    'https://example.com/page2',
    'https://example.com/page3',
    # Add more URLs as needed
]

# Function to scrape a single page
def scrape_page(url):
    try:
        # Add random delay to mimic human behavior
        delay = random.uniform(3, 7)
        time.sleep(delay)
        
        # Make the request
        response = scraper.get(url)
        
        if response.status_code == 200:
            # Parse the content
            soup = BeautifulSoup(response.text, 'html.parser')
            
            # Extract data (customize for your target site)
            title = soup.title.string
            
            # Return the extracted data
            return {
                'url': url,
                'title': title,
                'success': True
            }
        else:
            return {
                'url': url,
                'success': False,
                'error': f"Status code: {response.status_code}"
            }
    except Exception as e:
        return {
            'url': url,
            'success': False,
            'error': str(e)
        }

# Scrape all pages
results = []
for url in urls:
    print(f"Scraping {url}...")
    result = scrape_page(url)
    results.append(result)
    
    # Print status
    if result['success']:
        print(f"✅ Success: {url}")
    else:
        print(f"❌ Failed: {url} - {result.get('error', 'Unknown error')}")

# Print final summary
successful = sum(1 for r in results if r['success'])
print(f"\nScraping completed: {successful}/{len(urls)} pages successful")

Parallel Scraping

For larger scraping operations, you might want to use parallel processing to speed things up. However, be careful with parallel requests to the same domain, as this can trigger rate limiting or anti-bot measures.

Here's an example using concurrent.futures:

import cloudscraper
from bs4 import BeautifulSoup
import concurrent.futures
import time
import random

# Function to create a new scraper instance
# (Each thread should have its own instance)
def create_scraper():
    return cloudscraper.create_scraper(
        browser={
            'browser': 'chrome',
            'platform': 'windows'
        },
        interpreter='nodejs'
    )

# Function to scrape a single page
def scrape_page(url):
    # Create a new scraper instance for each thread
    scraper = create_scraper()
    
    try:
        # Add random delay to mimic human behavior
        delay = random.uniform(3, 7)
        time.sleep(delay)
        
        # Make the request
        response = scraper.get(url)
        
        if response.status_code == 200:
            # Parse the content
            soup = BeautifulSoup(response.text, 'html.parser')
            
            # Extract data (customize for your target site)
            title = soup.title.string
            
            # Return the extracted data
            return {
                'url': url,
                'title': title,
                'success': True
            }
        else:
            return {
                'url': url,
                'success': False,
                'error': f"Status code: {response.status_code}"
            }
    except Exception as e:
        return {
            'url': url,
            'success': False,
            'error': str(e)
        }

# List of URLs to scrape
urls = [
    'https://example.com/page1',
    'https://example.com/page2',
    'https://example.com/page3',
    # Add more URLs as needed
]

# Number of worker threads
# Keep this low for the same domain to avoid triggering anti-bot measures
max_workers = 3

# Scrape in parallel
results = []
with concurrent.futures.ThreadPoolExecutor(max_workers=max_workers) as executor:
    # Submit all scraping tasks
    future_to_url = {executor.submit(scrape_page, url): url for url in urls}
    
    # Process results as they complete
    for future in concurrent.futures.as_completed(future_to_url):
        url = future_to_url[future]
        try:
            result = future.result()
            results.append(result)
            
            # Print status
            if result['success']:
                print(f"✅ Success: {url}")
            else:
                print(f"❌ Failed: {url} - {result.get('error', 'Unknown error')}")
        except Exception as exc:
            print(f"❌ Error: {url} generated an exception: {exc}")
            results.append({
                'url': url,
                'success': False,
                'error': str(exc)
            })

# Print final summary
successful = sum(1 for r in results if r['success'])
print(f"\nScraping completed: {successful}/{len(urls)} pages successful")

Final Thoughts

Cloudscraper remains one of the most reliable tools for bypassing Cloudflare in 2025—but it’s not magic. You’ll still need smart configurations, good proxies, and sometimes a CAPTCHA-solving service to pull it all off.

For complex jobs, you may want to combine Cloudscraper with headless browsers like Selenium or Playwright. But if you’re looking to balance speed, simplicity, and power, Cloudscraper’s a great place to start.

And remember: scrape ethically. Respect robots.txt, avoid hammering servers, and stick to publicly available data. Long-term success in scraping depends on it.

Marius Bernard
Article by

Marius Bernard

Marius Bernard is a Product Advisor, Technical SEO, & Brand Ambassador at Roundproxies. He was the lead author for the SEO chapter of the 2024 Web and a reviewer for the 2023 SEO chapter.