Installation

Installation

🌐 English · Deutsch

Requirements

Component	Requirement
Python	≥ 3.9
FFmpeg	Must be installed and available in PATH
Operating system	Windows, macOS, Linux (or Docker)

FFmpeg is mandatory — downloads will not work without it. On Windows the app downloads mpv.exe automatically when needed; FFmpeg can be installed e.g. via winget install Gyan.FFmpeg.

On first start the app also automatically downloads a Patchright Chromium browser. It is required for solving captchas (see Download System).

Warning

NAS devices (UGREEN, Synology): Both are supported, but MediaForge's code is not optimized for these two NAS platforms and will not be — so expect recurring issues. We're happy to help with installation, but we do not optimize MediaForge for UGREEN or Synology. For the smoothest experience, use Docker on a standard Linux, Windows or macOS host.

Installing Python

If python --version doesn't print 3.9 or newer, install Python first:

• Windows: winget install Python.Python.3.12 — or download from python.org and tick "Add python.exe to PATH" in the installer.
• macOS: brew install python (via Homebrew), or the installer from python.org.
• Linux: use your package manager, e.g. sudo apt install python3 python3-pip (Debian/Ubuntu), sudo dnf install python3 python3-pip (Fedora) or sudo pacman -S python python-pip (Arch).

Verify it:

python --version    # or: python3 --version
pip --version       # or: pip3 --version

On Windows, if python is "not found" right after installing, close and reopen the terminal so the updated PATH is loaded. On macOS/Linux you may need to use python3 / pip3.

Install via pip (recommended)

# Latest stable release
pip install mediaforge

# Update to the latest version
pip install --upgrade mediaforge

Development version (models branch)

pip install --upgrade "mediaforge @ git+https://github.com/PD-Codes/MediaForge.git@main"

Dev installs show a version like 2.5.3-dev+abc1234 in the UI (base version + commit hash). The built-in update checker compares the commit hash against the latest commit on the models branch for dev installs, and the version number against the latest GitHub release for release installs.

Launching

# Default: WebUI on http://localhost:8080, browser opens automatically
mediaforge

# Custom port
mediaforge -wP 9090

# Listen on all interfaces (LAN, Docker, reverse proxy)
mediaforge -wH 0.0.0.0

# Combined
mediaforge -wH 0.0.0.0 -wP 9090

All launch flags

Flag	Description
-wP / --web-port	Web UI port (default: 8080)
-wH / --web-host	Host/IP to bind (default: 127.0.0.1)
-wN / --no-browser	Don't open the browser automatically on startup
-d / --debug	Enable debug logging

That's all there is — every other setting is configured in the WebUI (Configuration).

Security note: If you bind to anything other than 127.0.0.1, the UI becomes reachable from the network. Authentication is enabled by default; still, never expose an instance unprotected to the internet (Authentication).

Docker

For container deployment see the dedicated Docker page.

Data directory

All configuration data, the SQLite database and helper files live under ~/.mediaforge/:

File	Purpose
mediaforge.db	SQLite database (settings, queue, users, …)
.flask_secret	Secret key for sessions & settings encryption
mediaforge.pid	Instance lock (warns on double start)
vapid_keys.json	Auto-generated Web Push keys
keyword_ids.json	TMDB keyword export (only with advanced search enabled)

Next step

→ Getting Started: setup token, admin account and your first download.