DOCSEARCHbyAlgolia
Submit Docs

qBit Manage Documentation

repository·develop·Indexed 23 days ago

https://github.com/stuffanthings/qbit_manage

An automation tool for managing qBittorrent instances. It provides features for automated tagging, categorization, cleanup of orphaned files and unregistered torrents, and enforcement of share limits. The tool includes a Web UI for visual configuration of YAML files, a FastAPI backend, and a built-in scheduler for task automation. It supports webhook notifications via Notifiarr and Apprise API.

Tokens
24.6K
Snippets
44
Records
135
Agent score
82%

What's inside qBit Manage

  1. Overview of qBit Manage features

    develop

    qBit Manage is a management tool for qBittorrent instances. It automates various torrent management tasks, including:

    • Tagging & Categorization: Tag torrents based on tracker URLs, apply categories based on save_path, or change categories using cat_change.
    • Cleanup: Remove unregistered torrents (optionally deleting data), remove orphaned files not referenced by qBittorrent, and use a RecycleBin function to move files instead of direct deletion.
    • Maintenance: Recheck paused torrents (sorted by lowest size) and resume them if completed.
    • Link Management: Tag torrents that lack hard links outside the root folder.
    • Share Limits: Apply share limits to groups filtered by tags/categories, with optional cleanup based on maximum ratio or time seeded, while respecting minimum seed time and minimum seeder counts.
    • Automation & Notifications: Includes a built-in scheduler to run tasks every $x$ minutes and supports webhook notifications via Notifiarr and Apprise API.

  2. Overview of qBit Manage Web UI

    develop

    The qBit Manage Web UI is a modern interface designed to configure and manage qBit Manage. Instead of manually editing YAML files, users can use an intuitive visual interface to perform real-time editing.

    Key features include:

    • Visual Configuration Editor: Uses forms for editing YAML configurations.
    • Real-time Validation: Provides instant feedback on configuration errors.
    • Undo/Redo History: Allows tracking and reverting changes.
    • Theme Support: Includes light/dark modes with system preference detection.
    • Responsive Design: Compatible with desktop and mobile devices.
    • YAML Preview: Offers a real-time preview of the generated configuration.

  3. Configure share_limits to control torrent seeding and cleanup

    develop

    The share_limits configuration allows you to group torrents and apply specific rules for their maximum share ratio, seeding time, and upload speed. Each torrent is matched with the highest priority group (lowest priority number) that meets its filter criteria.

    Key behaviors:

    • No match: If no group matches a torrent, it remains untouched (no limits, no tags, no cleanup).
    • Catch-all group: To apply a default rule to all torrents, create a group with the highest priority number (e.g., 999) and no filters. Set add_group_to_tag: false to prevent it from adding a tag to untouched torrents.
    • Priority: Lower numbers have higher priority. A group's priority should be largest priority + 1 relative to others if you want it to be a fallback.
    share_limits:
  default:
    priority: 999
    max_ratio: -1
    max_seeding_time: -1
    cleanup: false
    add_group_to_tag: false

  4. Use test factories for unit testing

    develop

    To avoid needing a live qBittorrent connection during tests, use the bypass-constructors provided in tests/factories.py. These factories allow you to create objects with specific configurations using keyword arguments.

    Key Helpers:

    • make_share_limits() — returns a configured ShareLimits instance
    • make_category() — returns a Category instance
    • make_tag_nohardlinks() — returns a TagNoHardLinks instance

  5. How nohardlinks works and how to configure it

    develop

    The nohardlinks functionality identifies torrents whose files (or the largest file in a multi-file torrent) do not have any hardlinks outside of the qbit_manage root_dir. This is useful for identifying data that is not being properly hardlinked for media libraries.

    Usage Requirements:

    • You must have configured the directory section (root_dir or remote_dir) for this to work.
    • You must use the category names defined in the cat section as keys.
    • To match torrents with no category, use an empty string "" as the key. Note that there is no All or Uncategorized wildcard; you must list each category you want checked.

    Key Options:

    • ignore_root_dir (Default: True): If set to true, the script ignores hardlinks detected within the same root_dir.
    • exclude_tags: A list of tags to exclude from the check. Torrents with these tags will not be processed.

  6. How stalled torrent tagging works

    develop

    To tag stalled downloading torrents, you must set both tag_stalled_torrents to true and define the desired tag name in stalled_tag. The boolean toggle activates the feature, while the string defines the actual tag applied to the torrent.

    settings:
  tag_stalled_torrents: true
  stalled_tag: my_custom_stalled_tag

  7. Understand the difference between cleanup and share_limit_action

    develop

    There are two distinct models for handling torrents when they reach their limits. You must choose one, as they are mutually exclusive for a single group.

    1. qbm-managed deletion (Recommended)

    Use this to leverage the qBit Manage recyclebin feature.

    • Configuration: cleanup: true AND share_limit_action: Default or Stop.
    • Workflow: qBittorrent stops the torrent $\rightarrow$ qBit Manage runs its batch pass $\rightarrow$ qBit Manage moves files to the recyclebin location.

    2. qBittorrent-managed deletion

    Use this if you want qBittorrent to handle everything immediately.

    • Configuration: cleanup: false AND share_limit_action: Remove or RemoveWithContent.
    • Workflow: qBittorrent hits the limit $\rightarrow$ qBittorrent removes the torrent/files immediately.
    • WARNING: This bypasses the qBit Manage recyclebin. Files are not recoverable via qbm.

    Note: qBit Manage will fail to start if you attempt to set cleanup: true with a destructive share_limit_action (like RemoveWithContent).

  8. Understand the qBit Manage project structure

    develop

    The repository is organized as follows:

    • qbit_manage.py: Main entry point and CLI argument parsing
    • modules/: Core application logic
      • config.py: Config loading
      • qbittorrent.py: qBittorrent API wrapper
      • web_api.py: REST API server
      • web_ui.py: Web UI server
      • core/: Per-feature modules (e.g., tags.py, share_limits.py)
    • tests/: Test suite (including factories.py for testing)
    • web-ui/: Web UI frontend
    • desktop/tauri/: Tauri desktop app shell
    • config/: Sample configuration files
    • Makefile: Development automation

  9. Understand the Post-Merge Release Cascade

    develop

    Once a release PR is merged into master, a chain of automated workflows is triggered by the resulting push. The sequence is as follows:

    1. tag.yml: Reads the VERSION file and creates/pushes the v<X.Y.Z> tag.
    2. pypi-publish.yml: Triggered by the new tag; builds and publishes the Python package to PyPI using OIDC.
    3. version.yml: Triggered by the new tag; builds/pushes the Docker image and converts the existing draft GitHub release (created during the Release PR step) into a published release. It does not rebuild binaries.
    4. update-develop-branch.yml: Back-merges master into develop and bumps the VERSION to the next development iteration (e.g., 4.7.2 → 4.7.3-develop1).

  11. Understand the rem_unregistered cross-seed safety model

    develop
    When using the rem_unregistered command, qBit Manage includes a safety check for cross-seeding. Even if rem_unregistered_filter_completed is set to true, the logic will check for cross-seed siblings before deleting torrent data. If a torrent is marked as unregistered AND completed, but a sibling cross-seed shares the same save path, the data files will be preserved.

  12. Configure qBit Manage Execution Mode and Scheduling

    develop

    Control how and when qbit_manage runs.

    • Run Once: Use -r or --run (or QBT_RUN) to run the script once without the scheduler. The script will exit after completion.
    • Scheduling: Use -sch or --schedule (or QBT_SCHEDULE) to run at specific intervals. You can pass an integer representing minutes (default: 1440 for 1 day) or a cron expression.
    • Startup Delay: Use -sd or --startup-delay (or QBT_STARTUP_DELAY) to set a delay in seconds before the first scheduled run (default: 0).