manga-downloader

⭐ If you like this project, star it on GitHub!

Website • Features • Installation • Desktop app • Command line • Supported sites • Troubleshooting

Manga Downloader downloads manga chapters from MangaDex and more than 100 other sites and packs them into CBZ files, ready to read on your e-reader or in your favorite comic app. It comes as a desktop app for Windows, macOS and Linux, and as a command line tool for scripts, servers and Docker.

Desktop app

• Paste a URL and it loads: the series, its chapters and the languages and scanlation groups it offers appear on their own.
• Pick what you need: type a range such as 1-10,12, Shift+click a span, or select all, then choose the language and scanlation group the series has.
• Live progress: every chapter shows up as it's fetched and packed, with a summary and an Open folder button when it's done.
• Native folder picker, and a window that follows your system's light or dark theme.

Desktop app and command line

• 115 supported sites, from big aggregators to small scanlation groups.
• Chapter ranges such as 1,3,5-10, so you download only what's missing.
• E-reader friendly output: AVIF and WebP pages are converted to JPEG, so they don't show up blank on Kobo, KOReader or Calibre.
• Flexible output: one CBZ per chapter, one per volume (--volumes), a single bundled CBZ (--bundle), or plain image folders (--format raw), named from a template.
• Language and scanlation group filters for sites that host several versions of a chapter, and skipping pages such as credits or ads.
• Concurrent downloads with retries.
• JavaScript and Cloudflare-protected sites are handled by driving a local Chromium browser, which clicks "Verify you are human" checkboxes for you.

Command line

• A single binary with no runtime, no dependencies and no config file, plus Docker images.

The easiest way is the website, which picks the right download for your system. Or download the manga-downloader-gui asset for your system from the releases page:

• Windows: manga-downloader-gui-<tag>-windows-amd64.zip, or -windows-arm64.zip for ARM devices such as Snapdragon laptops. Unzip it and run manga-downloader-gui.exe.

• macOS: manga-downloader-gui-<tag>-darwin-universal.zip. Unzip it and move Manga Downloader.app wherever you like. Or install it with Homebrew, which also puts manga-downloader-gui on your PATH:

  brew install --cask elboletaire/tap/manga-downloader

  The cask installs the command line tool too, so manga-downloader ui works. Mind the --cask: without it, Homebrew installs only the command line tool, which shares the name.

• Linux: manga-downloader-gui-<tag>-linux-amd64.tar.gz, or -linux-arm64.tar.gz. Extract it and run manga-downloader-gui. It needs WebKitGTK 4.1 (libwebkit2gtk-4.1-0 on Debian and Ubuntu), which most desktops already have.

If the desktop app sits next to the command line tool or is on your PATH (the Homebrew cask puts it there), manga-downloader ui opens it. On Windows, double-clicking manga-downloader.exe does the same.

When a newer release is out, a yellow ! next to the version in the status bar links to it.

On macOS and Linux, install the command line tool from Homebrew:

brew install elboletaire/tap/manga-downloader

Homebrew doesn't quarantine the command line tool, so there's no Gatekeeper step on macOS. brew upgrade manga-downloader updates it.

This installs only the command line tool. On macOS, the desktop app is a cask with the same name, which installs both and gets manga-downloader ui working:

brew install --cask elboletaire/tap/manga-downloader

Download the archive for your system from the releases page, extract it and run the binary:

./manga-downloader --help

Builds are published for Linux, macOS and Windows on amd64 and arm64 (Windows arm64 included), plus 32-bit builds for Linux and Windows. The Windows 32-bit build is named windows-32bit-legacy.

To run it from any folder, move the binary to a folder in your PATH, such as /usr/local/bin on Linux and macOS.

docker run --rm -it -v "$PWD:/downloads" elboletaire/manga-downloader [url] [chapters]

Files are written to the mounted /downloads folder. They're owned by USER_ID/GROUP_ID, which both default to 1000. If your user has a different ID, pass it with -e USER_ID=$(id -u) -e GROUP_ID=$(id -g).

:latest and :browser follow releases. The current development version is :master (and :master-browser).

The default image has no browser. For sites marked with *, use the :browser image, which ships Chromium and a virtual display:

docker run --rm -it -v "$PWD:/downloads" elboletaire/manga-downloader:browser [url] [chapters]

docker run --rm -it -e DISPLAY=$DISPLAY -v /tmp/.X11-unix:/tmp/.X11-unix \
    -v "$PWD:/downloads" elboletaire/manga-downloader:browser --browser-visible [url] [chapters]

go install github.com/elboletaire/manga-downloader@latest

Open the app and follow these steps:

1. Paste the series' URL into the box at the top. The app loads the series on its own, without a button.

2. Pick chapters in the list. Type a range such as 1-10,12 and press Add range, Shift+click to select a span, or use All and None. The arrow keys and Space work too.

3. Choose a language and a scanlation group when the site offers them. The selectors only appear for series that list them, and picking one reloads the chapter list. Sites that support it also offer All.

   

4. Set the options in the Options tab: where the files go, the format (CBZ archive or image folder), Pack as (a file per chapter, per volume, or one for everything), Convert to JPEG for AVIF and WebP pages, pages to skip, the file name template, and whether to Show the browser window. Packing by volume adds a Volumes box above the chapter list, filled with the site's volumes when it lists them, and groups the list by volume.

   

5. Press Download. The Activity tab shows each chapter as it's fetched and packed. Cancel lets the chapters already downloading finish, and starts no new ones. A log is one click away in the status bar.

   

6. When it's done, the summary shows what was downloaded. Press Open folder to go straight to the files.

   

   If a chapter fails, the summary names it and says why; the other chapters are still saved.

   

The app saves your options to gui.json in the manga-downloader folder of your user config folder (the same place as the Manga Plus secret, see below), so they're still there the next time you open it. Files go to your Downloads folder (or your home folder, if there isn't one) unless you choose another folder.

The app uses the command line's defaults for concurrency and retries. Sites whose image servers limit the request rate get lower limits automatically, in both the app and the command line.

manga-downloader [flags] [url] [chapters]

• url is the manga's index page, the page that lists all its chapters. Don't use the URL of a single chapter.
• chapters is a comma-separated list of numbers and ranges, such as 1,3,5-10. If you leave it out, the tool asks whether to download every chapter. The answer defaults to "no".

Arguments aren't positional, so manga-downloader 1-50 [url] works too.

Some sites, such as MangaDex, list each chapter once per language. Use --language to download only one of them:

manga-downloader --language es https://mangadex.org/title/a1c7c817-4e59-43b7-9365-09675a149a6f 1-10

On sites that list several languages, --language all downloads every one of them.

Sites that host several scanlation groups' versions of the same chapter download the group with the most chapters, and list the other groups. Use --scanlator <name> to pick a group, or --scanlator all to download every version. With all, the group name is added to each file name.

# all chapters in a single CBZ, one folder per chapter inside it
manga-downloader --bundle [url] 1-8

# plain image folders instead of CBZ files
manga-downloader --format raw [url] 1-8

--volumes packs one file per volume. auto uses the volumes the site files chapters under (not every site lists them); otherwise give the chapters of each volume, separated by slashes, in the chapter range syntax:

manga-downloader --volumes 1-7/8-16 [url] 1-20

That writes Series Vol. 01.cbz and Series Vol. 02.cbz, with a folder per chapter inside, and chapters 17 to 20, outside every volume, one file each. The chapters argument still picks what's downloaded: a volume packs the chapters of it you asked for. A group can give its volume number with N:, and the groups after it count on from there:

manga-downloader --volumes 16:112-114/115-118 [url] 112-118

That's volumes 16 and 17. An empty group also skips a number (1-7//20-30 has no volume 2), and --volumes can't be combined with --bundle.

Most e-readers can't display AVIF, so a chapter with AVIF pages looks empty on the device even though the download succeeded. AVIF pages are converted to JPEG by default. WebP renders fine in phone apps but is unreliable on e-ink, so converting it is opt-in:

manga-downloader --convert-images avif,webp [url] 1-10   # strict e-ink setup
manga-downloader --convert-images none [url] 1-10        # keep pages untouched

JPEG, PNG and GIF pages are never re-encoded. If a page fails to convert, it's kept as it was and a warning is shown, so the rest of the chapter isn't lost.

The desktop app offers the same choice as two checkboxes, AVIF and WebP.

Scanlation groups often reserve a page or two of every chapter for their own credits or ads. --skip-pages drops them, using the same range syntax as the chapter argument, applied to each chapter's pages:

manga-downloader --skip-pages 2 [url] 1100-1110       # just the credits page
manga-downloader --skip-pages 2,5-7 [url] 1100-1110   # several at once

Pages count from 1, and negative positions count backwards from the end of the chapter: -1 is its last page, -3--1 the last three. They're resolved per chapter, so -1 means each chapter's own last page however long it is:

manga-downloader --skip-pages 2,-1 [url] 1100-1110    # one at each end

The pages are dropped before they're downloaded, so they cost no time or bandwidth, and a page that's broken on the site's end can't fail the chapter around it — which is the only way to download a chapter whose page 404s.

The archive is still numbered 000, 001, … in order, with no holes left by the skipped pages. A position the chapter doesn't have is ignored.

Use --filename-template to change file names. It takes a Go text/template string, and the default is:

{{.Series}} {{.Number}} - {{.Title}}{{if gt .Version 1}} v{{.Version}}{{end}}

{{.Version}} is a counter that's added when two files would have the same name, and {{.Volume}} is the volume number (0 when the site doesn't say); {{printf "%02d" .Volume}} pads it.

Volume files (--volumes) get their own default name while the template is left as is:

{{.Series}} Vol. {{printf "%02d" .Volume}}{{if gt .Version 1}} v{{.Version}}{{end}}

A custom template names them too, with {{.Number}} being the volume's chapters (1-7) and {{.Title}} Vol. 01.

Manga Plus answers the complete chapter list only to an app client, which authenticates with an anonymous device secret. manga-downloader registers one on first use and caches it in manga-downloader/mangaplus-secret inside your user config folder ($XDG_CONFIG_HOME or ~/.config on Linux, ~/Library/Application Support on macOS, %AppData% on Windows): no account is ever needed. Secrets are 32 lowercase hexadecimal characters, and anything that isn't one is treated as absent — so exporting a malformed MANGAPLUS_SECRET, or deleting the cached file, makes the next run register a fresh device, as does a cached secret the API stops accepting. Export a valid MANGAPLUS_SECRET to reuse a secret registered elsewhere, such as the one of a device with your Manga Plus subscription.

In Docker, the cached secret lives inside the container and is lost with it, so every run registers a new device. To keep one, either pass it with -e MANGAPLUS_SECRET=..., or mount your own config folder so the container shares the secret of your local install (create the folder first, or Docker creates it owned by root):

mkdir -p ~/.config/manga-downloader
docker run --rm -it -v "$PWD:/downloads" \
    -v ~/.config/manga-downloader:/home/manga/.config/manga-downloader \
    elboletaire/manga-downloader [url] [chapters]

Manga Plus also publishes one edition per language, and their chapter lists differ: some list the whole series, others only a handful of chapters. A URL points at one edition, and --language downloads another one instead (--language en on a Spanish URL downloads the English edition).

Run manga-downloader help to list them in your terminal.

Some sites cap the concurrency lower, because their image servers refuse requests that come too fast; a lower value still applies there. Pages refused for coming too fast (a 429) are retried after the wait the server asks for, up to a minute.

Other sites built on the same platforms often work too, even when they aren't listed. If one doesn't, open an issue or send a pull request.

A browser window pops up

This is expected for sites marked with *. The window opens when the site shows a Cloudflare challenge or a captcha of its own, and the terminal (or the app) tells you when it may need you. Checkboxes are clicked automatically, but some challenges need you to solve them yourself; the download carries on once the page loads. You rarely need to show the window from the start, but you can with --browser-visible or Show the browser window in the app.

The command line tool needs Go 1.19 or newer:

make install   # download dependencies
make build     # test and build ./manga-downloader

The desktop app is a Wails app: a Go program showing a React frontend in the system's webview. It needs Go 1.26 or newer (gui/go.mod), Node 22, pnpm 10, and on Linux the WebKitGTK 4.1 and GTK 3 development headers (libgtk-3-dev libwebkit2gtk-4.1-dev on Debian and Ubuntu):

make build/gui         # build ./manga-downloader-gui (frontend first)
make build/gui/windows # cross-build manga-downloader-gui.exe, no cgo needed