Manual Installation
Run Comicarr from source without Docker.
Advanced / development use
Docker is the recommended deployment method. Manual installation is intended for development or environments where Docker is unavailable.
Prerequisites
| Dependency | Minimum Version | Notes |
|---|---|---|
| Python | 3.10+ | |
| Node.js | 22+ | Frontend builds and raw Vite; the default npm run dev command needs 24+ |
| uv (or pip) | Latest | Recommended for Python deps |
| psycopg2-binary | any | Only if using PostgreSQL (uv sync --extra postgres) |
| mysqlclient / PyMySQL | any | Only if using MySQL |
Installation
Clone the repository
git clone https://github.com/frankieramirez/comicarr.git
cd comicarrInstall Python dependencies
Using uv (recommended, uses the committed uv.lock resolution):
uv syncOr create a virtual environment and install with pip. This resolves dependencies from pyproject.toml without using uv.lock:
python3 -m venv .venv
source .venv/bin/activate
pip install .On Windows, activate the environment with .venv\Scripts\activate instead.
Build the frontend
cd frontend
npm ci
npm run build
cd ..This compiles the React 19 frontend into static assets that Comicarr serves from frontend/dist.
Start Comicarr
source .venv/bin/activate
python3 Comicarr.py --nolaunchThe --nolaunch flag prevents Comicarr from automatically opening a browser window.
Access the UI
Open http://localhost:8090 in your browser and follow the Initial Setup guide.
Data Directory
By default, Comicarr stores its database, config, and logs in the application directory (the directory containing Comicarr.py). Override this with the --datadir flag:
python3 Comicarr.py --nolaunch --datadir /path/to/dataConfig and keys then live under /path/to/data/config.ini and /path/to/data/.secure/.
Development
For development with hot-reload on the frontend:
# Terminal 1: Activate the environment and start the backend (port 8090)
source .venv/bin/activate
python3 Comicarr.py --nolaunch
# Terminal 2: Start the frontend dev server (Node.js 24+)
cd frontend
npm run devOpen https://comicarr.localhost:1355. The default command uses portless; the first HTTPS session may require npx portless trust.
With Node.js 22, or when portless is unavailable, run npm run dev:vite from frontend and open http://localhost:5173. Node.js 22+ supports frontend builds and raw Vite; the locked portless dependency requires Node.js 24+.
Both development commands proxy API requests to http://localhost:8090. If the backend listens elsewhere, set VITE_API_PROXY_TARGET (for example http://localhost:8091) when starting the frontend.
See the project's CONTRIBUTING.md for full development setup instructions.