# qBit Manage for Automated qBittorrent Maintenance

> qBit Manage is a Python automation layer for qBittorrent that handles tagging, category rules, orphaned data, cross-seeded torrents, share limits, notifications, and recurring maintenance. It suits self-hosted users who need policy-driven cleanup, but its deletion behavior and dependency on qBittorrent filesystem access require careful configuration.

**StuffAnThings/qbit_manage** — This tool will help manage tedious tasks in qBittorrent and automate them. Tag, categorize, remove Orphaned data, remove unregistered torrents and much much more.

- Repository: https://github.com/StuffAnThings/qbit_manage
- Stars: 1,666 · Forks: 89
- Language: Python
- License: MIT
- Published: 2026-10-16 · Updated: 2026-10-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/stuffanthings-qbit-manage

## Why qBit Manage Exists Beyond qBittorrent Automation

qBit Manage addresses the gap between maintaining an ordinary qBittorrent session and enforcing library-wide rules over time. Its target user is likely a self-hosted qBittorrent operator with multiple categories, tags, tracker-specific naming conventions, cross-seeded content, or retention policies that would otherwise require repetitive manual work. The README lists tag assignment by tracker URL, category assignment based on `save_path`, category changes, unregistered-torrent cleanup, paused-torrent recovery, orphan removal, and share-limit enforcement.

The project is not intended as a replacement qBittorrent interface. Its `qbit_manage.py` entry point and the installed `qbit-manage` command expose administrative operations, while the package metadata also includes FastAPI, Uvicorn, SlowAPI, and a `web-ui` directory. The repository files establish that a web component exists, but the README does not explain its supported operations or deployment instructions, so its role should not be treated as a documented replacement for the qBittorrent UI.

This tool is most relevant where policies cross torrent boundaries. Applying categories from save paths, identifying torrents without external hard links, and handling unregistered or orphaned data all require a broader view than qBittorrent presents to an occasional user. That also makes configuration quality more important. A cleanup automation system is only as dependable as its understanding of the filesystem layout and retention rules.

## qBit Manage Rules, Filesystem Checks, and Deletion Paths

The repository layout indicates a Python application centered on `qbit_manage.py`, with behavior organized under `modules/`, configuration examples under `config/`, and supporting assets under `web-ui/`. Package metadata identifies `qbittorrent-api==2026.10.0` as the interface used to communicate with qBittorrent. This is a sensible boundary: qBit Manage can apply management policy while the dependency handles the client-facing API details.

Several jobs operate on relationships between qBittorrent metadata and local files. Orphan cleanup removes files under the configured root that qBittorrent no longer references. Another rule can tag multi-file torrents when no hard links exist outside the root folder, using the largest file for the multi-file case. These checks depend on seeing the same filesystem state as qBittorrent. A container path that does not represent the torrent root can therefore produce an incorrect view, even when qBittorrent authentication succeeds.

Deletion has several branches. An unregistered torrent is deleted together with its data only when it is not being cross-seeded. In the cross-seeded case, the torrent is removed without deleting the shared data. Share-limit groups can clean up content according to maximum ratio, seeding time, minimum seed time, and optional minimum seeder requirements. The optional RecycleBin function changes deletion behavior by moving files into a RecycleBin folder rather than deleting them immediately.

That branching is useful, but it also creates configuration-sensitive behavior. Cross-seed status, tracker groups, save paths, and root-directory boundaries determine whether content remains. The README does not provide a universal rollback procedure, nor does it document a dry-run mode. Operators should inspect the specific configuration options in the project's Config Setup wiki before enabling cleanup rules.

## Local and Docker Installation Paths for qBit Manage

The README directs local users to Python 3.10 or newer and sends Docker users to dedicated installation guides. Start by consulting the Local Installation, Docker Installation, or Unraid Installation guide in the project wiki.

For an installed local or packaged copy, the documented first command asks the program to display its available commands:

```bash
python qbit_manage.py -h
```

The reader should see the command-line help for the installed source tree. After that, create a configuration file from the repository's `config/config.yml.sample`, fill in the values needed to connect to qBittorrent, and consult the Commands wiki for the exact operation to run. The README says configuration setup is required, but it does not state which fields are mandatory in this page.

Container deployments follow a different setup path. The supplied `Dockerfile` uses a multi-stage Python 3.14 Alpine build, installs dependencies with `uv`, sets `QBM_DOCKER=True`, and produces a smaller runtime image. OCI labels identify the image as `qbit-manage`, version it dynamically, and record the MIT license. Those details confirm container support, but they are not a substitute for the Docker Installation guide.

Because the project can remove files, the first real use should be selected from the command list with the least destructive scope, not an unexplained “clean everything” action. The repository includes `tests/`, `pytest.ini`, and Playwright web UI tests, but the README does not give users a configuration validation command.

## Scheduling and Notification Boundaries in qBit Manage

qBit Manage includes its own scheduler and can run a single pass with the documented `--run` command. These are materially different operating modes. The scheduler is appropriate for a long-running Python or Docker deployment where periodic rules should execute every configured number of minutes. The one-shot mode fits external schedulers, including host cron or an orchestration platform that already owns timing.

That built-in scheduler is also a real alternative to building a custom maintenance service. Instead of writing a separate script around `qbittorrent-api`, an operator can use qBit Manage for recurring policy evaluation. A custom script remains more appropriate for a narrow workflow that needs exact control over API calls, custom decisions, or an application-specific event pipeline, although that approach creates code and maintenance work outside this project.

Notifications cover two documented integrations: Notifiarr and Apprise API. The repository does not state which events trigger messages, which notification transports are supported by Apprise, or how delivery failures affect cleanup. Treat notifications as an operational integration rather than proof that every deletion or skipped action is reported.

The scheduler also changes the operational blast radius. A one-shot command can be supervised and inspected in isolation. A continuously scheduled process can repeat a bad root path or rule on every pass. The wiki's Commands and Config Setup pages are therefore part of the safety boundary, not merely setup reading.

## qBittorrent Compatibility and Dependency Constraints

Compatibility depends on `qbittorrent-api`, which qBit Manage pins at version `2026.10.0` in `pyproject.toml`. The README warns that new qBittorrent releases may not be supported immediately because qBit Manage cannot add support until the underlying API library does. It also describes an automated dependency-update chain: Renovate watches `qbittorrent-api`, updates occur after a release is at least three days old, and CI refreshes `SUPPORTED_VERSIONS.json`.

That process reduces the need to request routine dependency bumps, but it does not guarantee immediate compatibility with every qBittorrent release. The repository includes releases `v4.13.0` on 2026-09-04 and `v4.12.0` on 2026-08-16, followed by `latest-develop` on 2026-10-14. The default branch is `develop`, while contributions are also directed to that branch in the README. Anyone prioritizing release predictability should distinguish tagged releases from the develop build.

The package requires Python `>=3.10` and pins several operational dependencies, including `fastapi==0.139.0`, `uvicorn==0.51.0`, `ruamel.yaml==0.19.1`, and `requests==2.34.2`. Exact pins improve reproducibility for a deployment, but upgrades can require coordinated release work. The MIT license permits use and modification under its terms; this is a factual note rather than legal guidance. Any redistribution should follow the license and included notices as required.

## Maintenance Activity and Upgrade Work for qBit Manage

The repository is not archived. The README also documents automated handling for `qbittorrent-api` version bumps and a development build released on the same date. Those facts indicate ongoing repository work, but they do not establish that every supported qBittorrent version is bug-free or that every documentation page is current.

Upgrade work for an operator has at least two components. First, the Python package itself changes, and its pinned dependencies can change. Second, qBittorrent support depends on the capabilities of `qbittorrent-api` and on `SUPPORTED_VERSIONS.json`. An upgrade review should therefore check the project's current supported-version data rather than assuming a newer qBittorrent client is automatically acceptable.

The web UI adds another maintenance surface. `package.json` defines a private `qbit-manage-web-ui-tests` package, requires Node.js 20 or newer, and uses Playwright 1.61.1 for `test:web-ui`. This is test infrastructure for contributors, not an end-user installation command. The Python side separately defines development dependencies for pytest, coverage, Ruff, and pre-commit.

Configuration migration is another practical concern. The README does not specify a schema version, automatic migration command, or rollback procedure. Operators should retain their current configuration file and consult the release notes and configuration guide before replacing it.

## Conclusion

Adopt qBit Manage if you operate a self-hosted qBittorrent instance and want repeatable tag, category, orphan cleanup, and share-limit policies. Do not adopt it if you need a lightweight interactive client or cannot grant it accurate access to torrent roots. Before enabling destructive cleanup, verify the configuration file, qBittorrent version support, and RecycleBin behavior for the exact root directories involved.

## FAQ

### How do I install qBit Manage for qBittorrent?

The README offers Python 3.10+ local installation and Docker or Unraid installation through the project wiki. After installation, create a configuration file from `config/config.yml.sample` and fill in the values needed to connect to qBittorrent.

### Can qBit Manage remove orphaned files and unregistered torrents?

Yes. It can remove files under the configured root when qBittorrent does not reference them. For an unregistered torrent, it deletes the torrent and data when the torrent is not cross-seeded, otherwise it removes only the torrent.

### Does qBit Manage have a RecycleBin and an external scheduler?

It has a RecycleBin function that moves deleted files into a RecycleBin folder instead of deleting them directly. Its built-in scheduler runs the script every configured number of minutes, while the documented `--run` command performs a run without that scheduler.

## Sources

- [Issues](https://github.com/StuffAnThings/qbit_manage/issues)
- [License: MIT](https://github.com/StuffAnThings/qbit_manage/blob/develop/LICENSE)
- [README](https://github.com/StuffAnThings/qbit_manage/blob/develop/README.md)
- [Releases](https://github.com/StuffAnThings/qbit_manage/releases)
- [StuffAnThings/qbit_manage on GitHub](https://github.com/StuffAnThings/qbit_manage)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/stuffanthings-qbit-manage