cloudscraper使い方：Cloudflareのアンチボットチャレンジを自動突破するPython完全ガイド

cloudscraperは、Cloudflareのアンチボットチャレンジ（IUAM＝I’m Under Attack Mode）をPythonから自動処理するオープンソースモジュールだ。requestsのドロップイン置き換えとして使え、GitHubで6,668スター（2026-07-28時点）を集めている。関連する自動化ツール全般はAI自動化ツール｜ノーコードからコードまで2026年版の比較と選び方で比較している。

本記事は公式README・PyPI公開情報・実際のインストール検証（隔離venvでのpipインストールと関数呼び出し確認）に基づく。pip install cloudscraperで実際に何が手に入るのか、GitHub上の説明とどこがズレているのかを中心に整理する。

cloudscraperとは何か——CloudflareのアンチボットチャレンジをPythonで自動突破する仕組み

cloudscraperは、requestsではJavaScriptを実行できずCloudflareのアンチボットページで止まってしまう問題を、内蔵JSインタープリターでチャレンジスクリプトを実行することで解決するPythonモジュールだ。Cloudflareは世界中の相当数のWebサイトでBot Management機能を有効にしており、ボットと判定した接続に対して「Checking your browser before accessing website.com」というIUAMページを表示し、JavaScriptチャレンジの実行を要求する。

通常のrequestsやurllib3はJavaScriptエンジンを持たないため、このチャレンジをパスできない。SeleniumやBrowser-Useの使い方｜AIに実ブラウザを操作させるOSSの仕組み・導入・他ツール比較【2026】のような実ブラウザ制御ツールで突破する方法もあるが、ブラウザプロセスの起動コストが大きく、軽量な定期取得には不向きだ。

cloudscraperはこの中間を取る。js2py・Node.js・ChakraCore・V8（v8eval）・nativeソルバーのいずれかのJSエンジンをPythonプロセス内で動かし、Cloudflareのチャレンジスクリプトを解析・実行してセッションクッキー（cf_clearance）を取得する。取得したクッキーは後続のリクエストに自動で付与され、以降のアクセスは通常のrequestsと同じ速度で完結する。

開発の経緯としては、オリジナル作者VeNoMouSが2019-04-16にリポジトリを作成し（GitHub API実測。PyPI最古リリースは同年5月31日の1.1.13）、公開してきたプロジェクトに対し、2025年にZied Boughdir氏（GitHub: zinzied）が大規模な改修（Enhanced Edition、PR #281「Enhanced version」・49ファイル変更／+5,208行・-1,825行）をプルリクエストで提案し、2025-06-10にマージ・GitHub Release 3.0.0としてタグ付けされた。マージ当日にはVeNoMouS自身も「Correct the owner details」「Fix owner」「re-add gitignore」といった小さな後処理コミットを重ねており、この日を境にリポジトリの所有・体制が実質的にZied Boughdir氏主導へ移った様子がうかがえる。ただし後述の通り、このコードはpip install cloudscraperでは手に入らない。

cloudscraperの主な機能：対応チャレンジとステルス機能の一覧

cloudscraperが公称する機能は次の通り。ただし★印はcloudscraper-enhanced（v3.0.0）限定の機能で、pip install cloudscraper（v1.2.71）には該当コードが存在しない。

・requests完全互換のAPI：CloudScraperオブジェクトはrequests.Sessionのサブクラスで、.get()/.post()/.cookies/.headersをそのまま利用できる
・複数JSインタープリター対応：js2py（デフォルト）/Node.js/ChakraCore/V8/nativeソルバーから選択できる
・Cloudflare v1 IUAMチャレンジの自動解決：唯一、v1.2.71でも動作する基本機能
・★Cloudflare v2チャレンジ（reCAPTCHAベース）の解決：cloudflare_v2.pyはenhanced版のみに存在
・★Cloudflare v3 JS VMチャレンジの解決：cloudflare_v3.pyはenhanced版のみに存在
・★Turnstile CAPTCHAの自動検知とソルバー連携：turnstile.pyはenhanced版のみに存在
・★ステルスモード（human-likeな遅延・ヘッダーランダム化・ブラウザ癖の再現）とスマートプロキシローテーション：stealth.py/proxy_manager.pyはenhanced版のみに存在

3rd party CAPTCHAソルバーとの連携自体（captcha=パラメータ）はv1.2.71にも実装されているため、2captcha・anticaptcha・CapSolver・CapMonster Cloud・deathbycaptcha・9kw・return_responseの指定はどちらのバージョンでも受け付ける。ただしTurnstile検知ロジックが無いv1.2.71では、Turnstile固有のソルバー連携が自動発火することはない。

なお、GitHubのREADMEは「📊 Test Results」セクションで「Cloudflare v1〜v3チャレンジ・ステルスモードとも100%成功率でテスト済み」と記載しているが、これはREADMEが案内する検証コマンド（test_all_features.py等）をメンテナ自身が実行した自己申告の結果であり、第三者機関による独立検証ではない。本記事の検証も同様に、あくまで自分たちで再現した範囲での確認である点は明記しておく。

クイックスタート：cloudscraperのインストールと最初のリクエスト

基本インストール

pip install cloudscraper

pip install cloudscraper（v1.2.71）が実際にインストールする依存パッケージはrequests・requests-toolbelt・pyparsingの3つだけ（pip show cloudscraperで確認）。js2pyはデフォルトのJSインタープリターとして案内されるが、動的インポート（JavaScriptInterpreter.dynamicImport()）で必要時にのみ読み込まれる設計のため依存関係には含まれず、使う場合はpip install js2pyを別途実行する必要がある。一方cloudscraper-enhanced（v3.0.0）はrequests・requests-toolbelt・pyparsingに加えてpyOpenSSL・pycryptodome・websocket-client・js2py・brotli・certifiをインストール時点の依存として持つ。Node.jsインタープリターを使う場合はいずれのバージョンでも別途インストールが必要。PyPIのメタデータ上、cloudscraperはPython 3.6〜3.9向けの分類のままだが、cloudscraper-enhancedはPython 3.8以上を要求しClassifiersも3.8〜3.13まで更新されている（いずれも実際には最新のPython 3.14環境でも動作を確認済み）。

# Node.jsのインストール（Ubuntu/Debian）
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo bash -
sudo apt-get install -y nodejs

requestsからの移行

CloudScraperはrequests.Sessionのサブクラスなので、importと生成部分を変えるだけで移行できる。

# Before: requests を使った従来のコード
import requests
response = requests.get("https://cloudflare-protected-site.com")

# After: cloudscraperに変更（それ以外はほぼ同じ）
import cloudscraper
scraper = cloudscraper.create_scraper()
response = scraper.get("https://cloudflare-protected-site.com")
print(response.text)

POST・セッション維持・ヘッダー指定も従来通り動く。

import cloudscraper

scraper = cloudscraper.create_scraper()

# POSTリクエスト
response = scraper.post(
    "https://example.com/api",
    json={"key": "value"},
    headers={"Content-Type": "application/json"}
)

# セッションを維持したまま複数ページを取得
scraper.get("https://example.com/login")
scraper.post("https://example.com/login", data={"user": "xxx", "pass": "yyy"})
scraper.get("https://example.com/dashboard")

基本インストールしたcloudscraper（v1.2.71）に、次章で示すenable_stealthのような高度なオプションを渡すと何が起きるのか、実際に検証した結果を先に示す。

検証結果：pip install cloudscraperで実際に何が入るのか

ここが本記事の核心部分だ。GitHubのREADMEは「v3.0.0・Enhanced Edition」「v1/v2/v3チャレンジとTurnstile CAPTCHA完全対応」と謳っているが、これはGitHubリポジトリの現在の中身の話であって、pip install cloudscraperで入るパッケージの話ではない。

実際にPyPIのJSON APIとGitHub APIを突き合わせ、隔離venv環境で両方をインストールして確認した結果は以下の通り。

実際に検証venvでenable_stealth=Trueを渡すと、v1.2.71では次のエラーで止まる。

import cloudscraper
scraper = cloudscraper.create_scraper(enable_stealth=True)
# TypeError: Session.__init__() got an unexpected keyword argument 'enable_stealth'

つまり、多くのチュートリアルやAI生成コードがそのまま貼り付けている「ステルスモード」「プロキシローテーション」のサンプルコードは、素のpip install cloudscraper環境ではそのままでは動かない。加えてファイル構成を見る限り、v1.2.71にはv2/v3チャレンジ検知やTurnstile検知のモジュール自体が存在しないため、これらの新しい防御方式に遭遇した場合は静かに失敗する（クラス自体が無いのでdetectのしようがない）。

もう一段掘り下げると、Zied Boughdir氏によるEnhanced Editionのコードは2025-06-10にGitHub本体へマージ・Release 3.0.0としてタグ付けされたが、同じコードがPyPIのcloudscraperパッケージとして公開されたことは一度もない。代わりに約4ヶ月後の2025-10-03、cloudscraper-enhancedという別名でPyPI公開された。オリジナルのcloudscraperパッケージは2023-04-25のv1.2.71を最後に更新が止まっている。

アーキテクチャ：cloudscraperがCloudflareのJSチャレンジを解く処理フロー

cloudscraper-enhanced（v3.0.0）の内部フローは以下のように構成されている（「enhanced限定」はv1.2.71に存在しない分岐）。共通するのは「まずレスポンスがCloudflareのチャレンジページかどうかを判定し、該当すればチャレンジ種別ごとに用意された専用モジュールへ処理を振り分ける」という設計そのものだ。v1.2.71はcloudflare.pyだけがこの振り分け先として存在するため、v1 IUAM以外のレスポンスが来ても分岐のしようがなく、そのまま通常のHTMLとして扱われて空振りに終わる。

JavaScriptインタープリターの選択肢（すべてのバージョンで共通）：

競合ツールとの比較：Selenium・Playwrightから商用Cloudflareスクレイパーサービスまで

cloudscraperはあくまで「JSチャレンジだけを解く」軽量ツールで、Cloudflareバイパスの選択肢はほかにもある。用途別に整理すると次の通り。

自前でPythonプロセス内に軽く収めたいならcloudscraper-enhanced、JS動的レンダリングやフォーム操作まで必要ならBrowser-UseやPlaywright、IPレピュテーション管理ごと外部化したいなら商用の「Cloudflareスクレイパー API」というのが実務上の切り分けになる。同じPython製のクローラーとしては、大規模サイトマッピング用途ではSpider Rs：Rust製の高速Webクローラーで大規模サイトマッピングを実現、特定サイト特化のスクレイパーとしてはreddit-universal-scraper：Redditのあらゆるコンテンツを自動収集するPythonツール完全ガイドも参考になる。

商用の「Cloudflareスクレイパー API」（ScraperAPI・ZenRows・Bright Data Web Unlockerなど）は、自前でプロキシプールやブラウザフィンガープリントを管理せず、リクエストを1本投げるだけでHTML/JSONを返してもらう課金制のマネージドサービスだ。cloudscraperのようにJS実行そのものを自分のプロセス内で行うのではなく、Cloudflareのチャレンジ解決を丸ごとベンダー側のインフラに委譲する点が根本的に異なる。大量リクエストやIPブロック対策込みでの安定運用を優先し、開発コストより運用費を許容できる場合の選択肢になる。

なお2026年時点でCloudflareにはSuper Bot Fight Modeや商用WAF（Akamai等）のような、cloudscraperの設計対象外の防御層も存在する。これらに遭遇した場合の症状は403/521/1015エラーの連発や、チャレンジページへの永久ループになりやすい。cloudscraper-enhancedでも解決しない場合は、Playwright＋Stealthプラグインなど実ブラウザ系への切り替えが現実的な選択になる。

実践的な使い方：Cloudflare保護サイトをスクレイピングする3つのシナリオ

シナリオ1：価格監視・比較ツールの構築

ECサイトの価格データを定期取得する場合、対象がCloudflareのv1 IUAM程度であれば素のcloudscraperで足りる。

import cloudscraper
import time
import json
from datetime import datetime

scraper = cloudscraper.create_scraper()

def fetch_price(url: str) -> dict:
    """商品ページから価格情報を取得"""
    response = scraper.get(url)
    if response.status_code == 200:
        return {
            "timestamp": datetime.now().isoformat(),
            "url": url,
            "status": "ok",
            "html_length": len(response.text)
        }
    return {"status": "error", "code": response.status_code}

urls = ["https://example-shop.com/product/1", "https://example-shop.com/product/2"]
for url in urls:
    result = fetch_price(url)
    print(json.dumps(result, ensure_ascii=False))
    time.sleep(5)  # サーバー負荷を考慮した待機

シナリオ2：モダンなCloudflare設定への対応（cloudscraper-enhanced限定）

v2/v3チャレンジやTurnstileが出るサイトでは、cloudscraper-enhancedのステルスモードとプロキシローテーションを使う。

import cloudscraper  # pip install cloudscraper-enhanced が前提

scraper = cloudscraper.create_scraper(
    interpreter='nodejs',
    browser={'browser': 'chrome', 'platform': 'windows', 'mobile': False},
    enable_stealth=True,
    stealth_options={
        'min_delay': 2.0,
        'max_delay': 6.0,
        'human_like_delays': True,
        'randomize_headers': True
    },
    rotating_proxies=[
        'http://proxy1:8080',
        'http://proxy2:8080',
    ],
    captcha={
        'provider': '2captcha',
        'api_key': 'YOUR_2CAPTCHA_API_KEY'
    }
)

response = scraper.get("https://target-site.com")

シナリオ3：Cloudflareトークンを他ツールへ引き渡す

curlや別のHTTPクライアントで使うために、cloudscraperで取得したトークンだけを取り出す方法。

import cloudscraper

# Cloudflareトークンとユーザーエージェントを取得
tokens, user_agent = cloudscraper.get_tokens("https://target-site.com")
print(f"cf_clearance: {tokens.get('cf_clearance', 'N/A')}")

# クッキー文字列として取得（curl等での再利用向け）
cookie_string, user_agent = cloudscraper.get_cookie_string("https://target-site.com")
# 重要：取得したuser_agentを後続のリクエストでも必ず同じものを使うこと
# （user-agentとcf_clearanceの組み合わせが変わるとCloudflareに弾かれる）

スクレイピングの合法性について

cloudscraperの利用は技術的にはCloudflareの認証チャレンジを自動処理しているだけだが、対象サイトの利用規約・robots.txt・著作権によって法的リスクが決まる。日本国内では2018年改正・2019年1月施行の著作権法第30条の4により情報解析目的の学習データ収集は適法とされるが、商用転載目的だと不正競争防止法上の論点が生じうる。コード自体ではなく取得後のデータ利用に注意が必要だ。

取得したデータをどう扱うかに加えて、取得の過程そのものにも配慮が要る。サーバーへの過度な同時アクセスは、Cloudflareに検知される前に対象サイト自体へ負荷をかけてしまう。scraper.get()を並列で大量に投げるのではなく、time.sleep()等で間隔を空け、対象サイトの負荷状況を見ながら調整するのが実務上の基本になる。

まとめ：cloudscraperを選ぶべき人・避けるべき人

cloudscraperは、requestsへの最小限の変更でCloudflare保護サイトへのアクセスを自動化できる実用的なOSSモジュールだ。ただし本記事の検証結果通り、pip install cloudscraperとpip install cloudscraper-enhancedでは対応チャレンジの範囲がまったく異なる。まず自分の環境のcloudscraper.__version__を確認し、v1.2.71ならenhanced版への入れ替えを検討するところから始めるとよい。

・軽量な旧型Cloudflare設定のサイトを少量取得したいだけなら、素のcloudscraperで十分
・v2/v3チャレンジやTurnstileが出るモダンな設定が対象なら、cloudscraper-enhanced一択
・SPAやクリック操作が絡む場合はSelenium/Playwright/Browser-Useへ
・IP管理やチャレンジ更新の追従を外部化したいなら商用Cloudflareスクレイパー APIを検討
・GitHub本体は413日間コミットが無いため（2026-07-28時点）、新しいCloudflareの変更に即座に追従されるとは限らない前提で運用する

プロダクション用途では、バージョン確認・エラーハンドリング・リトライロジックを組み込んだ上で利用することを推奨する。CI/CDパイプラインで使う場合は、requirements.txtにcloudscraper==1.2.71のようにバージョンを固定しない限り、将来どちらのパッケージ名を指しているかが読み手に伝わりにくい。パッケージ名とバージョンの両方をコメントで明記しておくと、後から読むメンバーが同じ混乱を繰り返さずに済む。

参照ソース

• VeNoMouS/cloudscraper - GitHub
• cloudscraper - PyPI
• cloudscraper-enhanced - PyPI
• Cloudflare Bot Management 公式ドキュメント
• Cloudflare Turnstile 公式ドキュメント
• requests ライブラリ公式ドキュメント