Skip to main content
Universal Novel Scraper (UNS) is a cross-platform desktop application that lets you download web novels and convert them into EPUB books. This guide will walk you through installing UNS on your system.

​
Download Pre-Built Application

The easiest way to get started is to download the latest release for your platform:

Windows

Download the .exe installer

macOS

Download the .dmg disk image

Linux

Download the .AppImage or .deb package
1

Visit the Releases Page

Navigate to the UNS GitHub Releases page and download the installer for your operating system.
2

Install the Application

  1. Run the downloaded .exe file
  2. Follow the installation wizard
  3. Launch UNS from your Start Menu or Desktop shortcut
Windows may show a SmartScreen warning for unsigned applications. Click “More info” then “Run anyway” to proceed.
3

First Launch

When you first open UNS, the application will:
  • Start the Python backend engine automatically
  • Create necessary directories in your user data folder
  • Initialize the library database
You should see the main interface with the Download Manager ready to use.

​
Building from Source

If you want to contribute to development or customize UNS, you can build it from source.

​
Prerequisites

Before building UNS, ensure you have the following installed:

Node.js

Version 18 or higherDownload from nodejs.org

Python

Version 3.11 or higherDownload from python.org
If you’re on macOS with Apple Silicon (M1/M2/M3), install Xcode Command Line Tools:
xcode-select --install
This provides necessary build tools for native dependencies.

​
Clone the Repository

1

Clone the source code

git clone https://github.com/OsamaTab/UNS.git
cd UNS
2

Install Frontend Dependencies

Install Electron and React dependencies:
npm install
Then install frontend-specific dependencies:
cd frontend
npm install
cd ..
3

Setup Python Backend

Create a virtual environment and install Python dependencies:
cd backend
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
The backend uses these key dependencies:
  • FastAPI - REST API framework
  • uvicorn - ASGI server
  • ebooklib - EPUB generation
  • botasaurus - Web scraping utilities
4

Build the Python Engine

The Python backend must be compiled into a standalone executable:
cd backend
python -m PyInstaller \
  --onefile \
  --windowed \
  --name engine \
  api.py
On Windows, the output will be backend/dist/engine.exe. On macOS/Linux, it’s backend/dist/engine.
chmod +x backend/dist/engine
5

Run in Development Mode

Start the application in development mode:
npm run dev
This will:
  1. Start the Vite development server for React (port 5173)
  2. Launch Electron with hot-reload enabled
  3. Automatically start the Python engine backend (port 8000)

​
Build Production Executable

To create a distributable application: 
npm run build
This command:
  1. Builds the React frontend with Vite
  2. Packages everything with electron-builder
  3. Creates platform-specific installers in dist_electron/
The build process automatically includes the Python engine from backend/dist/ into the final package.

​
Troubleshooting

If the Python engine fails to start, it may not have execute permissions:
chmod +x ./backend/dist/engine
If the issue persists, check Console.app for error messages related to code signing.
Ensure PyInstaller is executed inside the activated virtual environment:
source backend/venv/bin/activate  # or venv\Scripts\activate on Windows
python -m PyInstaller --version   # Verify it's installed in venv
If you still get import errors, try:
pip install --upgrade pyinstaller
pip install --force-reinstall fastapi uvicorn ebooklib
If another application is using port 8000, the engine won’t start. Find and stop the conflicting process:
lsof -i :8000
kill -9 <PID>
Check the terminal output for errors. Common issues:
  • Frontend not built: Run cd frontend && npm run build
  • Vite dev server not ready: Wait a few seconds after starting npm run dev
  • Hardware acceleration issues: Try launching with: 
    npm start -- --disable-gpu

​
File Storage Locations

UNS stores your data in platform-specific user directories: 
C:\Users\<YourName>\AppData\Roaming\UNS\
├── output/
│   ├── epubs/          # Downloaded EPUB files
│   ├── jobs/           # Temporary chapter data
│   └── history/        # Download history
└── providers/          # Custom provider scripts
You can open the output folder directly from the Library page using the “Open Folder” button.

​
Next Steps

Quick Start Guide

Learn how to download your first novel

Provider System

Install additional website scrapers

Build docs developers (and LLMs) love

Get started for freeTalk to us