Binary Installation¶

Download and run pre-built qBitrr binaries for Linux, macOS, or Windows. No Python installation required!

Prerequisites¶

• 64-bit operating system (Linux, macOS, or Windows)
• qBittorrent running and accessible
• At least one Arr instance (Radarr, Sonarr, or Lidarr)

Download¶

Latest Release¶

Visit the GitHub Releases page and download the binary for your platform:

Command Line Download¶

# Download latest release
curl -L -o qbitrr https://github.com/Feramance/qBitrr/releases/latest/download/qbitrr-linux-x64

# Make executable
chmod +x qbitrr

# Run
./qbitrr

# Download latest release
curl -L -o qbitrr https://github.com/Feramance/qBitrr/releases/latest/download/qbitrr-macos-x64

# Make executable
chmod +x qbitrr

# Run (you may need to allow in Security settings)
./qbitrr

# Download with PowerShell
Invoke-WebRequest -Uri https://github.com/Feramance/qBitrr/releases/latest/download/qbitrr-windows-x64.exe -OutFile qbitrr.exe

# Run
.\qbitrr.exe

Installation¶

Linux¶

1. Download and install:

   sudo curl -L -o /usr/local/bin/qbitrr \
     https://github.com/Feramance/qBitrr/releases/latest/download/qbitrr-linux-x64
   
   sudo chmod +x /usr/local/bin/qbitrr
   

2. Run:

   qbitrr
   

macOS¶

1. Download:

   curl -L -o ~/Downloads/qbitrr \
     https://github.com/Feramance/qBitrr/releases/latest/download/qbitrr-macos-x64
   
   chmod +x ~/Downloads/qbitrr
   

2. Move to Applications (optional):

   sudo mv ~/Downloads/qbitrr /usr/local/bin/
   

3. First run (security prompt):

   ./qbitrr
   

If macOS blocks it: - Go to System Preferences → Security & Privacy - Click "Allow Anyway" next to the qbitrr message - Run again

Windows¶

1. Download qbitrr-windows-x64.exe from releases

2. Move to a permanent location:

   C:\Program Files\qBitrr\qbitrr.exe
   

3. Run:

4. Double-click qbitrr.exe

5. Or run from PowerShell: .\qbitrr.exe

6. Add to PATH (optional):

7. Search for "Environment Variables"
8. Edit "Path" system variable
9. Add C:\Program Files\qBitrr

First Run¶

1. Start qBitrr:

   ./qbitrr  # or qbitrr.exe on Windows
   

2. Configuration file created:

Binary installations use these default paths:

=== "Linux/macOS"

~/.config/qbitrr/config.toml
~/.local/share/qbitrr/logs/

=== "Windows"

%APPDATA%\qbitrr\config.toml
%APPDATA%\qbitrr\logs\

1. Stop qBitrr: Press Ctrl+C

2. Edit configuration: See First Run Guide

3. Start again:

   ./qbitrr
   

Configuration Location¶

Custom Config Path¶

Set a custom config directory:

export QBITRR_CONFIG_PATH=/path/to/config
./qbitrr

$env:QBITRR_CONFIG_PATH = "C:\path\to\config"
.\qbitrr.exe

Running as a Service¶

Linux (systemd)¶

Create /etc/systemd/system/qbitrr.service:

[Unit]
Description=qBitrr
After=network.target

[Service]
Type=simple
User=your-user
ExecStart=/usr/local/bin/qbitrr
Restart=always

[Install]
WantedBy=multi-user.target

Enable and start:

sudo systemctl daemon-reload
sudo systemctl enable --now qbitrr

Windows¶

Use Task Scheduler:

1. Open Task Scheduler
2. Create Basic Task
3. Name: "qBitrr"
4. Trigger: "When the computer starts"
5. Action: "Start a program"
6. Program: C:\Program Files\qBitrr\qbitrr.exe
7. Finish

Or use NSSM:

nssm install qBitrr "C:\Program Files\qBitrr\qbitrr.exe"
nssm start qBitrr

macOS (LaunchAgent)¶

Create ~/Library/LaunchAgents/com.qbitrr.plist:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.qbitrr</string>
    <key>ProgramArguments</key>
    <array>
        <string>/usr/local/bin/qbitrr</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
</dict>
</plist>

Load:

launchctl load ~/Library/LaunchAgents/com.qbitrr.plist

Updating¶

Binary installations do not support auto-update. You must manually download and replace the binary.

Linux/macOS¶

# Backup current binary
sudo mv /usr/local/bin/qbitrr /usr/local/bin/qbitrr.bak

# Download latest
sudo curl -L -o /usr/local/bin/qbitrr \
  https://github.com/Feramance/qBitrr/releases/latest/download/qbitrr-linux-x64

sudo chmod +x /usr/local/bin/qbitrr

# Restart service
sudo systemctl restart qbitrr  # if using systemd

Windows¶

1. Stop qBitrr (or the service)
2. Download new qbitrr-windows-x64.exe
3. Replace old file
4. Start qBitrr again

Troubleshooting¶

Binary Won't Run¶

ldd ./qbitrr

# Remove quarantine flag
xattr -d com.apple.quarantine ./qbitrr

Permission Denied¶

chmod +x qbitrr

Config File Not Found¶

Check config location:

./qbitrr --show-config-path

Create config directory manually:

mkdir -p ~/.config/qbitrr

New-Item -ItemType Directory -Path "$env:APPDATA\qbitrr"

Large Binary Size¶

Binary files are 50-100MB because they include: - Python interpreter - All Python dependencies - Compiled libraries

This is normal for PyInstaller binaries.

Advantages & Disadvantages¶

✅ Advantages¶

• No Python installation required
• Single file distribution
• Easy to deploy
• Consistent across systems
• No dependency conflicts

❌ Disadvantages¶

• Large file size (50-100MB)
• No auto-update support
• Manual updates required
• May trigger antivirus warnings
• Slower startup than native Python

Building from Source¶

To build your own binary:

# Clone repository
git clone https://github.com/Feramance/qBitrr.git
cd qBitrr

# Install dependencies
pip install pyinstaller
pip install -e .[all]

# Build
pyinstaller build.spec

# Binary in dist/
ls dist/

See the Development Guide for more details.

Next Steps¶

• First Run Guide
• Configure qBittorrent
• Configure Arr Instances
• Troubleshooting