PyPI Installation¶

Install qBitrr directly from PyPI using pip. This method is ideal for users who prefer native installations or are already using Python for other tools.

Prerequisites¶

• Python 3.11 or higher (Download Python)
• pip (included with Python 3.4+)
• qBittorrent running and accessible
• At least one Arr instance (Radarr, Sonarr, or Lidarr)

Quick Start¶

# Install qBitrr
pip install qBitrr2

# Run qBitrr
qbitrr

# Install qBitrr
pip install qBitrr2

# Run qBitrr
qbitrr

# Create virtual environment
python3 -m venv qbitrr-env

# Activate it
source qbitrr-env/bin/activate  # Linux/macOS
# or
qbitrr-env\Scripts\activate  # Windows

# Install qBitrr
pip install qBitrr2

# Run qBitrr
qbitrr

Installation¶

Check Python Version¶

python3 --version

Make sure you have Python 3.11 or higher.

Install qBitrr¶

pip install qBitrr2

Install with Optional Dependencies¶

For faster JSON parsing:

pip install qBitrr2[fast]

For development dependencies:

pip install qBitrr2[dev]

For all optional dependencies:

pip install qBitrr2[all]

First Run¶

1. Start qBitrr:

   qbitrr
   

2. Configuration file created: qBitrr will generate ~/config/config.toml on first run

3. Stop qBitrr: Press Ctrl+C

4. Edit the configuration:

   nano ~/config/config.toml
   

Or open with your preferred editor.

1. Start qBitrr again:

   qbitrr
   

See the First Run Guide for detailed configuration steps.

Configuration¶

Config File Location¶

By default, qBitrr stores configuration in:

~/config/config.toml
~/logs/

%USERPROFILE%\config\config.toml
%USERPROFILE%\logs\

Custom Config Path¶

Set a custom config directory:

export QBITRR_CONFIG_PATH=/path/to/config
qbitrr

Or on Windows:

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

Running as a Service¶

Linux (systemd)¶

See the Systemd Service Guide for running qBitrr as a system service.

Windows¶

Use Task Scheduler to run qBitrr at startup:

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

Or use NSSM (Non-Sucking Service Manager):

# Install NSSM
choco install nssm

# Create service
nssm install qBitrr "C:\Python311\Scripts\qbitrr.exe"
nssm start qBitrr

macOS¶

Create a LaunchAgent:

1. 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/>
    <key>StandardOutPath</key>
    <string>/tmp/qbitrr.log</string>
    <key>StandardErrorPath</key>
    <string>/tmp/qbitrr.error.log</string>
</dict>
</plist>

1. Load the service:

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

Updating¶

Upgrade to Latest Version¶

pip install --upgrade qBitrr2

Upgrade with Auto-Update¶

qBitrr has a built-in auto-update feature:

1. Enable in config.toml:

   [Settings.CompletedDownloadFolder]
   AutoUpdate = true
   UpdateSchedule = "0 3 * * 0"  # Sunday at 3 AM
   

2. qBitrr will automatically update itself from PyPI

Uninstalling¶

pip uninstall qBitrr2

Your configuration files in ~/config/ will remain.

Troubleshooting¶

Command Not Found¶

If qbitrr command is not found after installation:

# Find where pip installs scripts
python3 -m site --user-base

# Add to PATH (add to ~/.bashrc or ~/.zshrc)
export PATH="$HOME/.local/bin:$PATH"

Permission Denied¶

On Linux/macOS, if you get permission errors:

# Install for current user only
pip install --user qBitrr2

Python Version Too Old¶

If your system Python is too old:

# Install a newer Python version
sudo apt install python3.12  # Ubuntu/Debian
brew install python@3.12     # macOS

# Use specific version
python3.12 -m pip install qBitrr2
python3.12 -m qBitrr.main

Virtual Environment Issues¶

If you have problems with system Python:

# Create fresh venv
python3 -m venv --clear qbitrr-env

# Activate and install
source qbitrr-env/bin/activate
pip install --upgrade pip
pip install qBitrr2

Import Errors¶

If you get import errors on startup:

# Reinstall with all dependencies
pip install --force-reinstall qBitrr2[all]

Development Installation¶

To install from source for development:

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

# Create virtual environment
python3 -m venv .venv
source .venv/bin/activate

# Install in development mode
pip install -e .[all]

# Run from source
python -m qBitrr.main

See the Development Guide for more details.

Advantages & Disadvantages¶

✅ Advantages¶

• Native performance (no containerization overhead)
• Easy integration with other Python tools
• Direct access to logs and config files
• Simple updates via pip
• Works on any platform with Python

❌ Disadvantages¶

• Requires Python 3.11+ installed
• Manual dependency management
• No built-in process management (need systemd/Task Scheduler)
• Path issues on some systems
• More complex multi-user setups

Next Steps¶

• Configure qBittorrent
• Configure Arr Instances
• Set up Systemd Service (Linux)
• First Run Guide