Documentation (readme)

AIO Webtoon & Light Novel Downloader 📚

Important

May 2026 update: cross-site search, multi-source fallback, source-quality ranking, stricter chapter recovery, expanded site handlers, tests, and the Electron desktop app have been integrated.

The most versatile, feature-rich & customizable tool to download webtoons (manhwa), manga, comics and light novels from mangataro.org, mangafire.to, asuracomic.net, weebcentral.com, manganato.gg, comix.to & many others, and package them into PDF, EPUB, CBZ, or raw chapter bundles—available as a command-line tool, the original Tkinter graphical interface (gui.py), and a full Electron desktop app under UI-source/. Features include light-novel aware text handling, intelligent image processing, resumable downloads, parallel batch downloading, library auto-update, cross-site search, multi-source fallback, image-quality source ranking, scanlation group prioritization, and optional chapter/file-size splitting.

Follow me on 𝕏

📑 Table of Contents

• 🚀 Features
• 🛠️ Requirements
• 🌐 Supported Sites
• 🧰 Installation
• 🚀 Usage
• 🔌 REST API
• 🔎 Cross-Site Search
• 🌉 Multi-Source Mode
• 🖥️ Desktop UI
• ⚙️ Options
• 🔐 Cookie Setup
• 📖 Examples
• 💡 Tips & Tricks
• 📁 Output Structure
• ⚖️ Disclaimer
• 🤝 Contributing
• 🙏 Acknowledgements
• 📄 License

---

🚀 Features

• 💻 Command-Line Interface Full-featured CLI with extensive options—scriptable, automation-friendly, and composable with shell workflows.
• 🖥️ Graphical User Interface Launch gui.py for a full Tkinter GUI—manage downloads, browse your library, track chapter counts & file sizes, and trigger updates—without touching the command line.
• 🖥️ Electron Desktop App Use the React/Vite/Tailwind app under UI-source/ for Download, Search, Queue, Logs, Library, and Settings workflows, with packaging scripts for Windows, macOS, and Linux.
• 🔎 Cross-Site Search Search across search-capable handlers with --search, fuzzy title scoring via rapidfuzz, quality-seed ranking, language filtering, and JSON output for automation or UI integrations.
• 🌉 Multi-Source Fallback Pair --multi-source with direct URLs or --search --auto-pick to pre-fetch alternative chapter lists and transparently fall back per chapter when the primary source is missing, hollowed out, or failing.
• 🏛️ Official-Publisher Detection MangaDex official-publisher metadata is recognized and used during chapter merging so licensed/official releases are surfaced correctly.
• 📥 Flexible Chapter Selection Download specific chapters, ranges (1-5), lists (1,3,5-7), or open-ended ranges (-10 for up to ch 10, 5- for ch 5 onwards).
• ⚡ Parallel Batch Downloads Pass multiple URLs at once or use --jobs N to download several series concurrently across coordinated worker processes. Workers share a polite request pacing layer to avoid hammering sites.
• 🔁 Library Auto-Update Use --save-params once to record your download settings per series. Later, run --update-all to automatically fetch new chapters for every tracked series in your library—no need to remember flags or URLs.
• 🏷️ Scanlation Group Control Prioritize your favorite scanlation group(s), or choose by highest upvotes.
• 🖼️ Smart Page Processing Resize, scale, recombine, and compress image chapters. Webtoon strips stay continuous; page-style scans keep their page layout.
• 🚫 No-Processing Mode Package raw pages as-is into PDF/EPUB/CBZ (skip all resizing/recombining/scaling) via --no-processing.
• 📁 Multiple Formats Export as PDF, fixed-layout EPUB, vertical-scroll EPUB, or CBZ.
• 📚 Light-Novel Friendly Detects prose chapters automatically—EPUB embeds true XHTML pages, PDF outputs selectable text, CBZ renders text blocks as images, and --format none saves plain .txt chapters.
• 🧼 Clean Chapter Content Automatically strips Mangataro boilerplate (group avatars, site banners, copyright notices) so only true page content lands in your book.
• 📊 Image-Quality Source Ranking Curated quality priors in sites/quality_seed.json help search and multi-source fallback prefer visually stronger sources when title matches are close.
• 🛡️ Hardened Rate Limiting Per-domain request throttling with configurable gaps (page, AJAX, image), Cloudflare challenge detection, and exponential backoff with jitter—shared across parallel workers via file locks.
• ⚡ Parallel Image Downloads --image-workers controls per-chapter image concurrency, while --prefetch-image-workers can download chapter N+1 while chapter N is being encoded.
• 🔄 Resumable Downloads Automatically picks up where it left off if interrupted.
• 🎯 Per-Chapter Strict Mode Missing-page detection, chapter deadlines, host-poison thresholds, and inline chapter retries prevent silently incomplete chapters from landing in final books.
• 🩹 Missed Chapter Retry After a run completes, automatically retries any chapters that failed to download or process, with configurable retry count (--missed-retries).
• ✂️ Book Splitting Split large downloads by file size (e.g., 400MB) or chapter count (e.g., 10ch).
• 💾 Keep Originals Optionally retain raw images and per-chapter files.
• 🧪 Regression Tests Pytest coverage now includes chapter merging, search orchestration, and key site handlers under tests/.

---

🛠️ Requirements

• Python
  • Officially supported: 3.8+
  • Best-effort (tested): 3.7 (may require building Pillow from source on some platforms)
  • Not supported: 3.6 and Python 2.x
• OS: macOS, Linux, Windows
• Node.js 20+ (only for the Electron desktop UI)
• Python packages (installed via requirements.txt)
  • beautifulsoup4
  • cloudscraper
  • lxml
  • Pillow
  • pypdf
  • requests
  • fastapi / uvicorn — REST API server
  • impit — Chrome/Firefox TLS impersonation for bot-protected sites (handles zstd/brotli)
  • zendriver — Cloudflare Managed Challenge solver for CF-protected sites
  • patchright — Playwright-compatible browser automation for MangaFire VRF generation and site probes (python -m patchright install chromium after pip install)
  • rapidfuzz — cross-site title matching
  • pywidevine / cryptography — Kagane DRM support
  • curl_cffi — MangaFire fast image-download path with HTTP/2 + Chrome-like TLS fingerprints
• Notes for macOS (Apple Silicon), Python 3.7 only:
  • Building Pillow from source may require system libraries. If you see build errors, install via Homebrew:
    • brew install jpeg-turbo libpng freetype libtiff webp little-cms2 zlib
  • Ensure Xcode command line tools are installed: xcode-select --install

Feature support by Python version

• Legend:
  • ✅ Supported
  • ⚠️ Supported with caveats (see notes)
  • ❌ Not supported

Notes:

• Cloudscraper is optional. If it’s not available or fails to initialize, the downloader automatically falls back to requests.Session.
• The HTML parser prefers lxml if installed, and falls back to the built-in html.parser.
• Search and multi-source mode require rapidfuzz; browser automation paths require Python 3.8+ in practice.
• On macOS (Apple Silicon), Python 3.7 may need system libraries to build Pillow.

---

🧰 Installation

CLI

git clone https://github.com/zzyil/AIO-Webtoon-Downloader.git
cd AIO-Webtoon-Downloader
python3 -m pip install -r requirements.txt
python3 -m patchright install chromium    # one-time, for MangaFire/search probes

Development/test dependencies:

python3 -m pip install -r requirements-dev.txt

Desktop UI (Electron)

cd UI-source
npm install
npm run electron:dev       # development mode with hot reload

Build installers:

npm run dist:win           # Windows NSIS installer
npm run dist:mac           # macOS DMG/ZIP
npm run dist:linux         # Linux AppImage

The electron:build and dist:* scripts run scripts/prepare-src.js, bundle the Python backend as Electron extraResources, and write installers under UI-source/release/.

---

🌐 Supported Sites

For all supported sites, check docs/SUPPORTED_SITES.MD

---

🚀 Usage

Command-line:

python3 aio-dl.py [OPTIONS] COMIC_URL [COMIC_URL ...]

Graphical interface:

python3 gui.py

Electron desktop UI:

cd UI-source
npm run electron:dev

Cross-site search with automatic fallback:

python3 aio-dl.py --search "Witch Hat Atelier" --auto-pick --multi-source

List chapters as JSON without downloading:

python3 aio-dl.py --list-chapters "https://awesome-webtoon.url/series/name"

Run python3 aio-dl.py --help for the full option list.

---

🔌 REST API

The downloader includes a FastAPI-based REST backend (api.py) allowing you to interact with supported sites programmatically to retrieve metadata, active chapters, and image contents. (Thanks to @norphiil for the REST API implementation!).

Start the API Server:

uvicorn api:app --host 0.0.0.0 --port 8000
# or:
python3 aio-dl.py --serve --api-host 0.0.0.0 --api-port 8000

Available Endpoints:

• GET /api/handlers
  List all supported site handlers and their corresponding domains.
• GET /api/info?url=URL[&site=NAME]
  Fetch comic metadata (title, author, cover image, status).
• GET /api/chapters?url=URL[&site=NAME][&language=en]
  Retrieve a JSON list of available chapters for a comic.
• GET /api/chapter_images?url=URL&chapter_id=ID[&site=NAME]
  Get the exact image URLs for a specific chapter ID.
• GET /api/download_image?url=IMG_URL
  Downloads an image behind site protections and returns a local cache URL (/api/temp/...) for safe consumption.

Note: Cross-Origin Resource Sharing (CORS) is enabled by default for all origins, and intermediate images older than 1 hour are auto-purged from the temp directory.

---

🔎 Cross-Site Search

Use --search "<title>" to query search-capable handlers, score title matches with rapidfuzz, and return ranked JSON candidates with source site, URL, language, match score, and image-quality prior.

python3 aio-dl.py --search "Witch Hat Atelier"

Add --auto-pick to continue into the normal download pipeline with the top-ranked result:

python3 aio-dl.py --search "Witch Hat Atelier" --auto-pick --format epub

Useful search flags:

---

🌉 Multi-Source Mode

Some sources have incomplete catalogs, regional gaps, DMCA removals, or intermittent CDN failures. --multi-source pre-fetches alternative chapter lists, aligns them through sites/chapter_merger.py, and falls back per chapter when the primary source fails.

python3 aio-dl.py --search "Witch Hat Atelier" --auto-pick --multi-source

You can also use it with a direct URL:

python3 aio-dl.py --multi-source "https://mangadex.org/title/..."

Useful multi-source flags:

---

🖥️ Desktop UI

The original Tkinter GUI remains available as python3 gui.py. The merged desktop app adds a full Electron + React + Vite + Tailwind interface under UI-source/.

cd UI-source
npm install
npm run electron:dev

Electron tabs:

• Download — single URL or paste-multiple download setup.
• Search — cross-site search results with score, source rank, and coverage information.
• Queue — running and queued jobs with pause/resume/cancel controls.
• Logs — per-job stdout/stderr streaming from aio-dl.py.
• Library — manage downloaded books on disk.
• Settings — Python interpreter, default paths, group preferences, and theme.

Installer builds use npm run dist:win, npm run dist:mac, or npm run dist:linux, and output to UI-source/release/.

---

⚙️ Options

---

🔐 Cookie Setup

If authentication is required, export your cookies as a single quoted string:

export COOKIES='session_token=…; another_cookie=…'

Then run:

python3 aio-dl.py --site mangataro --cookies "$COOKIES" \
  "https://awesome-webtoon.url/series/name"

---

📖 Examples

1. Find and download via cross-site search with fallback enabled:

   python3 aio-dl.py \
     --search "Witch Hat Atelier" \
     --auto-pick \
     --multi-source \
     --format epub \
     --epub-layout page \
     --quality 92
   

2. Page-layout EPUB, chapters 1–2, preferred group Asura, verbose:

   python3 aio-dl.py \
     --group Asura \
     --chapters "1-2" \
     --format epub \
     --epub-layout page \
     --verbose \
     "https://awesome-webtoon.url/series/name"
   

3. Vertical EPUB, chapters 1–20, split every 5 chapters, verbose & debug:

   python3 aio-dl.py \
     --chapters "1-20" \
     --format epub \
     --epub-layout vertical \
     --split 5ch \
     --verbose --debug \
     "https://awesome-webtoon.url/series/name"
   

4. PDF, chapters 1–2, combined into one file:

   python3 aio-dl.py \
     --chapters "1-2" \
     --format pdf \
     "https://awesome-webtoon.url/series/name"
   

5. CBZ, chapters 1–2, one chapter per file:

   python3 aio-dl.py \
     --chapters "1-2" \
     --format cbz \
     --keep-chapters \
     "https://awesome-webtoon.url/series/name"
   

6. PDF, chapters 1–2, save each chapter separately:

   python3 aio-dl.py \
     --chapters "1-2" \
     --format pdf \
     --keep-chapters \
     "https://awesome-webtoon.url/series/name"
   

7. Page-layout EPUB, chapters 1–5:

   python3 aio-dl.py \
     --chapters "1-5" \
     --format epub \
     --epub-layout page \
     "https://awesome-webtoon.url/series/name"
   

8. Raw CBZ (pages copied as-is):

   python3 aio-dl.py \
     --chapters "1-50" \
     --format cbz \
     --no-processing \
     "https://awesome-webtoon.url/series/name"
   

9. Batch download 3 series at once with 2 parallel workers:

   python3 aio-dl.py \
     --jobs 2 \
     --format epub \
     --save-params \
     "https://site.com/series/alpha" \
     "https://site.com/series/beta" \
     "https://site.com/series/gamma"
   

10. Auto-update all previously saved series (fetch only new chapters):

python3 aio-dl.py --update-all --jobs 2

11. Open-ended range — download from chapter 50 to the latest:

    python3 aio-dl.py \
      --chapters "50-" \
      --format epub \
      "https://awesome-webtoon.url/series/name"
    

12. List chapters as JSON without downloading:

    python3 aio-dl.py --list-chapters "https://awesome-webtoon.url/series/name"
    

---

💡 Tips & Tricks

Here are some handy pointers to get the most out of your workflow:

• 🖥️ GUI for Everything • Run python3 gui.py to open the graphical interface—download, monitor progress, browse your library, and trigger updates without the command line. • Run npm run electron:dev inside UI-source/ for the newer desktop app with Search, Queue, Logs, Library, and Settings tabs.

• 🔎 Search Before Downloading • Use --search "Series Title" when you are not sure which site has the best source. • Add --auto-pick --multi-source to let the downloader pick the strongest match and pre-fetch alternatives before downloading.

• 🌉 DMCA or Missing Chapter Recovery • Use --multi-source for hollowed-out catalogs. The downloader compares chapter lists across sites and falls back per chapter when the primary source is missing content or fails.

• 🔁 Ongoing Series Auto-Update • Download with --save-params once: python3 aio-dl.py --save-params --format epub "https://...". • Later, run python3 aio-dl.py --update-all (optionally with --jobs N) to fetch new chapters for every tracked series automatically.

• ⚡ Parallel Batch Downloads • Provide multiple URLs and set --jobs 2 (or more) to download several series at the same time. • Workers share a coordinated pacing layer—no extra configuration needed for polite multi-site behavior. • For image-level parallelism, tune --image-workers; if a CDN starts throwing 5xx storms, lower it or set --prefetch-image-workers 0.

• 🔄 Ongoing Series Updates (manual) • Use --no-cleanup to keep your temporary data around and reuse the same settings. • Run again whenever new chapters appear, only new content will be downloaded & processed. • You can use --restore-parameters to restore input parameters to exactly match the previous one.

• 🗂️ Archiving Originals
  • Add --keep-images to save every raw page under manga/<Title>/Chapter_<n>/. • Useful if you want to re-process images later (different layout, quality, etc.).

• 🧾 Raw Packaging (No Processing)
  • Use --no-processing to package pages exactly as downloaded into CBZ/EPUB/PDF.
  • Skips resize/recombine/scaling; great if you prefer untouched originals inside the final file.
  • Combine with --keep-chapters to generate one raw file per chapter.

• 📑 Precise Chapter Selection
  • Use --chapters "1-20,21,23-100" to include exactly the chapters you want (skip fillers or extras).
  • Supports single numbers, ranges, and comma-separated lists.
  • Use --no-partials to skip fractional chapters such as 1.5, 30.1 or other non decimal exclusive chapters in order to prevent duplicates within your final export.

• ⚙️ Recover from Failures
  • After a crash or network hiccup, rerun with --restore-parameters, which will restore all parameters except for your desired file format. (Please remember that PDFs don't adhere to aspect ratios the same way as EPUBs & CBZs do, so going from pdf to either of them isn't recommended, the other way around works fine.)

• 🍏 Apple Books Friendly
  • Apple Books can choke on massive EPUBs— personal recommendation: split into ~10-chapter chunks: --split 10ch.
  • Alternatively, split by size: --split 200MB.

• 📖 EPUB Layout Recommendations
  • For standard e-readers (Kindle, Kobo): --epub-layout page.
  • For continuous scroll (Apple Books, PocketBook): --epub-layout vertical.

• 🎨 Control Output Quality & Size
  • --quality 60 to drop JPEG quality for smaller files.
  • --scaling 80 to downscale pages to 80% of the original processed size.
  • Combine with --split to keep individual file sizes manageable.

• 🏷️ Best Scanlation Version
  • --group "YourFavGroup" to prefer that scanlation team, or use --group "YourFavGroup1, YourFavGroup2" to allow several teams in priority order. If a chapter is missing from those groups, the downloader falls back to the highest-upvoted available release and reports it at the end by default.
  • Add --mix-by-upvote to pick the highest-upvoted release among the groups you allowed for that chapter. • Add --no-group-fallback if you want strict group-only downloads and would rather skip missing chapters.

• 🔍 Debugging & Verbose Logs
  • -v / --verbose for step-by-step progress.
  • -d / --debug for deep image-processing insights (resizing, recombining).

• 📦 Per-Chapter Files
  • Use --keep-chapters to save each chapter as its own PDF/EPUB/CBZ alongside the main book. • Add --no-final-file if you only want those per-chapter files and do not want a combined book.

---

📁 Output Structure

• Temporary Data: tmp_<hid>/ (or <temp-dir>/tmp_<hid>/ if --temp-dir is set)
  • run_params.json: Stores the processing settings for resume functionality.
• Final Files: <output-dir>/ (default: manga/)
  • Named <Title>[_Groups]_Ch_<start>-<end>.<format> (e.g., My_Awesome_Comic_Asura_Ch_1-5.epub)
• Series tracking (if --save-params is used):
  • <output-dir>/<Title>/download_params.json — saved settings for --update-all
  • <output-dir>/<Title>/.series_hid — internal marker used to avoid folder collisions in parallel runs
• Raw Images (if --keep-images is used):
  • <output-dir>/<Title>/Chapter_<n>/

tmp_<hid>/                              # Temporary workspace
└── run_params.json                     # Saved settings (resume/restore)
manga/
├── <Title>[_Groups]_Ch_a-b.epub/pdf/cbz   # Final build(s)
├── <Title>/
│   ├── download_params.json            # Saved params (--save-params)
│   ├── .series_hid                     # Internal folder marker
│   └── Chapter_<n>/                    # Raw images (--keep-images)
└── .aio_coord/                         # Cross-process coordination (--jobs)

• Final files → manga/ (override with -o/--output-dir)
• Use --no-cleanup to inspect tmp_<hid>/ after completion
• Re-run with --restore-parameters + new --format to reassemble without re-downloading

---

⚖️ Disclaimer

This tool is provided strictly for educational purposes and to help you create personal, offline backups of manga to which you have legal access. Many supported sites are unauthorized aggregators of licensed content; MangaDex official-publisher detection helps surface licensed English releases when metadata is available. Please respect the rights of content creators and publishers—unauthorized sharing, piracy, or redistribution of material is prohibited.

---

🤝 Contributing

1. Fork the repo
2. Create a feature branch (git checkout -b feature/foo)
3. Test your update (where possible)
   • macOS (Apple Silicon): test_scripts/python_version_tester.sh automatically spins up per-version virtualenvs after installing missing python@X.Y formulae via Homebrew (pyenv is optional but supported).
   • Otherwise: run targeted unit/download tests that exercise your change (python3 -m pytest tests/ when dev dependencies are installed).
   • For new site handlers, add or update focused tests under tests/ where practical.
4. Commit (git commit -m "Add foo")
5. Push (git push origin feature/foo)
6. Open a Pull Request

Please follow the existing style and include tests where applicable. New handlers should be registered in sites/__init__.py; if they support title search, implement search() so they join cross-site discovery and multi-source fallback.

---

📖 Changelog

Full changelog: docs/CHANGELOG.md

05.24.26

May 2026 integration:

• Integrated the Electron desktop UI, cross-site search, multi-source fallback, image-quality ranking, official-publisher metadata, expanded site handlers, regression tests, and packaging/release tooling.

🙏 Acknowledgements

This project stands on the shoulders of many wonderful open-source tools and libraries—thank you to all the maintainers and contributors who make these possible, thank you:

• Python (CPython) – The language powering this script
• requests (psf/requests) – HTTP for Humans
• cloudscraper (VeNoMouS/cloudscraper) – Seamless Cloudflare anti-bot bypass
• Beautiful Soup (BeautifulSoup) – HTML/XML parsing made easy
• lxml (lxml/lxml) – Fast, feature-rich XML/HTML processing
• Pillow (python-pillow/Pillow) – The friendly PIL fork for image manipulation
• pypdf (py-pdf/pypdf) – PDF generation and manipulation
• FastAPI (fastapi/fastapi) – REST API backend
• impit – Chrome/Firefox TLS fingerprint impersonation; handles zstd/brotli compression without launching a browser
• zendriver – CDP-based Chrome automation with built-in Cloudflare challenge solving
• Patchright / Playwright (microsoft/playwright-python) – Browser automation for MangaFire VRF generation and site probes
• rapidfuzz (rapidfuzz/RapidFuzz) – Fast fuzzy matching for cross-site search
• curl_cffi (lexiforest/curl_cffi) – HTTP/2 + browser-like TLS fingerprints for fast image paths
• pywidevine (devine-dl/pywidevine) – Widevine DRM support for Kagane
• Electron (electron/electron) – Desktop app shell
• React (facebook/react), Vite (vitejs/vite), Tailwind CSS (tailwindlabs/tailwindcss), and lucide-react (lucide-icons/lucide) – Electron renderer stack

---

📄 License

This project is licensed under the GNU GPLv3.

---