This file lists all available configuration options and their descriptions.

1. Extractor Options
2. Extractor-specific Options
3. Downloader Options
4. Output Options
5. Postprocessor Options
6. Miscellaneous Options
7. API Tokens & IDs

Each extractor is identified by its category and subcategory. The category is the lowercase site name without any spaces or special characters, which is usually just the module name (pixiv, danbooru, ...). The subcategory is a lowercase word describing the general functionality of that extractor (user, favorite, manga, ...).

Each one of the following options can be specified on multiple levels of the configuration tree:

A value in a "deeper" level hereby overrides a value of the same name on a lower level. Setting the extractor.pixiv.filename value, for example, lets you specify a general filename pattern for all the different pixiv extractors. Using the extractor.pixiv.user.filename value lets you override this general pattern specifically for PixivUserExtractor instances.

The category and subcategory of all extractors are included in the output of gallery-dl --list-extractors. For a specific URL these values can also be determined by using the -K/--list-keywords command-line option (see the example below).

Type

• string
• object (condition -> format string)

Example

"{manga}_c{chapter}_{page:>03}.{extension}"

{
    "extension == 'mp4'": "{id}_video.{extension}",
    "'nature' in title" : "{id}_{title}.{extension}",
    ""                  : "{id}_default.{extension}"
}

Description

A format string to build filenames for downloaded files with.

If this is an object, it must contain Python expressions mapping to the filename format strings to use. These expressions are evaluated in the order as specified in Python 3.6+ and in an undetermined order in Python 3.4 and 3.5.

The available replacement keys depend on the extractor used. A list of keys for a specific one can be acquired by calling gallery-dl with the -K/--list-keywords command-line option. For example:

$ gallery-dl -K http://seiga.nicovideo.jp/seiga/im5977527
Keywords for directory names:
-----------------------------
category
  seiga
subcategory
  image

Keywords for filenames:
-----------------------
category
  seiga
extension
  None
image-id
  5977527
subcategory
  image

Note: Even if the value of the extension key is missing or None, it will be filled in later when the file download is starting. This key is therefore always available to provide a valid filename extension.

Type

• list of strings
• object (condition -> format strings)

Example

["{category}", "{manga}", "c{chapter} - {title}"]

{
    "'nature' in content": ["Nature Pictures"],
    "retweet_id != 0"    : ["{category}", "{user[name]}", "Retweets"],
    ""                   : ["{category}", "{user[name]}"]
}

Description

A list of format strings to build target directory paths with.

If this is an object, it must contain Python expressions mapping to the list of format strings to use.

Each individual string in such a list represents a single path segment, which will be joined together and appended to the base-directory to form the complete target directory path.

Type

Path

Default

"./gallery-dl/"

Description

Directory path used as base for all download destinations.

Type

bool

Default

false

Description

Use an extractor's current target directory as base-directory for any spawned child extractors.

Type

• bool
• string

Default

false

Description

If true, overwrite any metadata provided by a child extractor with its parent's.

If this is a string, add a parent's metadata to its children's to a field named after said string.

For example with "parent-metadata": "_p_":

{
    "id": "child-id",
    "_p_": {"id": "parent-id"}
}

Type

bool

Default

false

Description

Share number of skipped downloads between parent and child extractors.

Type

• string
• object (character -> replacement character(s))

Default

"auto"

Example

• "/!? (){}"
• {" ": "_", "/": "-", "|": "-", ":": "_-_", "*": "_+_"}

Description

A string of characters to be replaced with the value of path-replace

or an object mapping invalid/unwanted characters to their replacements

for generated path segment names.

Special values:

• "auto": Use characters from "unix" or "windows" depending on the local operating system
• "unix": "/"
• "windows": "\\\\|/<>:\"?*"
• "ascii": "^0-9A-Za-z_." (only ASCII digits, letters, underscores, and dots)
• "ascii+": "^0-9@-[\\]-{ #-)+-.;=!}~" (all ASCII characters except the ones not allowed by Windows)

Implementation Detail: For strings with length >= 2, this option uses a Regular Expression Character Set, meaning that:

• using a caret ^ as first character inverts the set
• character ranges are supported (0-9a-z)
• ], -, and \ need to be escaped as \\], \\-, and \\\\ respectively to use them as literal characters

Type

string

Default

"_"

Description

The replacement character(s) for path-restrict

Type

string

Default

"\u0000-\u001f\u007f" (ASCII control characters)

Description

Set of characters to remove from generated path names.

Note: In a string with 2 or more characters, []^-\ need to be escaped with backslashes, e.g. "\\[\\]"

Type

string

Default

"auto"

Description

Set of characters to remove from the end of generated path segment names using str.rstrip()

Special values:

• "auto": Use characters from "unix" or "windows" depending on the local operating system
• "unix": ""
• "windows": ". "

Type

bool

Default

true

Description

On Windows, use extended-length paths prefixed with \\?\ to work around the 260 characters path length limit.

Type

object (extension -> replacement)

Default

{
    "jpeg": "jpg",
    "jpe" : "jpg",
    "jfif": "jpg",
    "jif" : "jpg",
    "jfi" : "jpg"
}

Description

A JSON object mapping filename extensions to their replacements.

Type

• bool
• string

Default

true

Description

Controls the behavior when downloading files that have been downloaded before, i.e. a file with the same filename already exists or its ID is in a download archive.

• true: Skip downloads
• false: Overwrite already existing files
• "abort": Stop the current extractor run
• "abort:N": Skip downloads and stop the current extractor run after N consecutive skips
• "terminate": Stop the current extractor run, including parent extractors
• "terminate:N": Skip downloads and stop the current extractor run, including parent extractors, after N consecutive skips
• "exit": Exit the program altogether
• "exit:N": Skip downloads and exit the program after N consecutive skips
• "enumerate": Add an enumeration index to the beginning of the filename extension (file.1.ext, file.2.ext, etc.)

Type

string

Description

Python expression controlling which skipped files to count towards "abort" / "terminate" / "exit".

Type

Duration

Default

0

Description

Number of seconds to sleep before each download.

Type

Duration

Default

0

Description

Number of seconds to sleep before handling an input URL, i.e. before starting a new extractor.

Type

Duration

Default

60

Description

Number of seconds to sleep when receiving a 429 Too Many Requests response before retrying the request.

Type

Duration

Default

• "0.5-1.5"

  ao3, civitai, [Danbooru], [E621], [foolfuuka]:search, itaku, koharu, newgrounds, [philomena], pixiv:novel, plurk, poipiku , pornpics, scrolller, soundgasm, urlgalleries, vk, zerochan

• "1.0-2.0"

  flickr, weibo, [wikimedia]

• "2.0-4.0"

  behance, imagefap, [Nijie]

• "3.0-6.0"

  bilibili, exhentai, idolcomplex, [reactor], readcomiconline

• "6.0-6.1"

  twibooru

• "6.0-12.0"

  instagram

• 0

  otherwise

Description

Minimal time interval in seconds between each HTTP request during data extraction.

Type

string

Default

null

Description

The username and password to use when attempting to log in to another site.

This is supported for

• aibooru (*)
• ao3
• aryion
• atfbooru (*)
• bluesky
• booruvar (*)
• coomerparty
• danbooru (*)
• deviantart
• e621 (*)
• e6ai (*)
• e926 (*)
• exhentai
• horne (R)
• idolcomplex
• imgbb
• inkbunny
• kemonoparty
• koharu
• mangadex
• mangoxo
• newgrounds
• nijie (R)
• pillowfort
• sankaku
• scrolller
• seiga
• subscribestar
• tapas
• tsumino
• twitter
• vipergirls
• zerochan

These values can also be specified via the -u/--username and -p/--password command-line options or by using a .netrc file. (see Authentication)

(*) The password value for these sites should be the API key found in your user profile, not the actual account password.

(R) Login with username & password or supplying logged-in cookies is required

Note: Leave the password value empty or undefined to be prompted for a passeword when performing a login (see getpass()).

Type

bool

Default

true if stdin is attached to a terminal, false otherwise

Description

Allow prompting the user for interactive input.

Type

bool

Default

false

Description

Enable the use of .netrc authentication data.

Type

• Path
• object (name -> value)
• list

Description

Source to read additional cookies from. This can be

• The Path to a Mozilla/Netscape format cookies.txt file

  "~/.local/share/cookies-instagram-com.txt"

• An object specifying cookies as name-value pairs

  {
      "cookie-name": "cookie-value",
      "sessionid"  : "14313336321%3AsabDFvuASDnlpb%3A31",
      "isAdult"    : "1"
  }

• A list with up to 5 entries specifying a browser profile.

  • The first entry is the browser name
  • The optional second entry is a profile name or an absolute path to a profile directory
  • The optional third entry is the keyring to retrieve passwords for decrypting cookies from
  • The optional fourth entry is a (Firefox) container name ("none" for only cookies with no container (default))
  • The optional fifth entry is the domain to extract cookies for. Prefix it with a dot . to include cookies for subdomains.

  ["firefox"]
  ["firefox", null, null, "Personal"]
  ["chromium", "Private", "kwallet", null, ".twitter.com"]

Type

string

Default

"random"

Description

Interpret extractor.cookies as a list of cookie sources and select one of them for each extractor run.

• "random": Select cookies randomly
• "rotate": Select cookies in sequence. Start over from the beginning after reaching the end of the list.

[
    "~/.local/share/cookies-instagram-com-1.txt",
    "~/.local/share/cookies-instagram-com-2.txt",
    "~/.local/share/cookies-instagram-com-3.txt",
    ["firefox", null, null, "c1", ".instagram-com"],
]

Type

• bool
• Path

Default

true

Description

Export session cookies in cookies.txt format.

• If this is a Path, write cookies to the given file path.
• If this is true and extractor.*.cookies specifies the Path of a valid cookies.txt file, update its contents.

Type

• string
• object (scheme -> proxy)

Example

"http://10.10.1.10:3128"

{
    "http" : "http://10.10.1.10:3128",
    "https": "http://10.10.1.10:1080",
    "http://10.20.1.128": "http://10.10.1.10:5323"
}

Description

Proxy (or proxies) to be used for remote connections.

• If this is a string, it is the proxy URL for all outgoing requests.
• If this is an object, it is a scheme-to-proxy mapping to specify different proxy URLs for each scheme. It is also possible to set a proxy for a specific host by using scheme://host as key. See Requests' proxy documentation for more details.

Note: If a proxy URL does not include a scheme, http:// is assumed.

Type

bool

Default

true

Description

Collect proxy configuration information from environment variables (HTTP_PROXY, HTTPS_PROXY, NO_PROXY) and Windows Registry settings.

Type

• string
• list with 1 string and 1 integer as elements

Example

• "192.168.178.20"
• ["192.168.178.20", 8080]

Description

Client-side IP address to bind to.

Can be either a simple string with just the local IP address

or a list with IP and explicit port number as elements.

Type

string

Default

"Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:128.0) Gecko/20100101 Firefox/128.0"

Description

User-Agent header value to be used for HTTP requests.

Setting this value to "browser" will try to automatically detect and use the User-Agent used by the system's default browser.

Note: This option has no effect on pixiv, e621, mangadex, and patreon extractors, as these need specific values to function correctly.

Type

string

Default

• "firefox": artstation, mangasee, twitter
• null: otherwise

Example

• "chrome:macos"

Description

Try to emulate a real browser (firefox or chrome) by using their default HTTP headers and TLS ciphers for HTTP requests.

Optionally, the operating system used in the User-Agent header can be specified after a : (windows, linux, or macos).

Note: requests and urllib3 only support HTTP/1.1, while a real browser would use HTTP/2.

Type

• bool
• string

Default

true

Description

Send Referer headers with all outgoing HTTP requests.

If this is a string, send it as Referer instead of the extractor's root domain.

Type

object (name -> value)

Default

{
    "User-Agent"     : "<extractor.*.user-agent>",
    "Accept"         : "*/*",
    "Accept-Language": "en-US,en;q=0.5",
    "Accept-Encoding": "gzip, deflate",
    "Referer"        : "<extractor.*.referer>"
}

Description

Additional HTTP headers to be sent with each HTTP request,

To disable sending a header, set its value to null.

Type

list of strings

Example

["ECDHE-ECDSA-AES128-GCM-SHA256",
 "ECDHE-RSA-AES128-GCM-SHA256",
 "ECDHE-ECDSA-CHACHA20-POLY1305",
 "ECDHE-RSA-CHACHA20-POLY1305"]

Description

List of TLS/SSL cipher suites in OpenSSL cipher list format to be passed to ssl.SSLContext.set_ciphers()

Type

bool

Default

• false: artstation
• true: otherwise

Description

Allow selecting TLS 1.2 cipher suites.

Can be disabled to alter TLS fingerprints and potentially bypass Cloudflare blocks.

Type

object (name -> value)

Example

{"type": "Pixel Art", "type_id": 123}

Description

Additional name-value pairs to be added to each metadata dictionary.

Type

bool

Default

false

Description

Evaluate each keywords string value as a format string.

Type

any

Default

"None"

Description

Default value used for missing or undefined keyword names in format strings.

Type

string

Description

Insert a file's download URL into its metadata dictionary as the given name.

For example, setting this option to "gdl_file_url" will cause a new metadata field with name gdl_file_url to appear, which contains the current file's download URL. This can then be used in filenames, with a metadata post processor, etc.

Type

string

Description

Insert a reference to the current PathFormat data structure into metadata dictionaries as the given name.

For example, setting this option to "gdl_path" would make it possible to access the current file's filename as "{gdl_path.filename}".

Type

string

Description

Insert a reference to the current Extractor object into metadata dictionaries as the given name.

Type

string

Description

Insert an object containing a file's HTTP headers and filename, extension, and date parsed from them into metadata dictionaries as the given name.

For example, setting this option to "gdl_http" would make it possible to access the current file's Last-Modified header as "{gdl_http[Last-Modified]}" and its parsed form as "{gdl_http[date]}".

Type

string

Description

Insert an object containing gallery-dl's version info into metadata dictionaries as the given name.

The content of the object is as follows:

{
    "version"         : "string",
    "is_executable"   : "bool",
    "current_git_head": "string or null"
}

Type

bool

Default

Extractor-specific

Description

Transfer an extractor's (sub)category values to all child extractors spawned by it, to let them inherit their parent's config options.

Type

list of strings

Default

["oauth", "recursive", "test"] + current extractor category

Example

["imgur", "redgifs:user", "*:image"]

Description

A list of extractor identifiers to ignore (or allow) when spawning child extractors for unknown URLs, e.g. from reddit or plurk.

Each identifier can be

• A category or basecategory name ("imgur", "mastodon")

• A (base)category-subcategory pair, where both names are separated by a colon ("redgifs:user").

  Both names can be a * or left empty, matching all possible names ("*:image", ":user").

Note: Any blacklist setting will automatically include "oauth", "recursive", and "test".

Type

Path

Default

null

Example

"$HOME/.archives/{category}.sqlite3"

Description

File to store IDs of downloaded files in. Downloads of files already recorded in this archive file will be skipped.

The resulting archive file is not a plain text file but an SQLite3 database, as either lookup operations are significantly faster or memory requirements are significantly lower when the amount of stored IDs gets reasonably large.

Note: Archive files that do not already exist get generated automatically.

Note: Archive paths support regular format string replacements, but be aware that using external inputs for building local paths may pose a security risk.

Type

• string
• list of strings

Default

"file"

Example

• "file,skip"
• ["file", "skip"]

Description

Event(s) for which IDs get written to an archive.

Available events are: file, skip

Type

string

Example

"{id}_{offset}"

Description

An alternative format string to build archive IDs with.

Type

string

Default

"file"

Description

Controls when to write archive IDs to the archive database.

• "file": Write IDs immediately after completing or skipping a file download.
• "memory": Keep IDs in memory and only write them after successful job completion.

Type

string

Default

"{category}"

Description

Prefix for archive IDs.

Type

list of strings

Example

["journal_mode=WAL", "synchronous=NORMAL"]

Description

A list of SQLite PRAGMA statements to run during archive initialization.

See https://www.sqlite.org/pragma.html#toc for available PRAGMA statements and further details.

Type

• object (pattern -> action(s))
• list of lists with pattern -> action(s) pairs as elements

Example

{
    "info:Logging in as .+"   : "level = debug",
    "warning:(?i)unable to .+": "exit 127",
    "error"                   : [
        "status |= 1",
        "exec notify.sh 'gdl error'",
        "abort"
    ]
}

[
    ["info:Logging in as .+"   , "level = debug"],
    ["warning:(?i)unable to .+", "exit 127"     ],
    ["error"                   , [
        "status |= 1",
        "exec notify.sh 'gdl error'",
        "abort"
    ]]
]

Description

Perform an action when logging a message matched by pattern.

pattern is parsed as severity level (debug, info, warning, error, or integer value) followed by an optional Python Regular Expression separated by a colon :. Using * as level or leaving it empty matches logging messages of all levels (e.g. *:<re> or :<re>).

action is parsed as action type followed by (optional) arguments.

It is possible to specify more than one action per pattern by providing them as a list: ["<action1>", "<action2>", …]

Supported Action Types:

status:

Modify job exit status.

Expected syntax is <operator> <value> (e.g. = 100).

Supported operators are = (assignment), & (bitwise AND), | (bitwise OR), ^ (bitwise XOR).

level:

Modify severity level of the current logging message.

Can be one of debug, info, warning, error or an integer value.

print:

Write argument to stdout.

exec:

Run a shell command.

abort:

Stop the current extractor run.

terminate:

Stop the current extractor run, including parent extractors.

restart:

Restart the current extractor run.

wait:

Sleep for a given Duration or

wait until Enter is pressed when no argument was given.

exit:

Exit the program with the given argument as exit status.

Type

• Postprocessor Configuration object
• list of Postprocessor Configuration objects

Example

[
    {
        "name": "zip" ,
        "compression": "store"
    },
    {
        "name": "exec",
        "command": ["/home/foobar/script", "{category}", "{image_id}"]
    }
]

Description

A list of post processors to be applied to each downloaded file in the specified order.

Unlike other options, a postprocessors setting at a deeper level does not override any postprocessors setting at a lower level.

Instead, all post processors from all applicable postprocessors settings get combined into a single list.

For example

• an mtime post processor at extractor.postprocessors,
• a zip post processor at extractor.pixiv.postprocessors,
• and using --exec

will run all three post processors - mtime, zip, exec - for each downloaded pixiv file.

Type

object (name -> value)

Example

{
    "archive": null,
    "keep-files": true
}

Description

Additional Postprocessor Options that get added to each individual post processor object before initializing it and evaluating filters.

Type

integer

Default

4

Description

Maximum number of times a failed HTTP request is retried before giving up, or -1 for infinite retries.

Type

list of integers

Example

[404, 429, 430]

Description

Additional HTTP response status codes to retry an HTTP request on.

2xx codes (success responses) and 3xx codes (redirection messages) will never be retried and always count as success, regardless of this option.

5xx codes (server error responses) will always be retried, regardless of this option.

Type

float

Default

30.0

Description

Amount of time (in seconds) to wait for a successful connection and response from a remote server.

This value gets internally used as the timeout parameter for the requests.request() method.

Type

• bool
• string

Default

true

Description

Controls whether to verify SSL/TLS certificates for HTTPS requests.

If this is a string, it must be the path to a CA bundle to use instead of the default certificates.

This value gets internally used as the verify parameter for the requests.request() method.

Type

bool

Default

true

Description

Controls whether to download media files.

Setting this to false won't download any files, but all other functions (postprocessors, download archive, etc.) will be executed as normal.

Type

bool

Default

true

Description

Use fallback download URLs when a download fails.

Type

• string
• list of strings

Examples

• "10-20"
• "-5, 10, 30-50, 100-"
• "10:21, 30:51:2, :5, 100:"
• ["-5", "10", "30-50", "100-"]

Description

Index range(s) selecting which files to download.

These can be specified as

• index: 3 (file number 3)
• range: 2-4 (files 2, 3, and 4)
• slice: 3:8:2 (files 3, 5, and 7)

Arguments for range and slice notation are optional and will default to begin (1) or end (sys.maxsize) if omitted.

For example 5-, 5:, and 5:: all mean "Start at file number 5".

Note: The index of the first file is 1.

Type

string

Description

Like image-range, but applies to delegated URLs like manga chapters, etc.

Type

• string
• list of strings

Examples

• "re.search(r'foo(bar)+', description)"
• ["width >= 1200", "width/height > 1.2"]

Description

Python expression controlling which files to download.

A file only gets downloaded when all of the given expressions evaluate to True.

Available values are the filename-specific ones listed by -K or -j.

Type

• string
• list of strings

Examples

• "lang == 'en'"
• ["language == 'French'", "10 <= chapter < 20"]

Description

Like image-filter, but applies to delegated URLs like manga chapters, etc.

Type

bool

Default

false

Description

Ignore image URLs that have been encountered before during the current extractor run.

Type

bool

Default

false

Description

Like image-unique, but applies to delegated URLs like manga chapters, etc.

Type

string

Default

"%Y-%m-%dT%H:%M:%S"

Description

Format string used to parse string values of date-min and date-max.

See strftime() and strptime() Behavior for a list of formatting directives.

Note: Despite its name, this option does not control how {date} metadata fields are formatted. To use a different formatting for those values other than the default %Y-%m-%d %H:%M:%S, put strftime() and strptime() Behavior formatting directives after a colon :, for example {date:%Y%m%d}.

Type

• bool
• string

Default

false

Description

During data extraction, write received HTTP request data to enumerated files in the current working directory.

Special values:

• "all": Include HTTP request and response headers. Hide Authorization, Cookie, and Set-Cookie values.
• "ALL": Include all HTTP request and response headers.

Type

• string
• list of strings

Default

"pdf"

Example

• "azw3,epub,mobi,pdf,html"
• ["azw3", "epub", "mobi", "pdf", "html"]

Description

Format(s) to download.

Type

bool

Default

false

Description

Try to follow external URLs of embedded players.

Type

integer

Default

null

Description

Limit the number of posts/projects to download.

Type

bool

Default

false

Description

Download video previews.

Type

bool

Default

true

Description

Download video clips.

Type

bool

Default

true

Description

Enable the "Show Studio and Pro member artwork first" checkbox when retrieving search results.

Type

bool

Default

true

Description

Controls the post extraction strategy.

• true: Start on users' main gallery pages and recursively descend into subfolders
• false: Get posts from "Latest Updates" pages

Type

integer

Default

1920

Description

Specifies the requested image width.

This value must be divisble by 16 and gets rounded down otherwise. The maximum possible value appears to be 1920.

Type

list of strings

Default

["image", "video", "mediacollection", "embed"]

Description

Selects which gallery modules to download from.

Supported module types are image, video, mediacollection, embed, text.

Type

string

Description

Custom Blogger API key.

https://developers.google.com/blogger/docs/3.0/using#APIKey

Type

bool

Default

true

Description

Download embedded videos hosted on https://www.blogger.com/

Type

• string
• list of strings

Default

"media"

Example

• "avatar,background,posts"
• ["avatar", "background", "posts"]

Description

A (comma-separated) list of subcategories to include when processing a user profile.

Possible values are "avatar", "background", "posts", "replies", "media", "likes",

It is possible to use "all" instead of listing all values separately.

Type

• bool
• string
• list of strings

Default

false

Example

• "facets,user"
• ["facets", "user"]

Description

Extract additional metadata.

• facets: hashtags, mentions, and uris
• user: detailed user metadata for the user referenced in the input URL (See app.bsky.actor.getProfile).

Type

integer

Default

0

Description

Sets the maximum depth of returned reply posts.

(See depth parameter of app.bsky.feed.getPostThread)

Type

bool

Default

false

Description

Fetch media from quoted posts.

Type

bool

Default

false

Description

Process reposts.

Type

bool

Default

true

Description

Download videos.

Type

bool

Default

true

Description

Request only available posts.

Type

bool

Default

false

Description

Request only purchased posts for feed results.

Type

bool

Default

false

Description

Provide detailed user metadata.

Type

• bool
• list of strings

Default

true

Example

["full_hd", "high", "medium"]

Description

Download videos.

If this is a list, it selects which format to try to download.

Possibly available formats are

• ultra_hd (2160p)
• quad_hd (1440p)
• full_hd (1080p)
• high (720p)
• medium (480p)
• low (360p)
• lowest (240p)
• tiny (144p)

Type

bool

Default

false

Description

Controls which bunkr TLDs to accept.

• true: Match URLs with all possible TLDs (e.g. bunkr.xyz or bunkrrr.duck)
• false: Match only URLs with known TLDs

Type

list of strings

Default

["image", "video", "download", "gallery"]

Description

Determines the type and order of files to download.

Available types are image, video, download, gallery.

Type

string

Default

"trpc"

Description

Selects which API endpoints to use.

• "rest": Public REST API
• "trpc": Internal tRPC API

Type

string

Description

The API Key value generated in your User Account Settings to make authorized API requests.

See API/Authorization for details.

Type

list of strings

Default

["image"]

Description

Determines the type and order of files to download when processing models.

Available types are model, image, gallery.

Type

• string
• list of strings

Default

["user-models", "user-posts"]

Description

A (comma-separated) list of subcategories to include when processing a user profile.

Possible values are "user-models", "user-posts", "user-images".

It is possible to use "all" instead of listing all values separately.

Type

• bool
• string
• list of strings

Default

false

Example

• "generation"
• ["generation"]

Description

Extract additional generation metadata.

Note: This requires 1 additional HTTP request per image.

Type

• bool
• string ("api": "rest")
• integer ("api": "trpc")

Default

true

Description

Download images rated NSFW.

• For "api": "rest", this can be one of "None", "Soft", "Mature", "X" to set the highest returned mature content flag.

• For "api": "trpc", this can be an integer whose bits select the returned mature content flags.

  For example, 12 (4|8) would return only Mature and X rated images, while 3 (1|2) would return only None and Soft rated images,

Type

• string
• list of strings

Default

"original=true"

Example

• "width=1280,quality=90"
• ["width=1280", "quality=90"]

Description

A (comma-separated) list of image quality options to pass with every image URL.

Known available options include original, quality, width

Note: Set this option to an arbitrary letter, e.g., "w", to download images in JPEG format at their original resolution.

Type

bool

Default

true

Description

Extract ask posts.

Type

bool

Default

false

Description

Extract pinned posts.

Type

bool

Default

true

Description

Extract reply posts.

Type

bool

Default

false

Description

Extract shared posts.

Type

string

Default

null

Example

"cyberdrop.to"

Description

Specifies the domain used by cyberdrop regardless of input URL.

Setting this option to "auto" uses the same domain as a given input URL.

Type

bool

Default

false

Description

For unavailable or restricted posts, follow the source and download from there if possible.

Type

bool

Default

false

Description

Controls the download target for Ugoira posts.

• true: Original ZIP archives
• false: Converted video files

Type

• bool
• string
• list of strings

Default

false

Example

• "replacements,comments,ai_tags"
• ["replacements", "comments", "ai_tags"]

Description

Extract additional metadata (notes, artist commentary, parent, children, uploader)

It is possible to specify a custom list of metadata includes. See available_includes for possible field names. aibooru also supports ai_metadata.

Note: This requires 1 additional HTTP request per 200-post batch.

Type

• string
• integer

Default

"auto"

Description

Stop paginating over API results if the length of a batch of returned posts is less than the specified number. Defaults to the per-page limit of the current instance, which is 200.

Note: Changing this setting is normally not necessary. When the value is greater than the per-page limit, gallery-dl will stop after the first batch. The value cannot be less than 1.

Type

string

Default

null

Description

Your Derpibooru API Key, to use your account's browsing settings and filters.

Type

integer

Default

56027 (Everything filter)

Description

The content filter ID to use.

Setting an explicit filter ID overrides any default filters and can be used to access 18+ content without API Key.

See Filters for details.

Type

bool

Default

true

Description

Download SVG versions of images when available.

Try to download the view_url version of these posts when this option is disabled.

Type

bool

Default

false

Description

Automatically watch users when encountering "Watchers-Only Deviations" (requires a refresh-token).

Type

bool

Default

false

Description

After watching a user through auto-watch, unwatch that user at the end of the current extractor run.

Type

bool

Default

false

Description

Extract comments metadata.

Type

bool

Default

false

Description

Download the avatar of each commenting user.

Note: Enabling this option also enables deviantart.comments.

Type

bool

Default

false

Description

Download extra Sta.sh resources from description texts and journals.

Note: Enabling this option also enables deviantart.metadata.

Type

bool

Default

true

Description

Select the directory structure created by the Gallery- and Favorite-Extractors.

• true: Use a flat directory structure.

• false: Collect a list of all gallery-folders or favorites-collections and transfer any further work to other extractors (folder or collection), which will then create individual subdirectories for each of them.

  Note: Going through all gallery folders will not be able to fetch deviations which aren't in any folder.

Type

bool

Default

false

Description

Provide a folders metadata field that contains the names of all folders a deviation is present in.

Note: Gathering this information requires a lot of API calls. Use with caution.

Type

• bool
• string

Default

true

Description

Check whether the profile name in a given URL belongs to a group or a regular user.

When disabled, assume every given profile name belongs to a regular user.

Special values:

• "skip": Skip groups

Type

• string
• list of strings

Default

"gallery"

Example

• "favorite,journal,scraps"
• ["favorite", "journal", "scraps"]

Description

A (comma-separated) list of subcategories to include when processing a user profile.

Possible values are "avatar", "background", "gallery", "scraps", "journal", "favorite", "status".

It is possible to use "all" instead of listing all values separately.

Type

bool

Default

true

Description

For older non-downloadable images, download a higher-quality /intermediary/ version.

Type

string

Default

"html"

Description

Selects the output format for textual content. This includes journals, literature and status updates.

• "html": HTML with (roughly) the same layout as on DeviantArt.
• "text": Plain text with image references and HTML tags removed.
• "none": Don't download textual content.

Type

bool

Default

false

Description

Update JSON Web Tokens (the token URL parameter) of otherwise non-downloadable, low-resolution images to be able to download them in full resolution.

Note: No longer functional as of 2023-10-11

Type

bool

Default

true

Description

Enable mature content.

This option simply sets the mature_content parameter for API calls to either "true" or "false" and does not do any other form of content filtering.

Type

• bool
• string
• list of strings

Default

false

Example

• "stats,submission"
• ["camera", "stats", "submission"]

Description

Extract additional metadata for deviation objects.

Provides description, tags, license, and is_watching fields when enabled.

It is possible to request extended metadata by specifying a list of

• camera : EXIF information (if available)
• stats : deviation statistics
• submission : submission information
• collection : favourited folder information (requires a refresh token)
• gallery : gallery folder information (requires a refresh token)

Set this option to "all" to request all extended metadata categories.

See /deviation/metadata for official documentation.

Type

• bool
• string

Default

true

Description

Download original files if available.

Setting this option to "images" only downloads original files if they are images and falls back to preview versions for everything else (archives, videos, etc.).

Type

string

Default

"api"

Description

Controls when to stop paginating over API results.

• "api": Trust the API and stop when has_more is false.
• "manual": Disregard has_more and only stop when a batch of results is empty.

Type

bool

Default

false

Description

For non-image files (archives, videos, etc.), also download the file's preview image.

Set this option to "all" to download previews for all files.

Type

bool

Default

true

Description

Use a public access token for API requests.

Disable this option to force using a private token for all requests when a refresh token is provided.

Type

• integer
• string

Default

100

Description

JPEG quality level of images for which an original file download is not available.

Set this to "png" to download a PNG version of these images instead.

Type

string

Default

null

Description

The refresh-token value you get from linking your DeviantArt account to gallery-dl.

Using a refresh-token allows you to access private or otherwise not publicly available deviations.

Note: The refresh-token becomes invalid after 3 months or whenever your cache file is deleted or cleared.

Type

integer

Default

0

Description

Minimum wait time in seconds before API requests.

Type

list of strings

Example

["original.jpg", "big.jpg", "big.gif", ".png"]

Description

Avatar URL formats to return.

Each format is parsed as SIZE.EXT.

Leave SIZE empty to download the regular, small avatar format.

Type

• bool
• string
• list of strings

Default

false

Example

• "notes,pools"
• ["notes", "pools"]

Description

Extract additional metadata (notes, pool metadata) if available.

Note: This requires 0-2 additional HTTP requests per post.

Type

• string
• integer

Default

"auto"

Description

Stop paginating over API results if the length of a batch of returned posts is less than the specified number. Defaults to the per-page limit of the current instance, which is 320.

Note: Changing this setting is normally not necessary. When the value is greater than the per-page limit, gallery-dl will stop after the first batch. The value cannot be less than 1.

Type

string

Default

"auto"

Description

• "auto": Use e-hentai.org or exhentai.org depending on the input URL
• "e-hentai.org": Use e-hentai.org for all URLs
• "exhentai.org": Use exhentai.org for all URLs

Type

integer

Default

2

Description

Number of times a failed image gets retried or -1 for infinite retries.

Type

string

Example

"4"

Description

After downloading a gallery, add it to your account's favorites as the given category number.

Note: Set this to "favdel" to remove galleries from your favorites.

Note: This will remove any Favorite Notes when applied to already favorited galleries.

Type

string

Default

"resized"

Description

Selects how to handle "you do not have enough GP" errors.

• "resized": Continue downloading non-original images.
• "stop": Stop the current extractor run.
• "wait": Wait for user input before retrying the current image.

Type

integer

Default

null

Description

Sets a custom image download limit and stops extraction when it gets exceeded.

Type

bool

Default

false

Description

Load extended gallery metadata from the API.

Adds archiver_key, posted, and torrents. Makes date and filesize more precise.

Type

bool

Default

true

Description

Download full-sized original images if available.

Type

string

Default

"gallery"

Description

Selects an alternative source to download files from.

• "hitomi": Download the corresponding gallery from hitomi.la

Type

bool

Default

false

Description

Group tags by type and provide them as tags_<type> metadata fields, for example tags_artist or tags_character.

Type

bool

Default

false

description

Extract comments that include photo attachments made by the author of the post.

Type

• bool
• string

Default

true

Description

Control video download behavior.

• true: Extract and download video & audio separately.
• "ytdl": Let yt-dlp/youtube-dl handle video extraction and download, and merge video & audio streams.
• false: Ignore videos.

Type

bool

Default

false

Description

Extract comments metadata.

Note: This requires 1 or more additional API requests per post, depending on the number of comments.

Type

• bool
• string

Default

true

Description

Control behavior on embedded content from external sites.

• true: Extract embed URLs and download them if supported (videos are not downloaded).
• "ytdl": Like true, but let yt-dlp/youtube-dl handle video extraction and download for YouTube, Vimeo, and SoundCloud embeds.
• false: Ignore embeds.

Type

• bool
• string
• list of strings

Default

false

Example

• user,plan,comments
• ["user", "plan", "comments"]

Description

Extract plan and extended user metadata.

Supported fields when selecting which data to extract are

• comments
• plan
• user

Note: comments can also be enabled via fanbox.comments

Type

string

Default

null

Description

The access_token and access_token_secret values you get from linking your Flickr account to gallery-dl.

Type

bool

Default

false

Description

For each photo, return the albums and pools it belongs to as set and pool metadata.

Note: This requires 1 additional API call per photo. See flickr.photos.getAllContexts for details.

Type

bool

Default

false

Description

For each photo, return its EXIF/TIFF/GPS tags as exif and camera metadata.

Note: This requires 1 additional API call per photo. See flickr.photos.getExif for details.

Type

• bool
• string
• list of strings

Default

false

Example

• license,last_update,machine_tags
• ["license", "last_update", "machine_tags"]

Description

Extract additional metadata (license, date_taken, original_format, last_update, geo, machine_tags, o_dims)

It is possible to specify a custom list of metadata includes. See the extras parameter in Flickr's API docs for possible field names.

Type

bool

Default

true

Description

Extract and download videos.

Type

• integer
• string

Default

null

Description

Sets the maximum allowed size for downloaded images.

• If this is an integer, it specifies the maximum image dimension (width and height) in pixels.
• If this is a string, it should be one of Flickr's format specifiers ("Original", "Large", ... or "o", "k", "h", "l", ...) to use as an upper limit.

Type

string

Default

"text"

Description

Controls the format of description metadata fields.

• "text": Plain text with HTML tags removed
• "html": Raw HTML content

Type

bool

Default

false

Description

Follow external URLs linked in descriptions.

Type

• string
• list of strings

Default

"gallery"

Example

• "scraps,favorite"
• ["scraps", "favorite"]

Description

A (comma-separated) list of subcategories to include when processing a user profile.

Possible values are "gallery", "scraps", "favorite".

It is possible to use "all" instead of listing all values separately.

Type

string

Default

"auto"

Description

Selects which site layout to expect when parsing posts.

• "auto": Automatically differentiate between "old" and "new"
• "old": Expect the old site layout
• "new": Expect the new site layout

Type

string

Default

null

Description

Values from the API Access Credentials section found at the bottom of your Account Options page.

Type

string

Default

"desc"

Description

Controls the order in which favorited posts are returned.

• "asc": Ascending favorite date order (oldest first)
• "desc": Descending favorite date order (newest first)
• "reverse": Same as "asc"

Type

bool

Default

false

Description

Match all URLs not otherwise supported by gallery-dl, even ones without a generic: prefix.

Type

string

Default

null

Description

API token value found at the bottom of your profile page.

If not set, a temporary guest token will be used.

Type

string

Description

API token value used during API requests.

An invalid or not up-to-date value will result in 401 Unauthorized errors.

Keeping this option unset will use an extra HTTP request to attempt to fetch the current value used by gofile.

Type

bool

Default

false

Description

Recursively download files from subfolders.

Type

• string
• list of strings

Default

"pictures"

Example

• "scraps,stories"
• ["scraps", "stories"]

Description

A (comma-separated) list of subcategories to include when processing a user profile.

Possible values are "pictures", "scraps", "stories", "favorite".

It is possible to use "all" instead of listing all values separately.

Type

string

Default

"webp"

Description

Selects which image format to download.

Available formats are "webp" and "avif".

"original" will try to download the original jpg or png versions, but is most likely going to fail with 403 Forbidden errors.

Type

string

Description

Your personal Image Chest access token.

These tokens allow using the API instead of having to scrape HTML pages, providing more detailed metadata. (date, description, etc)

See https://imgchest.com/docs/api/1.0/general/authorization for instructions on how to generate such a token.

Type

string

Description

Custom Client ID value for API requests.

Type

• bool
• string

Default

true

Description

Controls whether to choose the GIF or MP4 version of an animation.

• true: Follow Imgur's advice and choose MP4 if the prefer_video flag in an image's metadata is set.
• false: Always choose GIF.
• "always": Always choose MP4.

Type

string

Default

"create_datetime"

Description

Value of the orderby parameter for submission searches.

(See API#Search for details)

Type

string

Default

"rest"

Description

Selects which API endpoints to use.

• "rest": REST API - higher-resolution media
• "graphql": GraphQL API - lower-resolution media

Type

• bool
• string

Default

true

Example

"3414259811154179155_25025320"

Description

Controls from which position to start the extraction process from.

• true: Start from the beginning. Log the most recent cursor value when interrupted before reaching the end.
• false: Start from the beginning.
• any string: Start from the position defined by this value.

Type

• string
• list of strings

Default

"posts"

Example

• "stories,highlights,posts"
• ["stories", "highlights", "posts"]

Description

A (comma-separated) list of subcategories to include when processing a user profile.

Possible values are "posts", "reels", "tagged", "stories", "highlights", "info", "avatar".

It is possible to use "all" instead of listing all values separately.

Type

integer

Default

null

Description

Limit the number of posts to download.

Type

bool

Default

false

Description

Provide extended user metadata even when referring to a user by ID, e.g. instagram.com/id:12345678.

Note: This metadata is always available when referring to a user by name, e.g. instagram.com/USERNAME.

Type

string

Default

"asc"

Description

Controls the order in which files of each post are returned.

• "asc": Same order as displayed in a post
• "desc": Reverse order as displayed in a post
• "reverse": Same as "desc"

Note: This option does not affect {num}. To enumerate files in reverse order, use count - num + 1.

Type

string

Default

"asc"

Description

Controls the order in which posts are returned.

• "asc": Same order as displayed
• "desc": Reverse order as displayed
• "id" or "id_asc": Ascending order by ID
• "id_desc": Descending order by ID
• "reverse": Same as "desc"

Note: This option only affects highlights.

Type

bool

Default

false

Description

Download video previews.

Type

bool

Default

true

Description

Download video files.

Type

bool

Default

true

Description

Download video files.

Type

bool

Default

false

Description

Extract comments metadata.

Note: This requires 1 additional HTTP request per post.

Type

bool

Default

false

Description

Controls how to handle duplicate files in a post.

• true: Download duplicates
• false: Ignore duplicates

Type

bool

Default

false

Description

Extract a user's direct messages as dms metadata.

Type

bool

Default

false

Description

Extract a user's announcements as announcements metadata.

Type

string

Default

artist

Description

Determines the type of favorites to be downloaded.

Available types are artist, and post.

Type

list of strings

Default

["attachments", "file", "inline"]

Description

Determines the type and order of files to be downloaded.

Available types are file, attachments, and inline.

Type

integer

Default

null

Description

Limit the number of posts to download.

Type

bool

Default

false

Description

Extract username metadata.

Type

• bool
• string

Default

false

Description

Extract post revisions.

Set this to "unique" to filter out duplicate revisions.

Note: This requires 1 additional HTTP request per post.

Type

string

Default

"desc"

Description

Controls the order in which revisions are returned.

• "asc": Ascending order (oldest first)
• "desc": Descending order (newest first)
• "reverse": Same as "asc"

Type

string

Default

"mp3"

Description

The name of the preferred file format to download.

Use "all" to download all available formats, or a (comma-separated) list to select multiple formats.

If the selected format is not available, the first in the list gets chosen (usually mp3).

Type

bool

Default

true

Description

Download each gallery as a single .cbz file.

Disabling this option causes a gallery to be downloaded as individual image files.

Type

• string
• list of strings

Default

["0", "1600", "1280", "980", "780"]

Description

Name(s) of the image format to download.

When more than one format is given, the first available one is selected.

Possible formats are

"780", "980", "1280", "1600", "0" (original)

Type

bool

Default

false

Description

Group tags by type and provide them as tags_<type> metadata fields, for example tags_artist or tags_character.

Type

string

Default

null

Description

Specifies the domain used by a lolisafe extractor regardless of input URL.

Setting this option to "auto" uses the same domain as a given input URL.

Type

bool

Default

false

Description

Format in which to download animated images.

Use true to download animated images as gifs and false to download as mp4 videos.

Type

string

Default

"https://api.mangadex.org"

Description

The server to use for API requests.

Type

object (name -> value)

Example

{"order[updatedAt]": "desc"}

Description

Additional query parameters to send when fetching manga chapters.

(See /manga/{id}/feed and /user/follows/manga/feed)

Type

• string
• list of strings

Example

• "en"
• "fr,it"
• ["fr", "it"]

Description

ISO 639-1 language codes to filter chapters by.

Type

list of strings

Default

["safe", "suggestive", "erotica", "pornographic"]

Description

List of acceptable content ratings for returned chapters.

Type

• string
• integer

Example

• "koala:en"
• 15150116

Description

Select chapter source and language for a manga.

The general syntax is "<source name>:<ISO 639-1 language code>".

Both are optional, meaning "koala", "koala:", ":en", or even just ":" are possible as well.

Specifying the numeric ID of a source is also supported.

Type

string

Default

null

Description

The access-token value you get from linking your account to gallery-dl.

Note: gallery-dl comes with built-in tokens for mastodon.social, pawoo and baraag. For other instances, you need to obtain an access-token in order to use usernames in place of numerical user IDs.

Type

bool

Default

false

Description

Fetch media from cards.

Type

bool

Default

false

Description

Fetch media from reblogged posts.

Type

bool

Default

true

Description

Fetch media from replies to other posts.

Type

bool

Default

false

Description

Also emit metadata for text-only posts without media content.

Type

string

Description

Your access token, necessary to fetch favorited notes.

Type

bool

Default

false

Description

Fetch media from renoted notes.

Type

bool

Default

true

Description

Fetch media from replies to other notes.

Type

bool

Default

false

Description

Extract extended pool metadata.

Note: Not supported by all moebooru instances.

Type

bool

Default

true

Description

Download original Adobe Flash animations instead of pre-rendered videos.

Type

• string
• list of string

Default

"original"

Example

• "720p"
• ["mp4", "mov", "1080p", "720p"]

Description

Selects the preferred format for video downloads.

If the selected format is not available, the next smaller one gets chosen.

If this is a list, try each given filename extension in original resolution or recoded format until an available format is found.

Type

• string
• list of strings

Default

"art"

Example

• "movies,audio"
• ["movies", "audio"]

Description

A (comma-separated) list of subcategories to include when processing a user profile.

Possible values are "art", "audio", "games", "movies".

It is possible to use "all" instead of listing all values separately.

Type

• string
• list of strings

Default

"illustration,doujin"

Description

A (comma-separated) list of subcategories to include when processing a user profile.

Possible values are "illustration", "doujin", "favorite", "nuita".

It is possible to use "all" instead of listing all values separately.

Type

bool

Default

false

Description

Fetch media from quoted Tweets.

Type

bool

Default

false

Description

Fetch media from Retweets.

Type

• bool
• string

Default

true

Description

Control video download behavior.

• true: Download videos
• "ytdl": Download videos using yt-dlp/youtube-dl
• false: Skip video Tweets

Type

bool

Default

true

Description

Controls how a user is directed to an OAuth authorization page.

• true: Use Python's webbrowser.open() method to automatically open the URL in the user's default browser.
• false: Ask the user to copy & paste an URL from the terminal.

Type

bool

Default

true

Description

Store tokens received during OAuth authorizations in cache.

Type

string

Default

"localhost"

Description

Host name / IP address to bind to during OAuth authorization.

Type

integer

Default

6414

Description

Port number to listen on during OAuth authorization.

Note: All redirects will go to port 6414, regardless of the port specified here. You'll have to manually adjust the port number in your browser's address bar when using a different port than the default.

Type

bool

Default

false

Description

Extract additional metadata (source, uploader)

Note: This requires 1 additional HTTP request per post.

Type

list of strings

Default

["images", "image_large", "attachments", "postfile", "content"]

Description

Determines types and order of files to download.

Available types:

• postfile
• images
• image_large
• attachments
• content

Type

string

Default

"download_url"

Description

Selects the format of images files.

Possible formats:

• original
• default
• default_small
• default_blurred
• default_blurred_small
• thumbnail
• thumbnail_large
• thumbnail_small
• url
• download_url

Type

bool

Default

false

Description

Follow links to external sites, e.g. Twitter,

Type

bool

Default

true

Description

Extract inline images.

Type

bool

Default

false

Description

Extract media from reblogged posts.

Type

string

Default

"auto"

Description

Specifies the domain used by pinterest extractors.

Setting this option to "auto" uses the same domain as a given input URL.

Type

bool

Default

true

Description

Include pins from board sections.

Type

bool

Default

true

Description

Extract files from story pins.

Type

bool

Default

true

Description

Download from video pins.

Type

string

Description

Your account's API key

Type

• string
• list of strings

Default

"artworks"

Example

• "avatar,background,artworks"
• ["avatar", "background", "artworks"]

Description

A (comma-separated) list of subcategories to include when processing a user profile.

Possible values are "artworks", "avatar", "background", "favorite", "novel-user", "novel-bookmark".

It is possible to use "all" instead of listing all values separately.

Type

string

Description

The refresh-token value you get from running gallery-dl oauth:pixiv (see OAuth) or by using a third-party tool like gppt.

Type

bool

Default

false

Description

Download cover images.

Type

bool

Default

false

Description

Download embedded images.

Type

bool

Default

false

Description

When downloading a novel being part of a series, download all novels of that series.

Type

bool

Default

false

Description

Fetch extended user metadata.

Type

bool

Default

false

Description

For works bookmarked by your own account, fetch bookmark tags as tags_bookmark metadata.

Note: This requires 1 additional API request per bookmarked post.

Type

bool

Default

false

Description

For works with seemingly empty caption metadata, try to grab the actual caption value using the AJAX API.

Type

bool

Default

false

Description

Fetch comments metadata.

Note: This requires 1 or more additional API requests per post, depending on the number of comments.

Type

bool

Default

false

Description

Also download related artworks.

Type

string

Default

"japanese"

Description

Controls the tags metadata field.

• "japanese": List of Japanese tags
• "translated": List of translated tags
• "original": Unmodified list with both Japanese and translated tags

Type

• bool
• string

Default

true

Description

Download Pixiv's Ugoira animations.

These animations come as a .zip archive containing all animation frames in JPEG format by default.

Set this option to "original" to download them as individual, higher-quality frames.

Use an ugoira post processor to convert them to watchable animations. (Example)

Type

integer

Default

0

Description

When downloading galleries, this sets the maximum number of posts to get. A value of 0 means no limit.

Type

bool

Default

true

Description

Try to fetch limit_sanity_level works via web API.

Type

bool

Default

false

Description

Also search Plurk comments for URLs.

Type

bool

Default

false

Description

Whether or not to save the body for link/image posts.

Type

bool

Default

false

Description

Format in which to download animated images.

Use true to download animated images as gifs and false to download as mp4 videos.

Type

string

Default

"stop"

Description

Controls how to handle redirects to CAPTCHA pages.

• "stop: Stop the current extractor run.
• "wait: Ask the user to solve the CAPTCHA and wait.

Type

string

Default

"auto"

Description

Sets the quality query parameter of issue pages. ("lq" or "hq")

"auto" uses the quality parameter of the input URL or "hq" if not present.

Type

integer

Default

0

Description

The value of the limit parameter when loading a submission and its comments. This number (roughly) specifies the total amount of comments being retrieved with the first API call.

Reddit's internal default and maximum values for this parameter appear to be 200 and 500 respectively.

The value 0 ignores all comments and significantly reduces the time required when scanning a subreddit.

Type

bool

Default

false

Description

Retrieve additional comments by resolving the more comment stubs in the base comment tree.

Note: This requires 1 additional API call for every 100 extra comments.

Type

bool

Default

true

Description

Download embedded comments media.

Type

Date

Default

0 and 253402210800 (timestamp of datetime.max)

Description

Ignore all submissions posted before/after this date.

Type

string

Example

"6kmzv2"

Description

Ignore all submissions posted before/after the submission with this ID.

Type

bool

Default

true

Description

For failed downloads from external URLs / child extractors, download Reddit's preview image/video if available.

Type

integer

Default

0

Description

Reddit extractors can recursively visit other submissions linked to in the initial set of submissions. This value sets the maximum recursion depth.

Special values:

• 0: Recursion is disabled
• -1: Infinite recursion (don't do this)

Type

string

Default

null

Description

The refresh-token value you get from linking your Reddit account to gallery-dl.

Using a refresh-token allows you to access private or otherwise not publicly available subreddits, given that your account is authorized to do so, but requests to the reddit API are going to be rate limited at 600 requests every 10 minutes/600 seconds.

Type

• bool
• string

Default

true

Description

Control video download behavior.

• true: Download videos and use yt-dlp/youtube-dl to handle HLS and DASH manifests
• "ytdl": Download videos and let yt-dlp/youtube-dl handle all of video extraction and download
• "dash": Extract DASH manifest URLs and use yt-dlp/youtube-dl to download and merge them. (*)
• false: Ignore videos

(*) This saves 1 HTTP request per video and might potentially be able to download otherwise deleted videos, but it will not always get the best video quality available.

Type

• string
• list of strings

Default

["hd", "sd", "gif"]

Description

List of names of the preferred animation format, which can be "hd", "sd", "gif", "thumbnail", "vthumbnail", or "poster".

If a selected format is not available, the next one in the list will be tried until an available format is found.

If the format is given as string, it will be extended with ["hd", "sd", "gif"]. Use a list with one element to restrict it to only one possible format.

Type

• string
• list of strings

Default

["10", "40", "41", "2"]

Example

"33,34,4"

Description

Selects the file format to extract.

When more than one format is given, the first available one is selected.

Type

string

Default

"numeric"

Description

Format of id metadata fields.

• "alphanumeric" or "alnum": 11-character alphanumeric IDs (y0abGlDOr2o)
• "numeric" or "legacy": numeric IDs (360451)

Type

bool

Default

false

Description

Refresh download URLs before they expire.

Type

bool

Default

false

Description

Download video embeds from external sites.

Type

bool

Default

true

Description

Download videos.

Type

bool

Default

false

Description

Download article images.

Type

bool

Default

false

Description

Download sent requests.

Type

bool

Default

false

Description

Download thumbnails.

Type

• string
• list of strings

Default

["genre:art", "genre:voice", "genre:novel", "genre:video", "genre:music", "genre:correction"]

Example

"genre:music OR genre:voice"

Description

Filters used during searches.

Type

bool

Default

true

Description

Download video files.

Type

bool

Default

true

Description

Include animated assets when downloading from a list of assets.

Type

bool

Default

true

Description

Include assets tagged with epilepsy when downloading from a list of assets.

Type

• string
• list of strings

Default

"all"

Examples

• "1024x512,512x512"
• ["460x215", "920x430"]

Description

Only include assets that are in the specified dimensions. all can be used to specify all dimensions. Valid values are:

• Grids: 460x215, 920x430, 600x900, 342x482, 660x930, 512x512, 1024x1024
• Heroes: 1920x620, 3840x1240, 1600x650
• Logos: N/A (will be ignored)
• Icons: 8x8, 10x10, 14x14, 16x16, 20x20, 24x24, 28x28, 32x32, 35x35, 40x40, 48x48, 54x54, 56x56, 57x57, 60x60, 64x64, 72x72, 76x76, 80x80, 90x90, 96x96, 100x100, 114x114, 120x120, 128x128, 144x144, 150x150, 152x152, 160x160, 180x180, 192x192, 194x194, 256x256, 310x310, 512x512, 768x768, 1024x1024

Type

• string
• list of strings

Default

"all"

Examples

• "png,jpeg"
• ["jpeg", "webp"]

Description

Only include assets that are in the specified file types. all can be used to specify all file types. Valid values are:

• Grids: png, jpeg, jpg, webp
• Heroes: png, jpeg, jpg, webp
• Logos: png, webp
• Icons: png, ico

Type

bool

Default

true

Description

Download fake PNGs alongside the real file.

Type

bool

Default

true

Description

Include assets tagged with humor when downloading from a list of assets.

Type

• string
• list of strings

Default

"all"

Examples

• "en,km"
• ["fr", "it"]

Description

Only include assets that are in the specified languages. all can be used to specify all languages. Valid values are ISO 639-1 language codes.

Type

bool

Default

true

Description

Include assets tagged with adult content when downloading from a list of assets.

Type

string

Default

score_desc

Description

Set the chosen sorting method when downloading from a list of assets. Can be one of:

• score_desc (Highest Score (Beta))
• score_asc (Lowest Score (Beta))
• score_old_desc (Highest Score (Old))
• score_old_asc (Lowest Score (Old))
• age_desc (Newest First)
• age_asc (Oldest First)

Type

bool

Default

true

Description

Include static assets when downloading from a list of assets.

Type

• string
• list of strings

Default

all

Examples

• white,black
• ["no_logo", "white_logo"]

Description

Only include assets that are in the specified styles. all can be used to specify all styles. Valid values are:

• Grids: alternate, blurred, no_logo, material, white_logo
• Heroes: alternate, blurred, material
• Logos: official, white, black, custom
• Icons: official, custom

Type

bool

Default

true

Description

Include untagged assets when downloading from a list of assets.

Type

string

Description

Username and login token of your account to access private resources.

To generate a token, visit /user/USERNAME/list-tokens and click Create Token.

Type

bool

Default

false

Description

Download blog avatars.

Type

Date

Default

0 and null

Description

Ignore all posts published before/after this date.

Type

bool

Default

false

Description

Follow external URLs (e.g. from "Link" posts) and try to extract images from them.

Type

bool

Default

true

Description

Search posts for inline images and videos.

Type

integer

Default

0

Description

Custom offset starting value when paginating over blog posts.

Allows skipping over posts without having to waste API calls.

Type

bool

Default

true

Description

Download full-resolution photo and inline images.

For each photo with "maximum" resolution (width equal to 2048 or height equal to 3072) or each inline image, use an extra HTTP request to find the URL to its full-resolution version.

Type

string

Default

"offset"

Description

Controls how to paginate over blog posts.

• "api": next parameter provided by the API (potentially misses posts due to a bug in Tumblr's API)
• "before": timestamp of last post
• "offset": post offset number

Type

string

Default

"abort"

Description

Selects how to handle exceeding the daily API rate limit.

• "abort": Raise an error and stop extraction
• "wait": Wait until rate limit reset

Type

• bool
• string

Default

true

Description

• true: Extract media from reblogged posts
• false: Skip reblogged posts
• "same-blog": Skip reblogged posts unless the original post is from the same blog

Type

• string
• list of strings

Default

"all"

Example

• "video,audio,link"
• ["video", "audio", "link"]

Description

A (comma-separated) list of post types to extract images, etc. from.

Possible types are text, quote, link, answer, video, audio, photo, chat.

It is possible to use "all" instead of listing all types separately.

Type

float

Default

120.0

Description

Number of seconds to wait between retries for fetching full-resolution images.

Type

integer

Default

2

Description

Number of retries for fetching full-resolution images or -1 for infinite retries.

Type

string

Default

null

Description

Your Twibooru API Key, to use your account's browsing settings and filters.

Type

integer

Default

2 (Everything filter)

Description

The content filter ID to use.

Setting an explicit filter ID overrides any default filters and can be used to access 18+ content without API Key.

See Filters for details.

Type

bool

Default

true

Description

Download SVG versions of images when available.

Try to download the view_url version of these posts when this option is disabled.

Type

bool

Default

false

Description

Fetch media from promoted Tweets.

Type

• bool
• string

Default

false

Description

Controls how to handle Twitter Cards.

• false: Ignore cards
• true: Download image content from supported cards
• "ytdl": Additionally download video content from unsupported cards using yt-dlp/youtube-dl

Type

list of strings

Example

["summary", "youtube.com", "player:twitch.tv"]

Description

List of card types to ignore.

Possible values are

• card names
• card domains
• <card name>:<card domain>

Type

• bool
• string

Default

false

Description

For input URLs pointing to a single Tweet, e.g. https://twitter.com/i/web/status/<TweetID>, fetch media from all Tweets and replies in this conversation.

If this option is equal to "accessible", only download from conversation Tweets if the given initial Tweet is accessible.

Type

string

Default

"cookies"

Description

Controls how to handle Cross Site Request Forgery (CSRF) tokens.

• "auto": Always auto-generate a token.
• "cookies": Use token given by the ct0 cookie if present.

Type

• bool
• string

Default

true

Example

"1/DAABCgABGVKi5lE___oKAAIYbfYNcxrQLggAAwAAAAIAAA"

Description

Controls from which position to start the extraction process from.

• true: Start from the beginning. Log the most recent cursor value when interrupted before reaching the end.
• false: Start from the beginning.
• any string: Start from the position defined by this value.

Note: A cursor value from one timeline cannot be used with another.

Type

bool

Default

false

Description

For each Tweet, return all Tweets from that initial Tweet's conversation or thread, i.e. expand all Twitter threads.

Going through a timeline with this option enabled is essentially the same as running gallery-dl https://twitter.com/i/web/status/<TweetID> with enabled conversations option for each Tweet in said timeline.

Note: This requires at least 1 additional API call per initial Tweet.

Type

bool

Default

false

Description

Try to download media marked as Unavailable, e.g. Geoblocked videos.

Type

• string
• list of strings

Default

"timeline"

Example

• "avatar,background,media"
• ["avatar", "background", "media"]

Description

A (comma-separated) list of subcategories to include when processing a user profile.

Possible values are "info", "avatar", "background", "timeline", "tweets", "media", "replies", "likes".

It is possible to use "all" instead of listing all values separately.

Type

bool

Default

true

Description

Transform Tweet and User metadata into a simpler, uniform format.

Type

string

Default

"auto"

Description

Selects the API endpoint used to retrieve single Tweets.

• "restid": /TweetResultByRestId - accessible to guest users
• "detail": /TweetDetail - more stable
• "auto": "detail" when logged in, "restid" otherwise

Type

list of strings

Default

["orig", "4096x4096", "large", "medium", "small"]

Description

The image version to download. Any entries after the first one will be used for potential fallback URLs.

Known available sizes are

• orig
• large
• medium
• small
• 4096x4096
• 900x900
• 360x360

Type

bool

Default

false

Description

Logout and retry as guest when access to another user's Tweets is blocked.

Type

bool

Default

false

Description

Fetch media from pinned Tweets.

Type

bool

Default

false

Description

Fetch media from quoted Tweets.

If this option is enabled, gallery-dl will try to fetch a quoted (original) Tweet when it sees the Tweet which quotes it.

Type

string

Default

"wait"

Description

Selects how to handle exceeding the API rate limit.

• "abort": Raise an error and stop extraction
• "wait": Wait until rate limit reset
• "wait:N": Wait for N seconds

Type

bool

Default

true

Description

When receiving a "Could not authenticate you" error while logged in with username & passeword, refresh the current login session and try to continue from where it left off.

Type

string

Default

"abort"

Description

Selects how to handle "account is temporarily locked" errors.

• "abort": Raise an error and stop extraction
• "wait": Wait until the account is unlocked and retry

Type

bool

Default

true

Description

Fetch media from replies to other Tweets.

If this value is "self", only consider replies where reply and original Tweet are from the same user.

Note: Twitter will automatically expand conversations if you use the /with_replies timeline while logged in. For example, media from Tweets which the user replied to will also be downloaded.

It is possible to exclude unwanted Tweets using image-filter.

Type

bool

Default

false

Description

Fetch media from Retweets.

If this value is "original", metadata for these files will be taken from the original Tweets, not the Retweets.

Type

string

Default

"auto"

Description

Controls the strategy / tweet source used for timeline URLs (https://twitter.com/USER/timeline).

• "tweets": /tweets timeline + search
• "media": /media timeline + search
• "with_replies": /with_replies timeline + search
• "auto": "tweets" or "media", depending on retweets and text-tweets settings

Type

bool

Default

false

Description

Also emit metadata for text-only Tweets without media content.

This only has an effect with a metadata (or exec) post processor with "event": "post" and appropriate filename.

Type

bool

Default

false

Description

Extract TwitPic embeds.

Type

bool

Default

true

Description

Ignore previously seen Tweets.

Type

string

Description

Alternate Identifier (username, email, phone number) when logging in.

When not specified and asked for by Twitter, this identifier will need to entered in an interactive prompt.

Type

string

Default

"user"

Example

"https://twitter.com/search?q=from:{legacy[screen_name]}"

Description

Format string for user URLs generated from following and list-members queries,

whose replacement field values come from Twitter user objects (Example)

Special values:

• "user": https://twitter.com/i/user/{rest_id}
• "timeline": https://twitter.com/id:{rest_id}/timeline
• "tweets": https://twitter.com/id:{rest_id}/tweets
• "media": https://twitter.com/id:{rest_id}/media

Note: To allow gallery-dl to follow custom URL formats, set the blacklist for twitter to a non-default value, e.g. an empty string "".

Type

• bool
• string

Default

true

Description

Control video download behavior.

• true: Download videos
• "ytdl": Download videos using yt-dlp/youtube-dl
• false: Skip video Tweets

Type

string

Default

"raw"

Description

Name of the image format to download.

Available formats are "raw", "full", "regular", "small", and "thumb".

Type

string

Default

"vipergirls.to"

Description

Specifies the domain used by vipergirls extractors.

For example "viper.click" if the main domain is blocked or to bypass Cloudflare,

Type

bool

Default

false

Description

Automatically like posts after downloading their images.

Note: Requires login or cookies

Type

integer

Default

0

Description

Custom offset starting value when paginating over image results.

Type

• string
• list of strings

Default

"gallery"

Example

• "avatar,collection"
• ["avatar", "collection"]

Description

A (comma-separated) list of subcategories to include when processing a user profile.

Possible values are "avatar", "gallery", "spaces", "collection",

It is possible to use "all" instead of listing all values separately.

Type

bool

Default

true

Description

Download video files.