gallery-dl使い方完全ガイド2026｜269サイト対応の画像一括ダウンロードをyt-dlpと使い分ける

gallery-dlは、画像ギャラリー投稿サイトから作品を一括ダウンロードするPython製のコマンドラインツールだ。動画・音声のyt-dlpに対して、こちらは静止画側の事実上の標準にあたる。本記事はv1.32.9を実際に手元へインストールし、対応サイト数・設定ファイルの探索順・pixivの認証エラーをすべて実測してから書いている。加えて、2026年4月に開発の本体がGitHubからCodebergへ移ったという、日本語ではほとんど共有されていない変更も扱う。

この記事は画像ギャラリー取得のCLI「gallery-dl」を解説します。自動化ツール全体の地図はAI自動化ツール｜ノーコードからコードまで2026年版の比較と選び方をご覧ください。

gallery-dlとは：yt-dlpと守備範囲が重ならない理由

gallery-dlは「画像ホスティングサイトから画像ギャラリーとコレクションをダウンロードするコマンドラインプログラム」と公式に説明されている。ポイントはギャラリー単位で扱うことだ。1枚のURLを渡して1枚落とすのではなく、「この投稿者の全作品」「このタグの検索結果」といった集合を展開してまとめて取得する。

yt-dlpとの違いは、しばしば「動画か画像か」だけで語られるが、実務上はもう一段深い。

最後の行が重要だ。gallery-dlはytdlという名前のダウンローダーバックエンドを内蔵しており、その実装を読むとyt-dlpを優先し、無ければyoutube-dlにフォールバックするようになっている。

# gallery_dl/ytdl.py — import_module（実際のソース）
def import_module(module_name):
    if module_name is None:
        try:
            return __import__("yt_dlp")
        except (ImportError, SyntaxError):
            return __import__("youtube_dl")
    return util.import_file(module_name)

つまり「gallery-dlか、yt-dlpか」という二者択一ではなく、画像は自前で処理し、動画に当たったらyt-dlpへ委譲するという設計だ。両方入れておくのが正しい構成になる。手元の環境では、内蔵ダウンローダーはcommon / http / text / ytdlの4つが確認できた。

2026年4月、開発の本体がCodebergへ移った

日本語の解説記事でまったく触れられていない変更がある。gallery-dlの開発は2026年4月5日にCodebergへ移った。READMEの冒頭にも「Active development has moved to Codeberg」と明記されている。

アナウンス（GitHub issue #9374）の内容を整理すると、次のようになる。

・アナウンス本文は移行の理由を、DMCAテイクダウン通知と、GitHubに残るために求められたコミット履歴の書き換え・コード削除を受けて（in light of）と説明している
・GitHubリポジトリは残るが、用途はCI/CD・自動化ワークフロー（テスト、nightlyバイナリ、Dockerイメージ）に限定される
・公式の表現では「gallery-dlの実際のコードはもう入らない」
・GitHubはアーカイブも凍結もされていない。★19,252・issueも開いたまま

実際にGitHub側の直近コミットを確認すると、release version 1.32.9のようなリリース同期のコミットだけが並んでいた。「更新が止まったリポジトリ」ではなく「役割が変わったリポジトリ」だと理解するのが正確だ。

実務上、これは次の3点に効いてくる。

なおpip install gallery-dlの参照先はPyPIなので変わらない。安定版をpipで入れている限り、この移行を意識する必要はない。影響を受けるのは、issueを追う人・ソースを読む人・実行ファイルを直接落としている人だ。

インストールと最初の1コマンド

安定版はPyPIで配布されている。Python 3.8以上とRequestsがあれば動く。

# 安定版をインストール（PyPI経由。Codeberg移行の影響を受けない）
python -m pip install -U gallery-dl

# バージョンと動作確認
gallery-dl --version

# 何もダウンロードせず、対象URLの中身だけ見る
gallery-dl --simulate "https://example.com/gallery/xxxx"

Windowsではpythonではなくpyを使う。pip以外にも、Homebrew（brew install gallery-dl）、Scoop、Chocolatey、MacPorts、Snap、Dockerイメージ（ghcr.io/mikf/gallery-dl）が用意されている。手元のmacOSではpip install後にgallery-dl --versionが1.32.9を返した。

--simulateは最初に必ず覚えておきたい。ファイルを書かずにURLの解決結果だけを確認するモードで、対応していないURLを渡していないか、認証が必要かを消費なしで判定できる。

対応サイトを実測で数える

公式READMEは「several image hosting sites（いくつかの画像ホスティングサイト）」としか書いておらず、具体的な件数を示していない。そこで実際に数えた。

# 対応サイト（Category）のユニーク件数を数える
gallery-dl --list-extractors \
  | grep '^Category: ' \
  | sed 's/^Category: //; s/ - Subcategory.*//' \
  | sort -u | wc -l

v1.32.9での結果は次のとおり。

「対応サイト数」として意味があるのは269のほうだ。1,015は「pixivのartworks」「pixivのranking」のように同じサイトの取得パターンを別々に数えた数なので、他ツールの公称値と横並びで比べると過大になる。

日本のユーザーに関係が深いところでは、pixiv・fanbox・fantia・booth・skeb・seiga・kemonoが含まれていた。pixivのサブカテゴリはartworks / user / ranking / search / series / favorite / followed / sketch / unlisted / pixivisionなど18種類あり、さらにpixiv-novelが独立したCategoryとして小説（novel / series / user / bookmark）に対応している。「pixivの一括ダウンロード」でやりたいことのほとんどは、この時点で守備範囲に入っている。

設定ファイルと認証：ここで9割つまずく

gallery-dlはコマンドラインオプションよりもJSON設定ファイルが主戦場になる。そして日本語の解説記事は、この探索順の説明が曖昧か、片方しか書いていないことが多い。実測すると3か所だった。

-v（verbose）で実行すると、起動時に読み込んだ設定ファイルが列挙される。手元では設定を置いていなかったため、次のように空リストが出た。

[gallery-dl][debug] Version 1.32.9
[gallery-dl][debug] Python 3.14.4 - macOS-14.5-arm64
[gallery-dl][debug] requests 2.34.2 - urllib3 2.7.0
[gallery-dl][debug] Configuration Files []

Configuration Files []は「設定ファイルを1つも読んでいない」という意味だ。「設定を書いたのに効かない」ときは、まずここを見れば置き場所を間違えたのかどうかが一発でわかる。探索先は次の3か所である。

PyYAMLやtomlを追加で入れればYAML・TOMLでも書けるが、素の状態ではJSONだけが確実に読める。

pixivは「URLが正しくても」認証で止まる

ログイン必須のサイトでは、URLの形式が完全に正しくても認証で停止する。手元でpixivの作品URLに--simulateをかけたところ、次のエラーになった。

[pixiv][error] AuthenticationError: 'refresh-token' required.
Run `gallery-dl oauth:pixiv` to get one.

これは不具合ではなく仕様だ。エラーメッセージが解決コマンドをそのまま提示している点が親切で、gallery-dl oauth:pixivを実行してrefresh-tokenを取得し、設定ファイルに書き込めばよい。

{
  "extractor": {
    "base-directory": "~/gallery-dl",
    "pixiv": {
      "refresh-token": "取得したトークンを入れる",
      "directory": ["pixiv", "{user[account]}"],
      "filename": "{id}_{num}.{extension}"
    }
  }
}

Cookieを使う手もある。--cookies-from-browserでブラウザのCookieを渡せるが、GNOMEキーリングを使う環境ではSecretStorageの追加インストールが必要になる。「トークン方式のほうが再現性が高く、CIにも載せやすい」というのが実務上の結論だ。

実運用のパターン：巡回・重複回避・メタデータ

gallery-dlが真価を発揮するのは、単発の取得ではなく繰り返し実行する巡回だ。処理の流れは次のようになる。

繰り返し実行するときに効くのが--download-archiveだ。取得済みIDをSQLiteに記録し、次回以降スキップする。

# 取得済みを記録して差分だけ取る（2回目以降が速い）
gallery-dl --download-archive ~/gallery-dl/archive.db "対象URL"

# メタデータをJSONで併記（あとで検索・分析に使える）
gallery-dl --write-metadata "対象URL"

# 出力先の階層とファイル名を指定する
gallery-dl -D ~/gallery-dl/pixiv -f "{id}_{num}.{extension}" "対象URL"

--write-metadataで吐き出されるJSONには、投稿者・タグ・投稿日時などサイト固有のフィールドがそのまま入る。画像そのものより、この構造化メタデータのほうが後工程で価値を持つことが多い。取得したタグ列をそのままデータセットのラベルにする、投稿日時で時系列の傾向を見る、といった使い方ができる。

なお--download-archiveと--write-metadataは目的が違うので併用が前提だ。前者は「もう取ったか」の判定用、後者は「何を取ったか」の記録用である。

どれを選ぶか：静止画・動画・ライブ配信の分担

ここまでを踏まえると、ダウンローダーの選定は「どれが最強か」ではなく対象の性質で分担する問題になる。

gallery-dlはytdlバックエンド経由でyt-dlpを呼ぶので、両方入れておくのが実質的な標準構成になる。ライブ配信だけは時間軸の性質が違うため、Streamlinkのような専用ツールが要る。

運用上の注意も1つ。gallery-dlは並列度やレート制限をデフォルトでは強くかけない。サイトへの負荷は自分で制御する必要があるため、大量巡回するときは設定ファイルのsleep・sleep-requestを明示して間隔を空けるのが礼儀であり、アカウント保全の観点でも合理的だ。

まとめ

・gallery-dlは静止画ギャラリー側の標準ツール。yt-dlpと競合せず、内部でyt-dlpを呼ぶ（yt_dlp優先、無ければyoutube_dl）
・v1.32.9の実測で対応サイト269件・extractor定義1,015件。公称値ではなく自分で数えられる
・2026年4月5日に開発の本体がCodebergへ移行。GitHubはCI/CD・nightly・Dockerイメージ用として残り、アーカイブはされていない。pipユーザーは影響を受けない
・設定ファイルの探索先は実測で3か所。-vのConfiguration Files []で読み込み状況が確認できる
・pixiv等はURLが正しくてもトークンが無ければ必ず止まる。gallery-dl oauth:pixivで取得して設定に書く

参照ソース

• mikf/gallery-dl — GitHub リポジトリ（★19,252 / GPL-2.0 / 2026-08-19時点）
• [Announcement] Moving to Codeberg — GitHub issue #9374（2026-04-05）
• mikf/gallery-dl — Codeberg（移行後の開発本体）
• gallery-dl 公式ドキュメント（configuration / options / formatting）
• 実測環境：gallery-dl 1.32.9 / Python 3.14.4 / macOS 14.5 arm64（--list-extractors・-v --simulateの出力）