Migration Guide¶

This guide helps you migrate from older versions of qBitrr or similar tools to the latest version.

Upgrading qBitrr¶

Before You Upgrade¶

1. Backup your configuration:

   # Native
   cp ~/config/config.toml ~/config/config.toml.backup
   
   # Docker
   docker exec qbitrr cat /config/config.toml > config.toml.backup
   

2. Backup your database:

   # Native
   cp ~/config/qBitrr.db ~/config/qBitrr.db.backup
   
   # Docker
   docker cp qbitrr:/config/qBitrr.db qBitrr.db.backup
   

3. Review release notes:

4. Check CHANGELOG.md for breaking changes
5. Review GitHub Releases for version-specific notes

Version-Specific Migration¶

Migrating to v5.8.0+ (Database Consolidation)¶

What Changes¶

Before (v5.7.x and earlier):

~/config/qBitManager/
├── Radarr-4K.db
├── Radarr-1080.db
├── Sonarr-TV.db
├── Sonarr-4K.db
├── Lidarr.db
└── webui_activity.db

After (v5.8.0+):

~/config/qBitManager/
└── qbitrr.db  (single consolidated database)

Automatic Migration Process¶

When you upgrade to v5.8.0+:

1. New consolidated database is created
2. Single qbitrr.db file with ArrInstance field for data isolation

3. You'll see: Initialized single database: /config/qBitManager/qbitrr.db

4. Old data is cleaned up on first startup

5. Records without ArrInstance field are automatically removed
6. You'll see: Database migration: Removed X old records without ArrInstance. qBitrr will repopulate data from Arr instances.

7. This ensures data integrity and prevents mixing data between instances

8. Performance indexes are created

9. Indexes on ArrInstance field improve WebUI query performance

10. You'll see: Created index: idx_arrinstance_moviesfilesmodel on moviesfilesmodel.ArrInstance (×11)

11. Data is automatically re-synced from Arr instances

12. Takes 5-30 minutes depending on library size
13. Search history, queue state, and tracking data are rebuilt from Arr APIs
14. Each instance's data is properly tagged with its ArrInstance name
15. No manual intervention required

Benefits¶

• ✅ Single file backup instead of 9+ separate databases
• ✅ Simplified management (one VACUUM, one integrity check)
• ✅ Better performance (shared connection pool, reduced I/O, indexed queries)
• ✅ 78% less database code (easier maintenance)
• ✅ Proper data isolation (ArrInstance field prevents data mixing)
• ✅ Optimized WebUI queries (11 indexes on ArrInstance field)

No Action Required¶

The migration is fully automatic. Just update and restart qBitrr.

Migrating from v4.x to v5.x¶

Major Changes¶

• Config schema v3: Adds process auto-restart settings
• WebUI moved to separate section: [WebUI] replaces Settings.Host/Port/Token
• Quality profile mappings: Changed from list-based to dict-based

Automatic Migration¶

qBitrr automatically migrates your config on first run:

# Native
qbitrr

# Docker
docker-compose up qbitrr

You'll see:

Config schema upgrade needed (v2 -> v3)
Config backup created: /config/config.toml.backup_20250326_120000
Migrated WebUI Host from Settings to WebUI section
Migration v2→v3: Added process auto-restart configuration settings
Configuration has been updated with migrations and defaults.

Manual Migration (If Needed)¶

1. Move WebUI settings:

Old (v4.x):

[Settings]
Host = "0.0.0.0"
Port = 6969
Token = "mytoken"

New (v5.x):

[WebUI]
Host = "0.0.0.0"
Port = 6969
Token = "mytoken"
LiveArr = true
GroupSonarr = true
GroupLidarr = true
Theme = "Dark"

2. Update quality profile mappings:

Old (v4.x):

[Radarr-Movies.EntrySearch]
MainQualityProfile = ["Ultra-HD", "HD-1080p"]
TempQualityProfile = ["HD-1080p", "HDTV-720p"]

New (v5.x):

[Radarr-Movies.EntrySearch]
QualityProfileMappings = { "Ultra-HD" = "HD-1080p", "HD-1080p" = "HDTV-720p" }

3. Add process restart settings (optional):

[Settings]
AutoRestartProcesses = true
MaxProcessRestarts = 5
ProcessRestartWindow = 300
ProcessRestartDelay = 5

Migrating from v3.x to v4.x¶

Major Changes¶

• qBittorrent 5.x support: Automatic version detection (no config needed)
• Custom format enhancements: Better CF score handling
• Search optimizations: Smarter series vs. episode search

Steps¶

1. Review custom format settings:

[Radarr-Movies.EntrySearch]
CustomFormatUnmetSearch = false  # Enable if using TRaSH guides
ForceMinimumCustomFormat = false  # Enable for strict CF enforcement

1. Update Sonarr search mode:

[Sonarr-TV.EntrySearch]
SearchBySeries = "smart"  # New smart mode (recommended)

Migrating from v2.x to v3.x¶

Major Changes¶

• Multi-instance support: Better handling of multiple Arr instances
• Overseerr/Ombi integration: Request prioritization
• FFprobe auto-update: Automatic binary management

Steps¶

1. Update instance names:

Ensure all Arr instances follow naming convention:

# ✅ Correct
[Radarr-Movies]
[Sonarr-TV]
[Lidarr-Music]

# ❌ Incorrect (will be ignored)
[Movies]
[TV]

1. Configure FFprobe (now automatic):

[Settings]
FFprobeAutoUpdate = true  # Default, downloads ffprobe automatically

1. Add request integration (optional):

[Radarr-Movies.EntrySearch.Overseerr]
SearchOverseerrRequests = false
OverseerrURI = "http://localhost:5055"
OverseerrAPIKey = "your-api-key"
ApprovedOnly = true
Is4K = false

Migrating from Other Tools¶

From qBittorrent-Manager¶

qBittorrent-Manager users will find qBitrr familiar but with many enhancements.

Key Differences¶

Migration Steps¶

1. Install qBitrr:

2. Follow Installation Guide

3. Stop qBittorrent-Manager:

   systemctl stop qbittorrent-manager
   

4. Create qBitrr config:

   qbitrr --gen-config
   

5. Port configuration:

6. Copy Arr connection details
7. Copy qBittorrent connection details

8. Set categories to match Arr download clients

9. Test qBitrr:

   qbitrr
   

10. Disable qBittorrent-Manager:

    systemctl disable qbittorrent-manager
    

From Arr-Scripts¶

Users running custom Arr scripts can consolidate functionality into qBitrr.

qBitrr Replaces These Scripts¶

• ✅ Stalled torrent removal scripts
• ✅ Missing media search scripts
• ✅ Quality upgrade scripts
• ✅ Import trigger scripts
• ✅ Disk space monitoring scripts

Migration Steps¶

1. Identify script functionality:
2. List what each script does

3. Match to qBitrr features

4. Configure equivalent qBitrr settings:

Stalled removal script:

[Radarr-Movies.Torrent]
StalledDelay = 15
ReSearchStalled = true

Missing media script:

[Radarr-Movies.EntrySearch]
SearchMissing = true
SearchByYear = true
SearchAgainOnSearchCompletion = true

Upgrade script:

[Radarr-Movies.EntrySearch]
DoUpgradeSearch = true
QualityUnmetSearch = true
CustomFormatUnmetSearch = true

1. Test qBitrr:
2. Run in parallel with scripts initially
3. Verify qBitrr handles all functionality
4. Disable old scripts once confident

Docker Migration¶

From Docker Run to Docker Compose¶

Old (docker run):

docker run -d \
  --name qbitrr \
  -v /path/to/config:/config \
  -p 6969:6969 \
  feramance/qbitrr:latest

New (docker-compose.yml):

version: "3.8"
services:
  qbitrr:
    image: feramance/qbitrr:latest
    container_name: qbitrr
    volumes:
      - /path/to/config:/config
    ports:
      - "6969:6969"
    restart: unless-stopped

Migrate:

# Stop old container
docker stop qbitrr
docker rm qbitrr

# Start with compose
docker-compose up -d qbitrr

Changing Docker Networks¶

Scenario: Moving from bridge to custom network

Steps:

1. Update docker-compose.yml:

services:
  qbitrr:
    image: feramance/qbitrr:latest
    networks:
      - mediastack  # Add custom network

networks:
  mediastack:
    external: true  # Or create here

1. Update config.toml:

[qBit]
Host = "qbittorrent"  # Use container name, not IP

[Radarr-Movies]
URI = "http://radarr:7878"  # Use container name

1. Recreate container:

docker-compose down qbitrr
docker-compose up -d qbitrr

Configuration Consolidation¶

Multiple Config Files to Single File¶

If you had split configs (one per Arr instance), consolidate to one config.toml:

Old structure:

config/
├── radarr.toml
├── sonarr.toml
├── lidarr.toml
└── settings.toml

New structure:

config/
└── config.toml  # Single file

Consolidation:

# Combine all sections into one file

[Settings]
# Global settings

[qBit]
# qBittorrent settings

[Radarr-Movies]
# Radarr instance 1

[Radarr-4K]
# Radarr instance 2

[Sonarr-TV]
# Sonarr instance

[Lidarr-Music]
# Lidarr instance

Testing Your Migration¶

Verification Checklist¶

After migrating, verify:

• qBittorrent connection:
• Open WebUI → Processes tab

• Check qBittorrent status: ✅ Connected

• Arr connections:

• WebUI → Radarr/Sonarr/Lidarr tabs

• Verify each shows "Connected"

• Torrent monitoring:

• Add a test download in Arr
• Verify qBitrr processes it

• Check logs for activity

• Search automation:

• Add a missing movie/show
• Wait for search cycle

• Check logs for search activity

• WebUI access:

• Open http://localhost:6969
• Verify all tabs load

• Check real-time updates work

• Logs:

• Review logs for errors
• Look for migration messages
• Verify expected operations

Test Commands¶

# Check qBitrr is running
ps aux | grep qbitrr  # Native
docker ps | grep qbitrr  # Docker

# View logs
tail -f ~/logs/Main.log  # Native
docker logs -f qbitrr  # Docker

# Test API
curl http://localhost:6969/api/health

# Test qBittorrent connection
curl http://localhost:6969/api/qbittorrent/status

Rollback Procedure¶

If migration fails or causes issues:

Native Rollback¶

# Stop qBitrr
killall qbitrr

# Restore config
cp ~/config/config.toml.backup ~/config/config.toml

# Restore database
cp ~/config/qBitrr.db.backup ~/config/qBitrr.db

# Downgrade qBitrr
pip install qBitrr2==4.5.0  # Replace with desired version

# Restart
qbitrr

Docker Rollback¶

# Stop container
docker-compose down qbitrr

# Restore config
docker cp config.toml.backup qbitrr:/config/config.toml

# Use older image
docker pull feramance/qbitrr:4.5.0

docker-compose.yml:

services:
  qbitrr:
    image: feramance/qbitrr:4.5.0  # Pin to old version

# Start with old version
docker-compose up -d qbitrr

Getting Help¶

If you encounter issues during migration:

1. Check logs for errors:

   # Enable debug logging
   ConsoleLevel = "DEBUG"
   

2. Review migration messages:

3. Look for "Config schema upgrade needed"
4. Check for backup file creation

5. Note any migration warnings

6. Compare configs:

   diff config.toml.backup config.toml
   

7. Ask for help:

8. GitHub Discussions
9. GitHub Issues
10. Include:
    • Old version number
    • New version number
    • Migration error messages
    • Relevant log excerpts

Related Documentation¶

• Installation Guide
• First Run Configuration
• Configuration Overview
• Troubleshooting