閉じる

Seleniumヘッドレスモードでファイルダウンロードを有効にする設定手順

広告

Seleniumを使用したWebブラウザの自動操作において、画面を表示させずに実行する「ヘッドレスモード」は、サーバー上での運用やリソースの節約に欠かせません。

しかし、ヘッドレスモードではセキュリティ上の制約から、デフォルト設定のままではファイルのダウンロードがブロックされてしまうという問題があります。

本記事では、Python環境においてSeleniumのヘッドレスモードを利用しつつ、指定したディレクトリにファイルを確実にダウンロードするための設定手順を解説します。

目次 [ close ]
  1. ヘッドレスモードでダウンロードが制限される理由
  2. ChromeOptionsを利用した基本設定
    1. ダウンロードディレクトリの指定
    2. セキュリティ制限の解除設定
  3. execute_cdp_cmdによる権限付与
  4. 実装サンプルコード
  5. Firefoxにおける設定手順
  6. 注意点とトラブルシューティング
  7. まとめ

ヘッドレスモードでダウンロードが制限される理由

通常のブラウザ実行時とは異なり、ヘッドレスモードは「ユーザーによる明示的な操作」がないと見なされるため、ブラウザのセキュリティ機能が強化されます。

Google Chromeなどのブラウザエンジンは、悪意のあるスクリプトが勝手にファイルを保存することを防ぐため、UIを持たない状態でのダウンロードをデフォルトで無効化しています。

そのため、自動化スクリプト側で明示的に「ダウンロードを許可する」という命令をブラウザ側に伝える必要があります。

2026年現在のSelenium 4以降の環境では、Chrome DevTools Protocol（CDP）を介した設定や、新しいヘッドレスモード（–headless=new）の活用が推奨されています。

ChromeOptionsを利用した基本設定

まずは、SeleniumのChromeOptionsを使用して、ダウンロード先のリポジトリや挙動を制御する基本設定を行います。

ダウンロードディレクトリの指定

ブラウザのプロファイル設定を変更することで、ファイルが保存されるパスを指定できます。

prefs（環境設定）の中に、保存先パスとなるdownload.default_directoryを定義することが重要です。

また、「ダウンロード時の確認ダイアログを表示させない」ための設定も併せて記述します。

セキュリティ制限の解除設定

ヘッドレスモード特有の制限を回避するため、profile.default_content_settings.popupsを「0」に設定します。

これにより、保存確認のポップアップで処理が停止するのを防ぐことができます。

さらに、セーフブラウジング機能がダウンロードを阻止しないよう、関連するフラグをオフにする設定も有効です。

execute_cdp_cmdによる権限付与

ChromeOptionsの設定だけでは、ヘッドレスモードでのダウンロードが完全に許可されないケースがあります。

この問題を解決するために、execute_cdp_cmdメソッドを使用してブラウザの深層設定（CDP）を操作します。

具体的には、Page.setDownloadBehaviorというコマンドを発行し、ヘッドレス状態でもダウンロードを許可（allow）するように指定します。

この処理は、ドライバを起動した直後、またはURLにアクセスする前に実行する必要があります。

実装サンプルコード

以下に、Pythonを使用したSeleniumの具体的な設定コードを記述します。

このコードでは、カレントディレクトリに「downloads」というフォルダを作成し、そこへファイルを保存する設定を行っています。

Python
import os
from selenium import webdriver
from selenium.webdriver.chrome.service import Service
from selenium.webdriver.chrome.options import Options

# ダウンロード先の絶対パスを取得
download_dir = os.path.join(os.getcwd(), "downloads")
if not os.path.exists(download_dir):
    os.makedirs(download_dir)

# Chromeのオプション設定
chrome_options = Options()
# 新しいヘッドレスモードを指定（2026年時点の推奨）
chrome_options.add_argument('--headless=new')

# ダウンロード設定の定義
prefs = {
    "download.default_directory": download_dir, # 保存先
    "download.prompt_for_download": False,       # ダイアログ非表示
    "download.directory_upgrade": True,
    "safebrowsing.enabled": True                 # セーフブラウジング
}
chrome_options.add_experimental_option("prefs", prefs)

# ドライバの起動
driver = webdriver.Chrome(options=chrome_options)

# ヘッドレスモードでのダウンロードを許可するCDPコマンドの実行
driver.execute_cdp_cmd("Page.setDownloadBehavior", {
    "behavior": "allow",
    "downloadPath": download_dir
})

# テスト実行（ダウンロードボタンがあるページへアクセス）
try:
    driver.get("https://example.com/download-page")
    download_link = driver.find_element("id", "download-button")
    download_link.click()
    print("ダウンロード処理を開始しました。")
finally:
    # 完了を待機するための処理をここに記述
    # driver.quit()
    pass
実行結果
ダウンロード処理を開始しました。
（指定したディレクトリにファイルが保存される）

Firefoxにおける設定手順

Firefoxを使用する場合も、Chromeと同様にプロファイル設定（Options）を変更することで対応可能です。

Firefoxではset_preferenceメソッドを使用し、browser.download.dirにパスを指定します。

また、browser.download.folderListを「2」に設定することで、カスタムディレクトリの使用を強制できます。

FirefoxのヘッドレスモードはChromeに比べてダウンロードの制限が緩やかですが、同様の明示的な指定が推奨されます。

注意点とトラブルシューティング

設定を行ってもダウンロードが始まらない場合、いくつかの要因が考えられます。

ダウンロード完了の待機処理

Seleniumはクリック操作の直後にプログラムが終了してしまうことがあります。

ファイルが完全にダウンロードされるまで、ディレクトリ内のファイルを監視するか、適切な待機時間を設ける必要があります。

拡張子が「.crdownload」などの一時ファイルが消えるまで待機するロジックを組むのが一般的です。

パスの指定形式

download.default_directoryに指定するパスは、必ず絶対パスで指定してください。

相対パスでは正しく認識されず、デフォルトのダウンロードフォルダ（Downloadsなど）に保存されてしまうことがあります。

要素のクリック失敗

ヘッドレスモードでは画面サイズ（ウィンドウサイズ）が原因でボタンが隠れている場合があります。

driver.set_window_size(1920, 1080)のように、十分な画面解像度を設定してから操作を行ってください。

まとめ

Seleniumのヘッドレスモードでファイルをダウンロードするためには、通常のオプション設定に加えて、CDPコマンドによる権限付与が非常に有効です。

特にChromeを使用する場合は、Page.setDownloadBehaviorの設定を忘れないようにしましょう。

適切なディレクトリ設定と待機処理を組み合わせることで、ブラウザを非表示にした状態でも安定した自動ダウンロード環境を構築できます。

本記事で紹介した設定を活用し、効率的なブラウザ自動化を実現してください。

URLをコピーしました！