menu_book Documentation

Getting Started

Install Mangasurf and its curl_cffi HTTP engine, then run your first download.

fact_checkPrerequisitesdownloadInstallverifiedVerifyplay_circleLaunchboltQuick Start
Mangasurf v1.7.5 · 38 Sources

fact_checkPrerequisites

Mangasurf runs on Python 3.11 or newer. If you install from source you also need git, and for the full desktop experience PyQt6 and pywebview.

downloadInstall

info Mangasurf's HTTP engine is 100% curl_cffi — the requests package is not used at all. curl_cffi ships prebuilt wheels for CPython 3.8–3.13 on Linux, macOS and Windows, so there's normally no compiler needed.

# 1. The native HTTP binding
pip install curl_cffi

# 2. The rest of the project
git clone https://github.com/Compromisee/Mangasurf.git
cd Mangasurf
pip install -r requirements.txt

Or install the published package with extras:

pip install "mangasurf[all]"      # GUI + TUI + tray + servers
pip install "mangasurf[gui]"      # desktop app only

verifiedVerify the engine

python -c "from mangasurf import http; print(http.get('https://cloudflare.com', timeout=10).status_code)"

This prints 200 even on Cloudflare-fronted pages, because curl_cffi sends a genuine browser TLS/JA3+JA4 fingerprint (impersonate="chrome" by default).

play_circleLaunch

window

Desktop GUI

python gui.py — the PyQt6 app with the Foliate reader.

widgets

Launcher

python launcher.py — pick your interface.

lan

LAN / Server

python server.py — drive it from your phone.

menu_book

OPDS Catalog

python opdsserve.py — stream to e-readers.

boltQuick start

# Free-text search across every enabled source
mangasurf "solo leveling"

# Target a specific source
mangasurf "@kagane solo leveling"
mangasurf "mangakatana: naruto"

# Download a whole manga (or paste a series URL)
mangasurf --url "https://mangadex.org/title/<uuid>" --format cbz --selection all

See the landing page or the SYNTAX.md CLI reference for the full command grammar.