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

* .. code:: json

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

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.

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.

Special values:

* "auto": Use characters from "unix" or "windows" depending on the local operating system
* "unix": "/"
* "windows": "\\\\|/<>:\"?*"
* "ascii": "^0-9A-Za-z_."

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

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

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

* 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.)

Specifying a username and password is required for

* nijie
* seiga

and optional for

* aryion
* danbooru (*)
* e621 (*)
* exhentai
* idolcomplex
* imgbb
* inkbunny
* instagram
* mangadex
* mangoxo
* pillowfort
* pinterest
* sankaku
* subscribestar
* tapas
* tsumino
* twitter

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 danbooru and e621 should be the API key found in your user profile, not the actual account password.

* the Path to a Mozilla/Netscape format cookies.txt file or
* a JSON object specifying cookies as a name-to-value mapping

Example:

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

* 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.

Example:

{ "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" }

Note: All proxy URLs should include a scheme, otherwise http:// is assumed.

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

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.

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

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 paths support regular format string replacements, but be aware that using external inputs for building local paths may pose a security risk.

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

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.

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

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.

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

Note: The index of the first image is 1.

Files for which the expression evaluates to False are ignored.
Available keys are the filename-specific ones listed by -K or -j.

See strptime for a list of formatting directives.

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

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

See Filters for details.

Note: Enabling this option also enables deviantart.metadata_.

* 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.

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

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

You can use "all" instead of listing all values separately.

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

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.

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

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.

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

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

* 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.

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

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

You can use "all" instead of listing all values separately.

If the selected format is not available, "mp4", "webm" and "gif" (in that order) will be tried instead, until an available format is found.

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

You can use "all" instead of listing all values separately.

* 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.

(See API#Search for details)

Possible values are "posts", "reels", "channel", "tagged", "stories", "highlights".

You can use "all" instead of listing all values separately.

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).

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

You can use "all" instead of listing all values separately.

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

You can use "all" instead of listing all values separately.

* 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.

Note: All redirects will go to http://localhost: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.

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

These animations come as a .zip file containing all animation frames in JPEG format.

Use an ugoira post processor to convert them to watchable videos. (Example__)

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

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.

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

Special values:

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

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.

* true: Download videos and use youtube-dl to handle HLS and DASH manifests
* "ytdl": Download videos and let youtube-dl handle all of video extraction and download
* false: Ignore videos

If the selected format is not available, "mp4", "webm" and "gif" (in that order) will be tried instead, until an available format is found.

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

You can use "all" instead of listing all types separately.

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

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

Special values:

* "timeline": https://twitter.com/i/user/{rest_id}
* "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 "".

* true: Download videos
* "ytdl": Download videos using youtube-dl
* false: Skip video Tweets

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

See https://wallhaven.cc/help/api for more information.

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

* true: Start with the latest chapter
* false: Start with the first chapter

Possible values are valid integer or floating-point numbers optionally followed by one of k, m. g, t or p. These suffixes are case-insensitive.

* true: Write downloaded data into .part files and rename them upon download completion. This mode additionally supports resuming incomplete downloads.
* false: Do not use .part files and write data directly into the actual output files.

Missing directories will be created as needed. If this value is null, .part files are going to be stored alongside the actual output files.

Possible values are valid integer or floating-point numbers optionally followed by one of k, m. g, t or p. These suffixes are case-insensitive.

Note: Set quiet and no_warnings in downloader.ytdl.raw-options to true to suppress all output.

Special values:

* null: generate filenames with extractor.*.filename
* "default": use youtube-dl's default, currently "%(title)s-%(id)s.%(ext)s"

Note: An output template other than null might cause unexpected results in combination with other options (e.g. "skip": "enumerate")

{ "quiet": true, "writesubtitles": true, "merge_output_format": "mkv" }

All available options can be found in youtube-dl's docstrings <https://github.com/ytdl-org/youtube-dl/blob/master/youtube_dl/YoutubeDL.py#L138-L318>.

* "null": No output
* "pipe": Suitable for piping to other processes or files
* "terminal": Suitable for the standard Windows console
* "color": Suitable for terminals that understand ANSI escape codes and colors
* "auto": Automatically choose the best suitable output mode

* true: Show the default progress indicator ("[{current}/{total}] {url}")
* false: Do not show any progress indicator
* Any string: Show the progress indicator using this as a custom format string. Possible replacement keys are current, total and url.

If this is a simple string, it specifies the format string for logging messages.

The default format string here is "{message}".

{ "Pictures": ["jpg", "jpeg", "png", "gif", "bmp", "svg", "webp"], "Video" : ["flv", "ogv", "avi", "mp4", "mpg", "mpeg", "3gp", "mkv", "webm", "vob", "wmv"], "Music" : ["mp3", "aac", "flac", "ogg", "wma", "m4a", "wav"], "Archives": ["zip", "rar", "7z", "tar", "gz", "bz2"] }

Files with an extension not listed will be ignored and stored in their default location.

* "replace": Replace/Overwrite the old version with the new one
* "enumerate": Add an enumeration index to the filename of the new version like skip = "enumerate"

* If this is a string, it will be executed using the system's shell, e.g. /bin/sh. Any {} will be replaced with the full path of a file or target directory, depending on exec.event

* If this is a list, the first element specifies the program name and any further elements its arguments. Each element of this list is treated as a format string using the files' metadata as well as {_path}, {_directory}, and {_filename}.

See metadata.event for a list of available events.

* "json": all metadata using json.dump() <https://docs.python.org/3/library/json.html#json.dump>
* "tags": tags separated by newlines
* "custom": result of applying metadata.content-format to a file's metadata dictionary

If this option is set, metadata.extension and metadata.extension-format will be ignored.

Note: metadata.extension is ignored if this option is set.

The available events are:

init After post processor initialization and before the first file download finalize On extractor shutdown, e.g. after all files were downloaded prepare Before a file download file When completing a file download, but before it gets moved to its target location after After a file got moved to its target location skip When skipping a file download post When starting to download all files of a post, e.g. a Tweet on Twitter or a post on Patreon.

Note: Only applies for "mode": "custom".

This value must either be a UNIX timestamp or a datetime object.

* "auto": Automatically assign a fitting frame rate based on delays between frames.
* any other string: Use this value as argument for -r.
* null or an empty string: Don't set an explicit frame rate.

This option, when libx264/5 is used, automatically adds ["-vf", "crop=iw-mod(iw\\,2):ih-mod(ih\\,2)"] to the list of FFmpeg command-line arguments to reduce an odd width/height by 1 pixel and make them even.

* "safe": Update the central directory file header each time a file is stored in a ZIP archive.

This greatly reduces the chance a ZIP archive gets corrupted in case the Python interpreter gets shut down unexpectedly (power outage, SIGKILL) but is also a lot slower.

Set this option to null or an invalid path to disable this cache.

* If given as string, it is parsed according to date-format.
* If given as integer, it is interpreted as UTC timestamp.

Simple tilde expansion and environment variable expansion is supported.

In Windows environments, backslashes ("\") can, in addition to forward slashes ("/"), be used as path separators. Because backslashes are JSON's escape character, they themselves have to be escaped. The path C:\path\to\file.ext has therefore to be written as "C:\\path\\to\\file.ext" if you want to use backslashes.

{ "format" : "{asctime} {name}: {message}", "format-date": "%H:%M:%S", "path" : "~/log.txt", "encoding" : "ascii" }

{ "level" : "debug", "format": { "debug" : "debug: {message}", "info" : "[{name}] {message}", "warning": "Warning: {message}", "error" : "ERROR: {message}" } }

* format
* General format string for logging messages or a dictionary with format strings for each loglevel.

In addition to the default LogRecord attributes, it is also possible to access the current extractor, job, path, and keywords objects and their attributes, for example "{extractor.url}", "{path.filename}", "{keywords.title}"
* Default: "[{name}][{levelname}] {message}"
* format-date
* Format string for {asctime} fields in logging messages (see strftime() directives)
* Default: "%Y-%m-%d %H:%M:%S"
* level
* Minimum logging message level (one of "debug", "info", "warning", "error", "exception")
* Default: "info"
* path
* Path to the output file
* mode
* Mode in which the file is opened; use "w" to truncate or "a" to append (see open())
* Default: "w"
* encoding
* File encoding
* Default: "utf-8"

Note: path, mode, and encoding are only applied when configuring logging output to a file.

{ "name": "mtime" }

{ "name" : "zip", "compression": "store", "extension" : "cbz", "filter" : "extension not in ('zip', 'rar')", "whitelist" : ["mangadex", "exhentai", "nhentai"] }

It is possible to set a "filter" expression similar to image-filter to only run a post-processor conditionally.

It is also possible set a "whitelist" or "blacklist" to only enable or disable a post-processor for the specified extractor categories.

The available post-processor types are

classify Categorize files by filename extension compare Compare versions of the same file and replace/enumerate them on mismatch
(requires downloader.*.part = true and extractor.*.skip = false)
exec Execute external commands metadata Write metadata to separate files mtime Set file modification time according to its metadata ugoira Convert Pixiv Ugoira to WebM using FFmpeg zip Store files in a ZIP archive