mangapy is a command-line downloader for FanFox and MangaDex. Download one chapter, a range, the latest chapter, or an entire series—with one PDF per chapter when you want a portable archive.

[!IMPORTANT] You need Python 3.14 or newer when installing from PyPI. The Homebrew formula installs its Python dependency for you.

Highlights

Supported providers

[!NOTE] fanfox is the default provider. MangaDex-specific filters are available in YAML mode.

Getting started

Install with pipx

pipx installs mangapy in an isolated environment while making the command available globally:

pipx install mangapy

Install with Homebrew

On macOS:

brew install alemar11/tap/mangapy

Confirm the installation:

mangapy --version
mangapy --help

CLI examples

The shortest command downloads the latest available chapter from FanFox as images into ~/Downloads/mangapy:

mangapy title bleach

Choose chapters

Chapter ranges are inclusive. Open-ended ranges are supported too:

# Chapter 85 and every available chapter after it
mangapy title "tower of god" --chapter 85-

[!TIP] Quote titles containing spaces. Run mangapy title --help for the complete command reference.

Control retries and progress

Disable network retries for benchmarking or fail-fast workflows:

mangapy title bleach --chapter 1 --no-retry

Disable the progress display for scripts and compact logs:

mangapy title bleach --chapter 1 --no-progress

Force a fresh download of the selected chapters while preserving the current files until each replacement has downloaded successfully:

mangapy title bleach --chapter 1 --force

Set NO_COLOR to disable terminal colors while keeping progress output enabled:

NO_COLOR=1 mangapy title bleach --chapter 1

Use a proxy

Pass a JSON object with both http and https entries. Each URL must include its scheme; the proxy is used for provider requests and chapter images.

mangapy title "one piece" \
  --out ~/Downloads \
  --proxy '{"http":"http://proxy.example:8080","https":"http://proxy.example:8080"}'

[!CAUTION] Treat proxy credentials as secrets. Avoid putting authenticated proxy URLs in shell history, shared YAML files, screenshots, or logs.

YAML mode

YAML mode is useful for repeatable downloads across multiple titles and providers:

mangapy yaml path/to/downloads.yaml

---
debug: false
force: false
no_retry: false
no_progress: false
output: "~/Downloads/mangapy"

downloads:
  - source: fanfox
    title: bleach
    pdf: true
    download_single_chapter: "10"

  - source: fanfox
    title: naruto
    download_chapters: "10-13"

  - source: mangadex
    title: blue lock
    translated_language: [en]
    content_rating: [safe, suggestive, erotica]
    data_saver: false
    download_all_chapters: true

Global settings act as defaults. A download entry can override debug, force, no_retry, no_progress, output, and proxy for that title.

Chapter selectors

Use at most one selector per download entry:

MangaDex options

These fields are valid only when source: mangadex:

[!NOTE] MangaDex output names include the immutable chapter UUID. This prevents corrected metadata, translations, and scanlations from overwriting one another. Legacy number-only outputs are kept but are not reused because they do not identify a translation.

More ready-to-run configurations are available in samples/. To run one directly from a source checkout:

uv run python3 scripts/dev_run.py sample.yaml

Configuration

Output layout

Downloads are organized by provider and manga beneath the selected output directory. Image mode stores page files under an images directory; PDF mode creates one PDF per chapter.

Mangapy owns each completed chapter image directory. After a successful image download, stale regular files in that chapter directory are removed so the local pages match the provider response.

Exit codes

Development setup

Install mise and clone the repository:

git clone https://github.com/alemar11/mangapy.git
cd mangapy
mise install
mise run setup

mise install provides the required Python 3.14 and uv. mise run setup creates the project-local .venv and installs the application and development dependencies.

Verify the checkout:

mise run lint
mise run test
uv run mangapy --help

The default test command excludes live provider tests because they contact third-party services and may be affected by site changes or rate limits.

When opening the repository in VS Code, accept the recommended Python, Python Environments, Python Debugger, and Ruff extensions. Select .venv as the Python interpreter if VS Code does not detect it automatically.

See Development for the complete editor workflow and Tests for live-provider and targeted test commands.

License

Distributed under the MIT License.