DOCSEARCHbyAlgolia
Submit Docs

qBitrr

repository·master·Indexed 41 days ago

https://github.com/feramance/qbitrr

An intelligent automation tool that acts as the glue between qBittorrent and the *Arr ecosystem (Radarr, Sonarr, Lidarr, Readarr). It automates torrent health monitoring, quality upgrades, disk space management, and request integration.

Tokens
190.9K
Snippets
539
Records
790
Agent score
51%

What's inside qBitrr

  1. Access the qBitrr WebUI API

    master

    The qBitrr WebUI REST API is accessible via the built-in WebUI server, which defaults to port 6969.

    Base URL

    http://<host>:6969 (Default: http://localhost:6969)

    Endpoint Patterns

    qBitrr provides two patterns for most endpoints. They return the same JSON data, but are intended for different use cases:

    PatternPurposeTypical UseAuthentication
    /api/*API-first endpointsExternal scripts, automation, CLI toolsRequires Bearer Token or session cookie
    /web/*First-party endpointsReact WebUI, same-origin browser toolsRequires session cookie

    Recommendation: Use /api/* for scripts and /web/* for the bundled WebUI.

    http://localhost:6969

  2. Access the qBitrr WebUI and API documentation

    master

    The qBitrr WebUI is a React-based interface for monitoring processes, browsing media from Arr instances, and managing configuration.

    • Default WebUI Access: http://localhost:6969/ui
    • Interactive API Documentation (Swagger/OpenAPI): Accessible at /web/docs or /api/docs.
    • Machine-readable OpenAPI spec: Available at /web/openapi.json.

    Note: If authentication is enabled, you must log in or provide a Bearer token to access the documentation.

    http://localhost:6969/ui

  3. WebUI Tech Stack and Project Structure

    master

    The WebUI is a React-based application built with the following technologies:

    Core Technologies:

    • React 18 & TypeScript
    • Vite (Build tool/HMR)
    • Mantine v8 (UI Component library)
    • fetch API (via src/api/client.ts)
    • urlBase helper (prefixes API paths via src/api/urlBase.ts when WebUI.UrlBase is set)

    State Management:

    • SearchContext: Search state
    • ToastContext: Notifications
    • WebUIContext: Settings

    Project Structure:

    • src/api/: API client, types, and URL helpers.
    • src/components/: Reusable UI components.
    • src/context/: Global state providers.
    • src/hooks/: Custom React hooks.
    • src/pages/: Route-level components (Dashboard, Processes, Logs, etc.).
    • src/utils/: Helper functions.

  4. Navigate the qBitrr WebUI

    master

    The WebUI uses a tab-based navigation system to manage your media stack. The main tabs include:

    • Processes: Process management and control.
    • Logs: Live log viewer with filtering.
    • Radarr/Sonarr/Lidarr: Library views for movies, TV series, and music (requires corresponding instances to be configured).
    • qBittorrent: Overview of monitored-category torrents.
    • Config: Configuration editor.
    • API: API documentation and testing.

    Interface Elements:

    • Header Bar: Contains the Logo (returns to Processes), Theme Toggle (Dark/Light/Auto), Refresh Indicator, Connection Status, and Version Badge.
    • Footer Bar: Displays Status Messages, Active Processes count, and the Last Update timestamp.

  5. Overview of configuration sections

    master

    The config.toml file is organized into the following functional sections:

    1. [Settings]: Global qBitrr settings.
    2. [WebUI]: Configuration for the web interface.
    3. [qBit] or [qBit-<name>]: Connection settings for qBittorrent. If no qBit section is present, qBittorrent functionality is disabled.
    4. [Sonarr-<name>]: Configuration for Sonarr instances.
    5. [Radarr-<name>]: Configuration for Radarr instances.
    6. [Lidarr-<name>]: Configuration for Lidarr instances.

  6. Overview of qBitrr database structure

    master

    qBitrr uses a single consolidated SQLite database to maintain persistent state across restarts. It utilizes SQLite's WAL (Write-Ahead Logging) mode for improved concurrency and crash resilience. This mode generates two additional temporary files alongside the main database.

    Database Files:

    • qbitrr.db: The main consolidated database containing all Arr instances and WebUI data.
    • qbitrr.db-wal: The Write-Ahead Log containing uncommitted changes.
    • qbitrr.db-shm: A shared memory index used for WAL mode.

    Locations:

    • Docker: /config/qBitManager/
    • Native: ~/config/qBitManager/ or .config/qbitrr/ in the current directory (or as defined by QBITRR_OVERRIDES_DATA_PATH).
    | Database File | Purpose | Location |
|--------------|---------|----------|
| `qbitrr.db` | **Single consolidated database** for all Arr instances and WebUI data | `~/config/qBitManager/` or `/config/qBitManager/` |
| `qbitrr.db-wal` | Write-Ahead Log (uncommitted changes) | Same directory |
| `qbitrr.db-shm` | Shared memory index for WAL mode | Same directory |

  7. Overview of Request Integration

    master

    qBitrr integrates with request management systems like Overseerr and Ombi to automate the search for user-requested content. It periodically polls these systems, triggers searches in Radarr or Sonarr for approved content, and monitors the download/import process.

    Supported Systems:

    • Overseerr: Full support including 4K instances, release date filtering, and advanced status handling. Recommended for modern setups.
    • Ombi: Supports approved and all-requests modes. Does not support 4K separation or release date filtering.
    • Requestrr: Integrates via Overseerr or Ombi backends (no direct qBitrr support).

    Unsupported Types: Request integration is only available for movies and TV. It is not supported for Lidarr (music) or Readarr (books).

  8. Configure Lidarr import modes

    master

    The importMode setting determines how files are handled after downloading. Available options are:

    ModeBehavior
    AutoLet Lidarr decide based on its own settings
    MoveMove files from download folder to library (faster, frees disk space)
    CopyCopy files and leave original (preserves seeding torrents)

    Tip: Use Copy mode if you are using music trackers with strict seeding requirements to ensure the original torrent remains available for seeding.

    importMode = "Copy"

  9. Protect against Hit-and-Run (HnR) violations

    master

    Hit-and-Run (HnR) protection is a safety layer that prevents qBitrr from removing torrents until the specific requirements of a private tracker are satisfied, even if your global SeedingMode limits are met.

    How HnR Protection Works

    • Full downloads (100%): HnR clears when either MinSeedRatio OR MinSeedingTimeDays is met.
    • Partial downloads (>= HitAndRunMinimumDownloadPercent%): HnR clears only when HitAndRunPartialSeedRatio is met (time is ignored).
    • Downloads < HitAndRunMinimumDownloadPercent%: Generally not subject to HnR.
    • TrackerUpdateBuffer: Extra seconds subtracted from seeding time to account for tracker reporting lag.
    • Automatic Bypass: If a tracker reports a torrent as unregistered, unauthorized, or not found, HnR protection is bypassed.
    • Multi-tracker priority: If a torrent has multiple trackers, the one with the highest Priority determines the HnR settings.

    Best Practices for HnR

    • Use importMode = "Copy" for private trackers.
    • Set qBitrr limits (MaxUploadRatio, MaxSeedingTime) slightly higher than the tracker's minimum requirements to provide a safety margin.
    • For absolute safety, set RemoveTorrent = -1 to never remove torrents.

  10. Understand the Torrent State Machine

    master

    Torrents managed by qBitrr progress through a lifecycle of states. Understanding these transitions is key to configuring automation behaviors like blacklisting and re-searching.

    State Lifecycle:

    • Detected: A new torrent is found in qBittorrent.
    • Downloading: The torrent is actively being downloaded.
    • Stalled: Progress has stopped (e.g., ETA exceeds MaxETA or no progress for longer than StallTimeout).
    • Completed: progress == 1.0 and state is uploading.
    • Importing: The torrent has passed validation (e.g., ffprobe) and is being sent to the Arr API.
    • Imported: The torrent has been successfully handled by the Arr application.
    • Failed: The download failed.
    • Blacklisted: The torrent is marked as failed and added to the Arr blacklist (occurs after retry limits are exceeded).
    • Re-searching: Triggered if AutoReSearch is enabled in the config after a blacklist event.
    • Seeding: The torrent is being uploaded to meet seed goals.
    • Deleted: The torrent is removed from qBittorrent after seed ratio/time goals are met.
    ┌─────────┐
        │ Detected│ (New torrent found in qBittorrent)
        └────┬────┘
             │
        ┌────▼─────────┐
        │ Downloading  │
        └────┬─────────┘
             │
    ┌────────┴────────┐
    │                 │
┌───▼────┐      ┌────▼─────┐
│Stalled │      │Completed │
└───┬────┘      └────┬─────┘
    │                └────┬─────┘
    │                     │
┌───▼────┐      ┌────▼─────┐
│Failed  │      │Importing │
└───┬────┘      └────┬─────┘
    │                └────┬─────┘
┌───▼────┐      ┌────▼─────┐
│Blacklisted │  │Imported  │
└───┬────────┘  └────┬─────┘
    │                └────┬─────┘
┌───▼────┐      ┌────▼─────┐
│Re-searching│  │ Seeding  │
└───┬────────┘  └────┬─────┘
    │                └────┬─────┘
                ┌────▼─────┐
                │ Deleted  │ (After seed goals met)
                └──────────┘

  11. Compare Ombi and Overseerr for qBitrr integration

    master

    When choosing a request management tool for qBitrr, consider the following differences:

    FeatureOmbiOverseerr
    User InterfaceOlder, Angular-basedModern, React-based
    Media DiscoveryBasicAdvanced (TMDB integration)
    Request ManagementBasic approvalFull workflow (approve/decline/comment)
    4K SupportLimitedNative
    User PermissionsBasic rolesGranular (per-user quotas, limits)
    PerformanceCan be slow with many usersFast, lightweight

    Recommendation: Use Overseerr for new setups due to better UX and modern features. Ombi is suitable for existing setups or simpler use cases.

  12. Understand auto-update support by installation method

    master

    Auto-update behavior depends heavily on how qBitrr was installed:

    • PyPI/pip: Fully supported for latest and stable (via pip install --upgrade) and nightly (via git).
    • Docker: Fully supported via a persistent /config/runtime overlay inside the container. It does not pull new Docker images; it installs updates into the container's filesystem. This survives container recreates if /config is mounted. If a new image is pulled that is already newer than the overlay, the overlay is cleared automatically.
    • Binary: Fully supported for latest and stable (uses download + SHA256 verify + atomic replace). Nightly is not supported for binaries.
    • Source (.git checkout or QBITRR_SOURCE_BUILD=1): Not supported. Auto-update is forced off. You must update the working tree or rebuild the image manually.