Installation

This guide covers the two methods for installing the Manhwa OCR Tool. For the best stability, performance, and access to the latest updates, we strongly recommend running the application directly from its source code.

Method Best For Difficulty
1. From Source Code All users. The most stable and reliable method for running the app. Medium
2. Via Executable File Quick testing only. This version is experimental and may be unstable. Easy

1. From Source Code (Recommended Method)

This method ensures you have the correct dependencies for your system and gives you immediate access to the latest updates and bug fixes.

Prerequisites

Before proceeding, ensure you have Python and Git installed on your system.

A. Install Python (3.8+ Recommended)

  1. Download: Go to the official Python website: python.org/downloads/
  2. Run Installer: Launch the installer.
  3. Important (Windows): On the first page of the installer, you must check the box labeled "Add Python to PATH" or "Add python.exe to PATH". This step is crucial for running Python from the command line. Add Python to PATH checkbox
  4. Complete the installation using the default settings.

B. Install Git

Git is required to download (clone) the application's source code from its repository.

  1. Download: Go to the official Git website: git-scm.com/downloads
  2. Run Installer: Launch the installer and proceed with the default recommended settings.

Installation Steps

The following steps should be performed in a command-line interface (e.g., Terminal on macOS/Linux or Command Prompt (CMD) / PowerShell on Windows).

Step 1: Create a Folder and Download the Code

First, create a dedicated folder for the tool and download the source code into it.

  1. Create and Navigate to a Project Folder:

    mkdir manhwa-ocr-tool
cd manhwa-ocr-tool

  2. Download (Clone) the Application Repository: This command uses Git to download the source code into your current folder.

    # Note the space and dot " ." at the end.
git clone https://github.com/kha-white/manhwa-ocr-tool.git .
For Advanced Users: Using a Virtual Environment (Optional)

If you are a developer and prefer to keep project dependencies isolated, you can create and activate a virtual environment after running cd manhwa-ocr-tool and before installing PyTorch.

# Create the virtual environment
# On Windows: python -m venv venv
# On macOS/Linux: python3 -m venv venv

# Activate it (must be done each time you open a new terminal)
# On Windows: .\venv\Scripts\activate
# On macOS/Linux: source venv/bin/activate

A (venv) prefix will appear in your terminal prompt when it's active. All subsequent pip install commands will apply only to this environment.

Step 2: Install PyTorch (Crucial First Step)

The OCR engine relies on PyTorch, which must be installed separately before other dependencies to ensure hardware compatibility (especially for NVIDIA GPU/CUDA acceleration).

  1. Go to the Official PyTorch Website: Navigate to pytorch.org.
  2. Use the Install Helper: Use the configuration tool on the homepage to select the appropriate options for your system (e.g., Stable, OS, Pip, CUDA version or CPU).
  3. Copy and Run the Command: The website will generate a specific pip install command. Copy and run this command in your terminal.

Example Command (Do NOT blindly copy this!) The generated command for a system with CUDA 12.1 might look like this. Your command will likely be different. Always use the command generated by the official PyTorch website.

pip3 install torch torchvision --index-url https://download.pytorch.org/whl/cu121

Step 3: Install Other Dependencies

Install the remaining required Python libraries from the requirements.txt file.

# On Windows
pip install -r requirements.txt

# On macOS or Linux
pip3 install -r requirements.txt

Step 4: Run the Application

Launch the tool from your terminal. Make sure you are still inside the manhwa-ocr-tool directory.

# On Windows
python main.py

# On macOS or Linux
python3 main.py

2. Via Executable (Alpha / Unstable)

Warning: Pre-compiled executables are currently in an alpha stage. They are intended for testing only and may be broken, lack features, or experience critical errors. For a stable experience, please use the "From Source Code" method above.

  1. Download: Go to the project's official GitHub Releases Page and download the latest package for your operating system.
  2. Install:
    • Windows: Run the .exe installer or extract the portable .zip file and run the executable inside.
    • macOS: Open the .dmg file and drag the application icon into your "Applications" folder.

Common Installation Issues

command not found (e.g., git, python, pip)

This error typically indicates one of two problems:

  1. The program (Git or Python) is not installed. Please review the Prerequisites section.
  2. (Windows) The program was not added to your system's PATH variable during installation. For Python, the easiest solution is to uninstall and reinstall it, ensuring the "Add Python to PATH" checkbox is selected.

GUI Library Conflict (PyQt5 vs. PySide6)

The application is built with PySide6. If the conflicting PyQt5 library is installed on your system, the application may fail to launch. The tool is designed to detect this issue and display a detailed error message with a "Copy Commands" button.

If you encounter this, follow the on-screen instructions or see our Troubleshooting Guide for a step-by-step solution.