Downloading

Last updated 2026-10-11

Every way to download content with comic-dl — single URLs, URL files, chapter selection, and scripting.

Download a single URL, queue a file of URLs, or select chapters from a series. For a first run, start with Quick Start; use this guide for batch downloads, size limits, and scripting.

Download a single URL

$ comic-dl -u https://asurascans.com/comics/demo-series/

The -u / --url flag accepts any URL from a supported site.

Download from a file

Create a text file with one URL per line:

# My comics
https://asurascans.com/comics/demo-series/chapter/1       # weekend batch
https://manhuato.com/manhua/demo-slug/

$ comic-dl -f urls.txt

Blank lines and lines starting with # are skipped. Inline # comments after a URL are stripped. Duplicate URLs are downloaded once. Lines that are not http(s):// URLs produce a warning naming the file and line.

If any URL fails, processing continues and a summary is printed at the end. The exit code is 1 when one or more downloads fail; see Exit Codes. Each error is annotated with its origin (e.g. Failed: https://... (urls.txt:12)).

Interactive mode

Run without arguments to be prompted for input:

$ comic-dl

The tool accepts either a gallery URL or a text file path. Requires a TTY; scripts must use -u or -f.

Custom output directory

$ comic-dl -u <URL> -o ~/Comics

Default: ~/Downloads/comic-dl/.

Chapter selection

When a URL points at a series (multiple chapters), comic-dl presents an interactive chapter picker by default. To skip the picker:

$ comic-dl -u <series-url> --chapters all       # download everything
$ comic-dl -u <series-url> --chapters 1-3,5     # specific chapters
$ comic-dl -u <series-url> --chapters 7          # a single chapter

--chapters selects by chapter number, not by the row number shown in the listing. Chapters are numbered as the site numbers them: a prologue/promo chapter labeled Ch. 0 is selected with 0, so --chapters 0-1 downloads the prologue plus chapter 1. Chapters without a number (e.g. an unnumbered one-shot or a “Season 1 End” extra) can’t be matched by number; use --chapters all for those. Only numbers and ranges are accepted (q/quit is reserved for the interactive picker).

Size limits

Per-image limit

$ comic-dl -u <URL> --max-image-size 50MB

Default: 100 MB. Images exceeding this are rejected. Accepts suffixed values (500 KB, 1 GB) or plain bytes.

Per-run limit

$ comic-dl -u <URL> --max-size 2GB

Default: 0 (unlimited). When an estimate exceeds this limit, the chapter is counted as failed (exit code 1) but other URLs continue.

Re-downloading

By default, already-downloaded chapters are skipped. To force a re-download:

$ comic-dl -u <URL> --force

--force bypasses both the on-disk check and the library index, overwriting existing files.

When --force is combined with a multi-URL file and re-downloads would occur, comic-dl asks for confirmation first. Non-interactive runs (--json) refuse unsolicited with exit code 130 (same class as an unanswerable confirmation prompt).

Dry run

Preview what a run would do without writing anything:

$ comic-dl -f urls.txt --dry-run
$ comic-dl -f urls.txt --force --dry-run    # preview re-downloads
$ comic-dl -f urls.txt --dry-run --json     # machine-readable preview

--dry-run resolves metadata asynchronously and reports the action (download, skip, or redownload), archive destination, and estimated total. No writes are made and no prompts are shown.

Quiet mode

Suppress all output except errors:

$ comic-dl -f urls.txt --quiet

Useful for scripts and cron jobs.

JSON output

Machine-readable output for scripting:

$ comic-dl -u <URL> --json
$ comic-dl -f urls.txt --json
$ comic-dl list --json
$ comic-dl info <series> --json
$ comic-dl latest --json

--json implies non-interactive mode. All human output goes to stderr; stdout receives only the JSON payload. Every payload includes a schema_version field (currently 2).

See JSON output shapes for the command-by-command reference.

Verbosity

Control diagnostic output with -v flags:

Diagnostic lines go to stderr with tagged prefixes ([http], [retry], [scrape], [timing], [download], [trace], [context]).

Set COMIC_DL_TRACE_HTTP=1 to surface page-request response headers at -vv without needing -vvv (image headers still need -vvv).

Interrupting a run

Press Ctrl-C once to stop gracefully. The current download finishes, partial .part files are kept for resume, and the process exits with code 130. A resume hint echoes the command you ran.

Press Ctrl-C twice within 2 seconds to force-quit immediately.

SIGTERM behaves identically to SIGINT.

Platform notes

• Windows: use Windows Terminal for Unicode support. In classic cmd.exe, run chcp 65001 first.
• Windows long paths: deep series trees can exceed MAX_PATH. Enable the system long-path policy or keep the output directory short.
• macOS: no binaries are distributed yet — build from source (git clone + uv sync). See Installation.