gallery-dl

1.31.10 · active · verified Thu Apr 16

gallery-dl is a command-line program designed to download image galleries and collections from a wide range of image hosting sites. It is actively maintained with frequent updates, primarily to address changes in website structures and add support for new sites. The current version is 1.31.10, and it maintains a rapid release cadence.

Common errors

```
gallery-dl: error: unrecognized arguments: https://some.site/url with spaces
```
cause The URL contains characters (like spaces or shell metacharacters such as '&') that are interpreted by the shell as separate arguments, or the URL itself is not properly quoted.

fix Always wrap URLs in double quotes (e.g., `gallery-dl "https://some.site/url with spaces"`) to ensure the shell passes the entire URL as a single argument to `gallery-dl`.
```
ERROR: [extractor-name] An unexpected error occurred: KeyError: 'data'
```
cause The website's structure has changed, and the `gallery-dl` extractor for that site is outdated and cannot find expected data elements.

fix This typically indicates a broken extractor. Upgrade `gallery-dl` to the latest version (`pip install --upgrade gallery-dl`). If the issue persists, check the GitHub issues for `gallery-dl` to see if a fix is in progress or report a new issue.
```
ERROR: [extractor-name] Login required
```
cause You are attempting to download content that requires authentication without providing valid credentials (e.g., cookies or login details).

fix Provide authentication credentials. For many sites, this means using a cookies file (e.g., `--cookies cookies.txt`) generated by a browser extension. Refer to the `gallery-dl` documentation for the specific site's authentication requirements.

Warnings

breaking Extractors for specific websites frequently break due to upstream changes on those sites (e.g., API changes, HTML structure modifications), leading to download failures or incomplete data.
Fix: Regularly update to the latest `gallery-dl` version (`pip install --upgrade gallery-dl`). If the issue persists after updating, check the official GitHub issues for known problems with the specific site or report a new one.
gotcha Authentication for many sites requires manually acquiring and providing cookies or login credentials. These methods can be site-dependent, may require browser extensions, and can change without notice.
Fix: Consult the `gallery-dl` documentation for the specific site you are trying to download from regarding authentication methods. Common approaches include using `--cookies` with a Netscape-formatted cookie file or `--username`/`--password` options if supported.
deprecated As of v1.31.10, DeviantArt 'original' downloads are disabled by default. This change might result in lower-quality images being downloaded unless explicitly configured.
Fix: To enable original DeviantArt downloads, you may need to adjust your configuration or use specific command-line options. Refer to the DeviantArt extractor documentation within `gallery-dl` for details on how to re-enable this feature.

Install

pip install gallery-dl Install latest version

Imports

main
```
from gallery_dl import main
```
While primarily a CLI tool, `gallery_dl.main.main()` can be called programmatically, typically with a list of arguments mimicking command-line input. It is generally advised to use it via the command line.

Quickstart

Downloads all available images from a public Imgur gallery, saving them to the current directory.

gallery-dl "https://imgur.com/gallery/1324567"

view raw JSON →