Direct Installation

v0.10.0

Trailarr supports native direct installation on Linux, macOS, and Windows — no Docker required. The only prerequisite is uv, a fast Python package manager that also manages Python versions.

Step 1 — Install uv

curl -LsSf https://astral.sh/uv/install.sh | sh

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Step 2 — Install Trailarr

curl -LsSf https://raw.githubusercontent.com/nandyalu/trailarr/main/install.sh | sudo sh

Set-ExecutionPolicy Bypass -Scope Process -Force
irm https://raw.githubusercontent.com/nandyalu/trailarr/main/install.ps1 | iex

The installer will:

1. Download the latest release (includes pre-built web interface) and verify its checksum
2. Set up an isolated Python environment with uv sync
3. Download the correct ffmpeg static binary for your OS and CPU architecture
4. Automatically select an available port starting from 7889
5. Create and start a system service (systemd / launchd / Task Scheduler)
6. Detect GPU hardware and display driver installation instructions

# Linux / macOS
curl -LsSf https://raw.githubusercontent.com/nandyalu/trailarr/main/install.sh | sudo TRAILARR_VERSION=v0.9.9 sh

# Windows (before running the installer)
$env:TRAILARR_VERSION = 'v0.9.9'

Directory Structure

/opt/trailarr/              # Application
├── backend/                # Python source + .venv/
├── frontend-build/         # Web interface
├── bin/                    # ffmpeg, ffprobe
└── scripts/                # start.py, cli/

/var/lib/trailarr/          # Data (persists across updates)
├── trailarr.db             # SQLite database
├── .env                    # Configuration
├── backups/                # Automatic DB backups (30 kept)
├── logs/                   # Application logs
└── web/images/             # Downloaded images

/etc/systemd/system/trailarr.service

/usr/local/opt/trailarr/    # Application
├── backend/                # Python source + .venv/
├── frontend-build/         # Web interface
├── bin/                    # ffmpeg, ffprobe
└── scripts/                # start.py, cli/

~/.local/share/trailarr/    # Data (persists across updates)
├── trailarr.db
├── .env
├── backups/
├── logs/
└── web/images/

~/Library/LaunchAgents/com.trailarr.app.plist

C:\Program Files\Trailarr\  # Application
├── backend\                # Python source + .venv\
├── frontend-build\         # Web interface
├── bin\                    # ffmpeg.exe, ffprobe.exe
└── scripts\                # start.py, cli\

C:\ProgramData\Trailarr\    # Data (persists across updates)
├── trailarr.db
├── .env
├── backups\
├── logs\
└── web\images\

Task Scheduler task: "Trailarr"

Service Management

Use the trailarr CLI that is installed automatically:

trailarr run             # Start the service
trailarr stop            # Stop the service
trailarr restart         # Restart the service
trailarr status          # Show current status
trailarr logs            # Show last 50 log lines
trailarr logs 200        # Show last 200 log lines
trailarr version         # Show installed and latest versions
trailarr update          # Update to the latest version
trailarr update vX.Y.Z   # Install a specific version
trailarr update --force  # Reinstall even if already up to date
trailarr uninstall       # Remove Trailarr

You can also use OS-native tools directly:

sudo systemctl start trailarr
sudo systemctl stop trailarr
sudo systemctl status trailarr
sudo journalctl -u trailarr -f          # Follow live logs

launchctl kickstart gui/$(id -u)/com.trailarr.app   # Start
launchctl bootout gui/$(id -u)/com.trailarr.app     # Stop
launchctl print gui/$(id -u)/com.trailarr.app       # Status
tail -f ~/Library/Logs/trailarr/trailarr.log

launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.trailarr.app.plist

Start-ScheduledTask -TaskName 'Trailarr'
Stop-ScheduledTask -TaskName 'Trailarr'
(Get-ScheduledTask -TaskName 'Trailarr').State
Get-Content "C:\ProgramData\Trailarr\logs\trailarr.log" -Tail 50 -Wait

GPU Hardware Acceleration

At the end of installation, Trailarr detects your GPU hardware and displays the exact commands needed to install drivers. Drivers are not installed automatically — you review and run the commands yourself.

After installing drivers, restart Trailarr and enable hardware acceleration in Settings → Video Processing.

Supported acceleration

Common driver commands

# Ubuntu / Debian
sudo apt install nvidia-driver-535

# Fedora
sudo dnf install akmod-nvidia

# Arch
sudo pacman -S nvidia

# Ubuntu / Debian
sudo apt install intel-media-va-driver intel-media-va-driver-non-free libva-drm2

# Fedora
sudo dnf install intel-media-driver libva

# Arch
sudo pacman -S intel-media-driver libva

# Ubuntu / Debian
sudo apt install mesa-va-drivers libva-drm2

# Fedora
sudo dnf install mesa-va-drivers libva

# Arch
sudo pacman -S mesa libva

Configuration

All settings can be changed from the Trailarr web interface after installation. The configuration file is at:

Updating

trailarr version           # Check for updates without installing anything
trailarr update            # Update to the latest release
trailarr update vX.Y.Z     # Install a specific version
trailarr update --force    # Reinstall even if already up to date

An update will:

1. Check the target release — if you are already on it, nothing is changed
2. Stop the service
3. Back up your database and .env to the backups/ folder
4. Download the release and verify its checksum
5. Swap in the new application files and run uv sync to update Python dependencies
6. Restart the service

If any step fails, the previous version is automatically restored and the service restarted — a failed update never leaves a broken install. Your data directory is never modified during an update.

Uninstalling

trailarr uninstall

You will be asked to confirm before anything is removed, and separately asked whether to also delete your data directory (database, backups, config). This removes the application, service, and CLI.

Troubleshooting

Service won't start

# Linux
sudo journalctl -u trailarr -n 100

# macOS
cat ~/Library/Logs/trailarr/trailarr.log

# Windows (PowerShell)
Get-Content "C:\ProgramData\Trailarr\logs\trailarr.log" -Tail 100

Common causes: port already in use, database corruption, missing uv or ffmpeg.

Port conflict

Edit the .env file and change APP_PORT, then restart the service.

# Check what's on port 7889
# Linux / macOS
lsof -i :7889
# Windows
netstat -ano | findstr :7889

Permission errors (Linux)

sudo chown -R trailarr:trailarr /opt/trailarr /var/lib/trailarr

GPU acceleration not working

Verify drivers are installed and detected at startup:

# NVIDIA
nvidia-smi

# Intel / AMD (Linux)
vainfo

# Check Trailarr logs for "GPU detected" lines
trailarr logs 100

Then confirm hardware acceleration is enabled in Settings → Video Processing.

Comparison: Direct vs Docker

Choose direct installation when you need full GPU hardware access, run in an environment where Docker GPU passthrough is difficult (e.g., Proxmox LXC), or simply prefer a native system service.