# gallery-dl: A Command-Line Downloader for Image Galleries and Collections > gallery-dl is a Python command-line tool that pulls image galleries and collections from sites such as danbooru, Pixiv, Twitter, DeviantArt and Mangadex. It is flexible and scriptable, but it is not a graphical app and its site coverage depends on extractors that break when sites change. **mikf/gallery-dl** — Command-line program to download image galleries and collections from several image hosting sites - Repository: https://github.com/mikf/gallery-dl - Website: https://discord.gg/rSzQwRvGnE - Stars: 19,875 · Forks: 1,495 - Language: Python - License: GPL-2.0 - Published: 2026-09-21 · Updated: 2026-09-21 · Language: en - Canonical page: https://hysenlabs.com/projects/mikf-gallery-dl ## What gallery-dl is for, and who it is not for gallery-dl downloads image galleries and collections from a list of image hosting sites. The README describes it as a cross-platform command-line program with many command-line and configuration options plus file-naming capabilities. The intended user is someone who already works in a shell: the tool takes URLs as arguments and writes files to disk, with no graphical interface mentioned anywhere in the README or the repository layout. If you want a window with thumbnails and a queue, this is the wrong project. The scope is broader than a single-site scraper. The repository topics list danbooru, deviantart, kemono, mangadex, pixiv, tumblr and twitter, and the README points to docs/supportedsites.md for the full list. That file, not the README, is the authority on whether a given site is covered. Treat site coverage as a moving target: extractors are written per site, and a site redesign can break one without affecting the rest. One structural fact matters before anything else. The README states that active development has moved to Codeberg, with a link to the announcement issue on GitHub. The GitHub repository still exists and the last push was on 2026-09-19, so it is not abandoned, but the canonical home is now Codeberg. Anyone filing issues or tracking changes should go there rather than to the GitHub mirror. ## How the extractor and downloader pipeline works The package is organised around two kinds of components, visible in the PACKAGES list in setup.py: gallery_dl.extractor, gallery_dl.extractor.utils, gallery_dl.downloader and gallery_dl.postprocessor. An extractor takes a URL, recognises the site, and yields metadata records for each image or video it finds. A downloader turns those records into files on disk. Postprocessors run afterwards for site-specific work. That split explains most of the tool's behaviour. Because extraction and downloading are separate, gallery-dl can print URLs instead of saving files, which is what the -g option does in the README example for a Twitter status. It also means filtering happens at extraction time: the README shows --chapter-filter with a chapter-number expression for manga, so excluded chapters are never queued for download. Optional dependencies attach to specific stages rather than the core. yt-dlp or youtube-dl is needed for HLS/DASH video downloads and the ytdl integration. FFmpeg is needed for Pixiv Ugoira conversion, and mkvmerge is listed for accurate Ugoira frame timecodes. PySocks adds SOCKS proxy support. PyYAML and toml add configuration file formats, and Psycopg adds PostgreSQL archive support, which suggests the archive of already-downloaded items can live in a database rather than only on disk. File naming is handled by a formatting layer the README links to separately. That is where directory structure, filenames and metadata substitution are configured, and it is the part most likely to need attention on a first run, because the defaults may not match how you want a large collection laid out. ## Installing gallery-dl and running a first download The README gives pip as the primary install path for stable releases on PyPI. On Windows the note says to use py instead of python. ```bash python -m pip install -U gallery-dl ``` After that, gallery-dl should be on your PATH. The README also advises keeping pip, setuptools and wheel current before installing: ```bash python -m pip install --upgrade pip setuptools wheel ``` If you would rather not manage a Python environment, prebuilt executables with a Python interpreter and the required packages bundled are published for Windows and Linux, and the README notes the Windows build needs the Microsoft Visual C++ Redistributable Package (x86). Other documented routes include snap install gallery-dl on Snapd-based Linux distributions, choco install gallery-dl and scoop install gallery-dl on Windows, brew install gallery-dl on macOS or Linux, sudo port install gallery-dl on macOS with MacPorts, and Nix or Home Manager. A first real use is a single URL. The README example downloads from danbooru via a tag search: ```bash gallery-dl "https://danbooru.donmai.us/posts?tags=bonocho" ``` Expect files to appear in a directory derived from the site and the search, with names produced by the formatting rules. To check what would be fetched without writing anything, the README shows the URL-printing mode combined with credentials for a site that needs authentication: ```bash gallery-dl -g -u "" -p "" "https://twitter.com/i/web/status/604341487988576256" ``` The README states that gallery-dl --help lists all command-line options, and docs/options.md is the fuller reference. For Docker, the repository ships a Dockerfile, and the README documents both building it and pulling mikf123/gallery-dl or ghcr.io/mikf/gallery-dl, with a dev tag for nightly images built from the latest commit. ## Where gallery-dl breaks or becomes the wrong choice The first limitation is inherent to the design: every supported site needs an extractor, and extractors depend on the site's current HTML, API or URL structure. The README does not promise stability for any individual site. If a host changes how a gallery page is rendered, downloads from that host can stop returning results while the rest of the tool keeps working. There is no documented fallback that recovers the missing items. The second is authentication. The README's own example passes a username and password on the command line for a Twitter status. Credentials in shell history are a real exposure, and the README does not present that example as a recommended long-term pattern. Cookie-based access exists through the --cookies-from-browser option, and the optional SecretStorage dependency is described as providing GNOME keyring passwords for that option, which ties that path to a GNOME keyring environment. On a headless server or a non-GNOME desktop, that specific convenience is not available. The third is the dependency surface. Core requires Python 3.8+ and requests. Everything else is optional but each optional piece buys a specific capability: video downloads, Ugoira conversion, SOCKS proxies, YAML or TOML config, PostgreSQL archives, Jinja templates, Brotli and Zstandard compression, native system certificates. A minimal install will silently lack those features rather than warn you, so a configuration copied from elsewhere may reference a capability the local install does not have. Finally, if your goal is a one-off save of a few images from a site you visit once, a browser extension or manual saving is less setup than a Python install plus a config file. ## gallery-dl compared with yt-dlp The most useful comparison is with yt-dlp, which the README lists as an optional dependency rather than a rival. The two overlap in shape: both are command-line Python downloaders with per-site extractors, both accept URLs as arguments, and gallery-dl can call yt-dlp through its ytdl integration for HLS and DASH video. The difference is the unit of work. yt-dlp is built around video and audio streams, with format selection, merging and remuxing as central concerns. gallery-dl is built around image galleries and collections, so its extractors produce sets of individual images, and its configuration is oriented toward file naming, directory layout and filtering of gallery items such as manga chapters. If your target is a video page, yt-dlp is the more direct tool. If your target is a tag search, a user's gallery or a chapter list, gallery-dl models that shape natively. Because gallery-dl already depends on yt-dlp for video work, running both is not redundant. A practical split is gallery-dl for the gallery URLs and yt-dlp for anything that is fundamentally a video stream. ## Maintenance, licensing and upgrade cost The repository is not archived and the last push was on 2026-09-19, with releases v1.32.13 on 2026-09-19, v1.32.12 on 2026-09-12 and v1.32.11 on 2026-09-04. That cadence is frequent, and frequent releases on a per-site extractor model mean the upgrade path is also the fix path: when a site breaks, the fix usually arrives as a new version rather than a configuration change. Upgrading is a single pip command, and the README also documents installing the latest development version directly from the master archive with --force-reinstall --no-deps, omitting --no-deps if requests has not been installed yet. The cost is not the upgrade itself but the tracking. There is no long-term support branch described in the README, and the project has moved its development to Codeberg, so changelog and issue activity should be followed there. The CHANGELOG.md file exists at the repository root for release history. On licensing, gallery-dl is GPL-2.0. The README does not discuss licence implications for downstream use, and nothing here should be read as legal advice. The practical point for an engineer is that GPL-2.0 is a copyleft licence: if you redistribute a modified version or incorporate the code into a distributed product, the licence terms apply. Using the tool as an end user to download files is a different situation from shipping it inside your own application. If that distinction matters to your project, read the LICENSE file and get proper advice. ## Conclusion gallery-dl suits people comfortable with a terminal who want scripted, configurable downloads from many image hosts, and it is a poor fit for anyone who needs a graphical interface or a guarantee that every site keeps working. Before adopting it, check docs/supportedsites.md for the sites you actually use, confirm the Python 3.8+ requirement and the requests dependency, and read the Codeberg migration notice, because active development has moved away from the GitHub repository. ## FAQ ### What is gallery-dl? It is a cross-platform command-line program that downloads image galleries and collections from several image hosting sites. It is written in Python and configured through command-line options and a configuration file. ### How to install gallery-dl? The stable release is on PyPI and installs with python -m pip install -U gallery-dl, using py instead of python on Windows. Prebuilt executables for Windows and Linux, plus snap, Chocolatey, Scoop, Homebrew, MacPorts, Nix and Docker routes, are also documented in the README. ### What is the command to update gallery-dl? The README gives python -m pip install -U gallery-dl as the way to install or upgrade the stable release. It also documents installing the latest development version from the master archive with pip. ### Which websites support gallery-dl? The README points to docs/supportedsites.md for the full list of supported sites. The repository topics name danbooru, deviantart, kemono, mangadex, pixiv, tumblr and twitter as examples. ### How do I use gallery-dl for Twitter? The README example passes a Twitter status URL with -g to print the direct image URL and -u and -p for username and password authentication. Cookie access from a browser is available through the --cookies-from-browser option. ## Sources - [License: GPL-2.0](https://github.com/mikf/gallery-dl/blob/master/LICENSE) - [mikf/gallery-dl on GitHub](https://github.com/mikf/gallery-dl) - [Project website](https://discord.gg/rSzQwRvGnE) - [README](https://github.com/mikf/gallery-dl/blob/master/README.md) - [Releases](https://github.com/mikf/gallery-dl/releases) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/mikf-gallery-dl