Installation

Get Universal Novel Scraper installed on Windows, macOS, or Linux

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

   Windows

   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.

   macOS

   1. Open the downloaded .dmg file
   2. Drag the UNS icon to your Applications folder
   3. Launch UNS from Launchpad or Applications

   macOS may block the app because it’s not from an identified developer. Go to System Settings → Privacy & Security and click “Open Anyway”.

   Linux

   For AppImage:

   chmod +x UNS-*.AppImage
   ./UNS-*.AppImage
   

   For Debian/Ubuntu (.deb):

   sudo dpkg -i uns_*.deb
   sudo apt-get install -f  # Install dependencies if needed
   
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 higher

Download from nodejs.org

Python

Version 3.11 or higher

Download from python.org

macOS Apple Silicon Requirements

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

   npm install
   

   Then install frontend-specific dependencies:

   cd frontend
   npm install
   cd ..
   
3. Setup Python Backend

   Create a virtual environment and install Python dependencies:

   macOS/Linux

   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.

   Make the engine executable (macOS/Linux)

   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

Engine Not Starting (macOS)

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.

PyInstaller Import Errors

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

Port 8000 Already in Use

If another application is using port 8000, the engine won’t start. Find and stop the conflicting process:

macOS/Linux

lsof -i :8000
kill -9 <PID>

Electron Window Doesn't Appear

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:

Windows

C:\Users\<YourName>\AppData\Roaming\UNS\
├── output/
│   ├── epubs/          # Downloaded EPUB files
│   ├── jobs/           # Temporary chapter data
│   └── history/        # Download history
└── providers/          # Custom provider scripts

macOS

~/Library/Application Support/UNS/
├── output/
│   ├── epubs/          # Downloaded EPUB files
│   ├── jobs/           # Temporary chapter data
│   └── history/        # Download history
└── providers/          # Custom provider scripts

Linux

~/.config/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