You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
thatfuckingbird 224b883ff4
[danbooru] add option for extended metadata extraction (#1458)
1 day ago
.github/workflows build executables with SOCKS proxy support (closes #1424) 1 week ago
bin return with non-zero exit status on error 1 year ago
docs [danbooru] add option for extended metadata extraction (#1458) 1 day ago
gallery_dl [danbooru] add option for extended metadata extraction (#1458) 1 day ago
scripts [yuki] remove module for 2 days ago
snap [snap] allow access user's .netrc for site authentication (#1352) 1 month ago
test unescape items in text.split_html() 2 weeks ago
.gitignore fix data file inclusion in source distributions 1 year ago build executables with SOCKS proxy support (closes #1424) 1 week ago
LICENSE initial commit 7 years ago add (#730) 11 months ago
Makefile update docs/supportedsites 1 month ago
README.rst release version 1.17.2 2 weeks ago
requirements.txt increase required 'requests' version to 2.11.0 2 years ago
setup.cfg fix flake8 errors, ignore W504 3 years ago update README.rst and 4 months ago



*gallery-dl* is a command-line program to download image galleries and
collections from several image hosting sites (see `Supported Sites`_).
It is a cross-platform tool with many configuration options
and powerful filenaming capabilities.

|pypi| |build| |gitter|

.. contents::


- Python_ 3.4+
- Requests_


- FFmpeg_: Pixiv Ugoira to WebM conversion
- youtube-dl_: Video downloads



The stable releases of *gallery-dl* are distributed on PyPI_ and can be
easily installed or upgraded using pip_:

.. code:: bash

$ python3 -m pip install -U gallery-dl

Installing the latest dev version directly from GitHub can be done with
pip_ as well:

.. code:: bash

$ python3 -m pip install -U -I --no-deps --no-cache-dir

Note: Windows users should use :code:`py -3` instead of :code:`python3`.

It is advised to use the latest version of pip_,
including the essential packages :code:`setuptools` and :code:`wheel`.
To ensure these packages are up-to-date, run

.. code:: bash

$ python3 -m pip install --upgrade pip setuptools wheel

Standalone Executable

Prebuilt executable files with a Python interpreter and
required Python packages included are available for

- `Windows <>`__
- `Linux <>`__

| Executables build from the latest commit can be found at


Linux users that are using a distro that is supported by Snapd_ can install *gallery-dl* from the Snap Store:

.. code:: bash

$ snap install gallery-dl


Windows users that have Chocolatey_ installed can install *gallery-dl* from the Chocolatey Community Packages repository:

.. code:: powershell

$ choco install gallery-dl


*gallery-dl* is also available in the Scoop_ "main" bucket for Windows users:

.. code:: powershell

$ scoop install gallery-dl


To use *gallery-dl* simply call it with the URLs you wish to download images

.. code:: bash

$ gallery-dl [OPTION]... URL...

See also :code:`gallery-dl --help`.


Download images; in this case from danbooru via tag search for 'bonocho':

.. code:: bash

$ gallery-dl ""

Get the direct URL of an image from a site that requires authentication:

.. code:: bash

$ gallery-dl -g -u "<username>" -p "<password>" ""

Filter manga chapters by language and chapter number:

.. code:: bash

$ gallery-dl --chapter-filter "lang == 'fr' and 10 <= chapter < 20" ""

| Search a remote resource for URLs and download images from them:
| (URLs for which no extractor can be found will be silently ignored)

.. code:: bash

$ gallery-dl "r:"

If a site's address is nonstandard for its extractor, you can prefix the URL with the
extractor's name to force the use of a specific extractor:

.. code:: bash

$ gallery-dl "tumblr:https://sometumblrblog.example"


Configuration files for *gallery-dl* use a JSON-based file format.

| For a (more or less) complete example with options set to their default values,
see gallery-dl.conf_.
| For a configuration file example with more involved settings and options,
see gallery-dl-example.conf_.
| A list of all available configuration options and their
descriptions can be found in configuration.rst_.

*gallery-dl* searches for configuration files in the following places:

* ``%APPDATA%\gallery-dl\config.json``
* ``%USERPROFILE%\gallery-dl\config.json``
* ``%USERPROFILE%\gallery-dl.conf``

(``%USERPROFILE%`` usually refers to the user's home directory,
i.e. ``C:\Users\<username>\``)

Linux, macOS, etc.:
* ``/etc/gallery-dl.conf``
* ``${HOME}/.config/gallery-dl/config.json``
* ``${HOME}/.gallery-dl.conf``

Values in later configuration files will override previous ones.

Command line options will override all related settings in the configuration file(s),
e.g. using ``--write-metadata`` will enable writing metadata using the default values
for all ``postprocessors.metadata.*`` settings, overriding any specific settings in
configuration files.


Username & Password

Some extractors require you to provide valid login credentials in the form of
a username & password pair. This is necessary for
``nijie`` and ``seiga``
and optional for
and ``twitter``.

You can set the necessary information in your configuration file
(cf. gallery-dl.conf_)

.. code:: json

"extractor": {
"seiga": {
"username": "<username>",
"password": "<password>"

or you can provide them directly via the
:code:`-u/--username` and :code:`-p/--password` or via the
:code:`-o/--option` command-line options

.. code:: bash

$ gallery-dl -u <username> -p <password> URL
$ gallery-dl -o username=<username> -o password=<password> URL


For sites where login with username & password is not possible due to
CAPTCHA or similar, or has not been implemented yet, you can use the
cookies from a browser login session and input them into *gallery-dl*.

This can be done via the
`cookies <>`__
option in your configuration file by specifying

- | the path to a Mozilla/Netscape format cookies.txt file exported by a browser addon
| (e.g. `Get cookies.txt <>`__ for Chrome,
`Export Cookies <>`__ for Firefox)

- | a list of name-value pairs gathered from your browser's web developer tools
| (in `Chrome <>`__,
in `Firefox <>`__)

For example:

.. code:: json

"extractor": {
"instagram": {
"cookies": "$HOME/path/to/cookies.txt"
"patreon": {
"cookies": {
"session_id": "K1T57EKu19TR49C51CDjOJoXNQLF7VbdVOiBrC9ye0a"

You can also specify a cookies.txt file with
the :code:`--cookies` command-line option:

.. code:: bash

$ gallery-dl --cookies "$HOME/path/to/cookies.txt" URL


*gallery-dl* supports user authentication via OAuth_ for
``deviantart``, ``flickr``, ``reddit``, ``smugmug``, ``tumblr``,
and ``mastodon`` instances.
This is mostly optional, but grants *gallery-dl* the ability
to issue requests on your account's behalf and enables it to access resources
which would otherwise be unavailable to a public user.

To link your account to *gallery-dl*, start by invoking it with
``oauth:<sitename>`` as an argument. For example:

.. code:: bash

$ gallery-dl oauth:flickr

You will be sent to the site's authorization page and asked to grant read
access to *gallery-dl*. Authorize it and you will be shown one or more
"tokens", which should be added to your configuration file.

To authenticate with a ``mastodon`` instance, run *gallery-dl* with
``oauth:mastodon:<instance>`` as argument. For example:

.. code:: bash

$ gallery-dl
$ gallery-dl oauth:mastodon:

.. _gallery-dl.conf:
.. _gallery-dl-example.conf:
.. _configuration.rst:
.. _Supported Sites:

.. _Python:
.. _PyPI:
.. _pip:
.. _Requests:
.. _FFmpeg:
.. _youtube-dl:
.. _pyOpenSSL:
.. _Snapd:
.. _OAuth:
.. _Chocolatey:
.. _Scoop:

.. |pypi| image::

.. |build| image::

.. |gitter| image::