mangadex-dl-gui

A web interface for mangadex-downloader, styled after Sonarr/Radarr. It runs in Docker and has no authentication of its own: put it behind an authenticating reverse proxy and never expose it directly to the internet.

Disclaimer: This is an unofficial project. It is not affiliated with, endorsed by or connected to MangaDex or the author of mangadex-downloader. It is meant for personal use only. You are responsible for complying with the MangaDex terms of service and with copyright law in your country.

Features

• Library: your manga as posters (or a table) with a download progress bar, like series in Sonarr
• Import: manga that are already in the download directory are found, matched to MangaDex by their folder name (you can correct the match) and added to the library; downloaded chapters are recognised from the file names
• Manga page: all chapters grouped by volume with status (downloaded / queued / missing), monitor volumes or single chapters (like in Sonarr), download a single chapter, a whole volume, a selection or everything that is missing and monitored
• Add: search MangaDex by title (or paste a URL), pick a result, choose what to monitor (all, future, missing, existing, recent, first/latest volume, none) and the basic options (save as, language, order, …); "Show advanced options" as in Sonarr
• Activity: Queue with status, progress bar and current phase (live updates every 2 s) and History with retry/remove
• Settings: defaults for the options plus the number of parallel downloads, default monitoring mode, refresh and backup intervals; only the common options (save as, language, order, sort by, log level) are shown until "Show advanced" is switched on
• System (like Sonarr): Status (health checks, disk space, versions), Tasks (library refresh every 6 h, weekly backup, run now), Backup (create, download, restore), Events and Log files (one per download)
• Detail view of every download with live log and the exact command that was executed
• Title, cover, author and chapter list come from the public MangaDex API (display only)
• The queue survives restarts, interrupted downloads are re-queued

Quick start

git clone <repository-url>
cd mangadex-dl-gui
docker compose up -d --build
# → http://localhost:8080

Downloads and configuration end up in ./downloads and ./config. The image runs on x86 and ARM (e.g. Apple Silicon).

To use a published image instead of building it, set image: <registry>/<owner>/mangadex-dl-gui:latest in compose.yaml:

services:
  mangadex-dl-gui:
    image: <registry>/<owner>/mangadex-dl-gui:latest
    restart: unless-stopped
    environment:
      TZ: Europe/Berlin
      PUID: 1000
      PGID: 1000
    volumes:
      - ./config:/config
      - ./downloads:/downloads
    ports:
      - "8080:8080"

Configuration

Container path	Content
/downloads	downloaded manga
/config	series.json (library), jobs.json, settings.json, events.jsonl, backups/, logs, mangadex-dl home

Variable	Default	Meaning
DOWNLOAD_DIR	/downloads	target folder of the downloads
CONFIG_DIR	/config	queue, settings, logs
PUID / PGID	1000 / 1000	user and group the app runs as
TZ	–	timezone, e.g. Europe/Berlin

The container starts as root, fixes the permissions on /config and then switches to PUID:PGID. PUID:PGID needs write access to /downloads (only its top level is adjusted). If the container is started as non-root instead (user: in Compose), the app runs directly under that UID and the folders must already have the right permissions.

Notes

• Only URLs on mangadex.org are accepted.
• By default every manga is saved in its own folder named after its title (/downloads/<title>/), which is the default value {manga.title} for the subfolder. If mangadex-downloader creates a title folder itself, the app collapses the duplicate level after the download.
• A custom subfolder ("Files & Paths") is relative to /downloads and replaces the default; for placeholders see Path placeholders.
• Progress is parsed from the console output of mangadex-downloader. With the progress bar layout none (under "Output & Misc") there is no percentage anymore, only log lines. The parsing has not been verified against every version of the real tool.
• New options can be added in app/options.py; the frontend builds its forms from it automatically.
• Logging in to MangaDex is deliberately not part of the interface.

Development

pip install -r requirements.txt
DOWNLOAD_DIR=./downloads CONFIG_DIR=./config uvicorn app.main:app --port 8080

The backend is a single FastAPI app (app/main.py), the frontend is plain HTML/JS/CSS in app/static/ without a build step.

Image and CI

The workflow build.yaml is written for Forgejo Actions (it also works with Gitea). On every push to main it builds the image and publishes it to the container registry of the Forgejo instance:

<forgejo-domain>/<owner>/<repo>:latest
<forgejo-domain>/<owner>/<repo>:<YYYY.MM.N>

It also creates a tag and a Forgejo release in the scheme YYYY.MM.N. Work happens on develop, main is fast-forwarded.

Requirements (one-time):

• A runner with the label docker and a BuildKit daemon that the job containers can reach. The workflow builds with docker buildx (driver remote), so neither the Docker socket nor a socket proxy is needed. The daemon address defaults to tcp://buildkit:1234 and can be changed with the repository variable BUILDKIT_ADDR
• Repository secrets REGISTRY_USER and REGISTRY_TOKEN (token with write:package). Without them the workflow falls back to the workflow token
• After the first push, link the package to this repository in the package settings
• The registry (/v2/) must be reachable without an authentication proxy in front of it, otherwise docker login, push and pull fail

The image is built for linux/amd64 only. To build for another platform locally, use docker compose build or docker buildx build --platform ….

License

MIT. mangadex-downloader (MIT) and other dependencies are not part of this repository, see THIRD-PARTY-NOTICES.md.