Skip to main content

​
Prerequisites

Before installing Universal Manga Downloader, ensure your system meets these requirements:
Python 3.10 or higher is required. Check your version with python --version or python3 --version.
  • Python 3.10+ with pip installed
  • Git for cloning the repository
  • 8GB RAM recommended for browser automation
  • 500MB disk space for dependencies and browser binaries

​
System compatibility

  • Windows 10/11
  • macOS 10.15+
  • Linux (Ubuntu 20.04+, Debian 11+, or equivalent)

​
Installation steps

1

Clone the repository

Download the source code from GitHub:
git clone https://github.com/Holkeano526/MangaDownloader.git
cd MangaDownloader
The repository is approximately 50MB. The clone operation may take 1-2 minutes depending on your connection speed.
2

Install Python dependencies

Install all required packages using pip:
pip install -r requirements.txt
This will install the following core dependencies:
  • discord.py - Discord bot integration
  • aiohttp - Async HTTP client
  • Pillow - Image processing
  • playwright - Browser automation
  • crawl4ai - Intelligent web scraping
  • python-dotenv - Environment variable management
  • img2pdf - PDF generation
  • fastapi - Web API framework
  • uvicorn - ASGI server
  • websockets - Real-time communication
If you encounter permission errors on Linux/macOS, try using pip3 instead of pip, or add --user flag: pip install --user -r requirements.txt
3

Install Playwright browsers

Playwright requires browser binaries for automation. Install Chromium:
playwright install chromium
This downloads and configures the Chromium browser (~300MB). The process may take several minutes.
To save bandwidth and disk space, install only Chromium. The downloader doesn’t require Firefox or WebKit.
If you need all browsers for development:
playwright install
4

Configure environment variables

Create a .env file in the project root directory:
touch .env
Add your configuration:
.env
# Optional: Discord bot token (only needed for bot.py)
DISCORD_TOKEN=your_discord_token_here

# Optional: Run Playwright in headless mode (default: false)
HEADLESS=true

# Optional: Google API key (if needed by specific handlers)
GOOGLE_API_KEY=your_google_api_key
The DISCORD_TOKEN is only required if you plan to use the Discord bot deployment method. For web and desktop usage, you can leave the .env file empty or skip this step.
Configuration options explained:
  • DISCORD_TOKEN - Your Discord bot token from the Discord Developer Portal
  • HEADLESS=true - Runs browser automation invisibly (recommended for servers)
  • HEADLESS=false - Shows browser window during scraping (useful for debugging)
  • GOOGLE_API_KEY - Optional API key for enhanced features
5

Verify installation

Test that all components are properly installed:
python --version
# Expected output: Python 3.10.x or higher
Run a quick health check:
python -c "import core; print('Core module loaded successfully')"
Expected output:
Core module loaded successfully
If you see ModuleNotFoundError, ensure you’re in the correct directory and all dependencies were installed successfully. Try running pip install -r requirements.txt again.

​
Directory structure

After installation, your project directory should look like this: 
MangaDownloader/
├── .env                    # Your environment configuration
├── requirements.txt        # Python dependencies
├── core/                   # Core engine package
│   ├── sites/             # Site-specific handlers
│   ├── config.py          # Configuration management
│   ├── handler.py         # Main routing logic
│   └── utils.py           # Utility functions
├── web_client_next/       # Next.js frontend
├── app.py                 # Desktop GUI application
├── bot.py                 # Discord bot
├── web_server.py          # FastAPI backend
└── PDF/                   # Output directory (auto-created)
The PDF/ directory will be automatically created when you download your first manga. This is where all generated PDFs are stored.

​
Optional: Install Node.js dependencies

If you plan to use or develop the web interface, install the Next.js dependencies:
1

Ensure Node.js is installed

The web interface requires Node.js 18+ and npm:
node --version  # Should be v18.0.0 or higher
npm --version
If not installed, download from nodejs.org.
2

Install frontend dependencies

Navigate to the web client directory and install:
cd web_client_next
npm install
cd ..
The START_WEB_VERSION.bat launcher will automatically handle frontend setup on Windows. Manual installation is only needed for development or Linux/macOS deployment.

​
Troubleshooting

​
Python not found

If you see python: command not found, try using python3 instead: 
python3 --version
python3 -m pip install -r requirements.txt

​
Permission errors on Linux/macOS

Add --user flag to install in your home directory: 
pip install --user -r requirements.txt
playwright install chromium

​
Playwright installation fails

If Playwright installation fails, try installing system dependencies first: 
sudo apt-get update
sudo apt-get install -y libglib2.0-0 libnss3 libnspr4 libdbus-1-3 \
  libatk1.0-0 libatk-bridge2.0-0 libcups2 libdrm2 libxkbcommon0 \
  libxcomposite1 libxdamage1 libxfixes3 libxrandr2 libgbm1 libpango-1.0-0 \
  libcairo2 libasound2
Then retry: 
playwright install chromium

​
Import errors

If you see ModuleNotFoundError: No module named 'core', ensure you’re running commands from the project root directory: 
cd MangaDownloader  # Ensure you're in the right directory
pwd                 # Should show path ending in /MangaDownloader
python app.py       # Now run your command

​
crawl4ai installation issues

If crawl4ai fails to install, you may need to install build tools: 
sudo apt-get install build-essential python3-dev

​
Next steps

Now that you have Universal Manga Downloader installed, you’re ready to download your first manga!

Quick start

Download your first manga in 5 minutes

Web deployment

Set up the modern web interface

Desktop app

Launch the standalone GUI

Core concepts

Learn about the architecture

Build docs developers (and LLMs) love

Get started for freeTalk to us