wiki/Catalogue-Self-Hosted/apps/app-qbit-manage.md

---
title: qBit Manage
created: 2026-06-07
updated: 2026-06-07
type: app
tags: [catalogue, automation, qbittorrent, torrent, cross-seed, python]
confidence: high
contested: false
sources: [https://selfh.st/apps/?tag=Automation, https://github.com/StuffAnThings/qbit_manage]
---

# 🧹 qBit Manage

> **Le majordome de votre instance qBittorrent** — automatise toutes les tâches fastidieuses : taguer par tracker, catégoriser par dossier, supprimer les torrents « unregistered », nettoyer les orphelins, gérer les share limits, cross-seed, et bien plus.

## 📋 Informations Générales

| Champ | Valeur |
| :--- | :--- |
| **Site web** | [github.com/StuffAnThings/qbit_manage](https://github.com/StuffAnThings/qbit_manage) |
| **GitHub** | [StuffAnThings/qbit_manage](https://github.com/StuffAnThings/qbit_manage) |
| **License** | MIT |
| **Langage** | Python (53 %), JavaScript (32 %), CSS, Rust |
| **Étoiles GitHub** | 1 500 ⭐ |
| **Dernière MAJ** | 2026-05-30 (release v4.8.0) |
| **Catégorie** | [[cat-automation\|Automation]] |

## 📝 Description

**qBit Manage** est l'outil compagnon indispensable de [[app-qbittorrent]] : il prend en charge tout ce que l'UI native ne fait pas, ou mal, pour une gestion durable d'une bibliothèque de torrents. C'est l'équivalent d'**autobrr** côté **monitoring/cleanup**, alors qu'autobrr se concentre sur la **course au download**.

Le programme s'exécute en **boucle planifiée** (intervalle configurable, par défaut 5 min) et applique en cascade des règles définies dans un `config.yml`. Voici le périmètre fonctionnel :

- **Tagging par tracker** : assigne automatiquement un tag (par exemple `private-tracker`, `public-tracker`, `*arr`) à chaque torrent en fonction de son URL tracker. C'est la base de presque toutes les autres règles.
- **Catégorisation par `save_path`** : si un torrent est sans catégorie, qBit Manage l'assigne selon le dossier où il se trouve.
- **Suppression des torrents « unregistered »** : pour les torrents supprimés par les trackers, qBit Manage vérifie le statut et supprime le torrent (et le fichier, ou seulement le torrent si du cross-seed est détecté ailleurs).
- **Recheck & Resume** : sur les torrents en pause, les trie par taille croissante, force un `recheck`, et reprend ceux qui sont complets (utile après un crash disque).
- **Nettoyage des orphelins** : détecte les fichiers dans le dossier racine de qBittorrent qui ne sont plus référencés par aucun torrent, et les déplace vers une corbeille configurable.
- **Détection de hardlinks** : tague les torrents qui n'ont aucun hardlink hors du dossier racine (signe qu'ils ne sont pas cross-seedés).
- **Share limits** : applique des limites de ratio/temps de seed par groupe de tags, avec cleanup optionnel des torrents atteignant les limites.
- **RecycleBin** : au lieu de supprimer, déplace les fichiers vers un dossier corbeille pendant X jours.
- **Notifications** : intégration native Notifiarr, Apprise, Discord, Telegram via webhooks.
- **Web UI** (depuis v4.x) : frontend de gestion du `config.yml` sur le port 8181 (changé depuis 8080 pour éviter le conflit avec qBittorrent lui-même).

## 🚀 Installation

### Option 1 : Docker Compose (recommandé)

```yaml
# docker-compose.yml
services:
  qbit-manage:
    image: ghcr.io/stuffanthings/qbit_manage:latest
    container_name: qbit-manage
    restart: unless-stopped
    environment:
      - TZ=Europe/Paris
      - PUID=1000
      - PGID=1000
      - QBT_HOST=localhost
      - QBT_PORT=8080
      - QBT_USER=admin
      - QBT_PASSWORD=***    volumes:
      - ./config:/config      # config.yml et fichiers associés
      - ./logs:/logs
    ports:
      - "8181:8181"           # Web UI (gérer le config.yml)
    depends_on:
      - qbittorrent

  qbittorrent:
    image: lscr.io/linuxserver/qbittorrent:latest
    container_name: qbittorrent
    restart: unless-stopped
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=Europe/Paris
      - WEBUI_PORT=8080
    volumes:
      - ./qbt-config:/config
      - ./downloads:/downloads
    ports:
      - "8080:8080"

volumes:
  qbt-config:
```

### Option 2 : Binaire standalone / Tauri Desktop

Des binaires standalone Linux x86_64 / ARM64 sont disponibles, ainsi qu'une **application Tauri** multi-plateforme (Linux, macOS, Windows) pour les utilisateurs qui ne veulent pas d'image Docker.

### Option 3 : Python (bare-metal)

```bash
git clone https://github.com/StuffAnThings/qbit_manage.git
cd qbit_manage
python -m pip install -r requirements.txt
python qbit_manage.py
```

Nécessite Python 3.10+ (depuis v4.6.6).

## ⚙️ Configuration

1. **Éditer `config/config.yml`** : spécifier l'URL, l'utilisateur, le mot de passe de qBittorrent.
2. **Définir les `directory` roots** : indiquez le dossier racine de votre bibliothèque torrent pour la détection d'orphelins.
3. **Configurer les `cat_change`** : transitions de catégorie (par exemple, quand un torrent passe en `Wanted` → `Have`).
4. **Activer le scheduler** : fréquence de scan recommandée = 5 à 15 min selon l'activité de votre instance.
5. **`share_limits`** : configurer les groupes (par tag) et les règles de ratio/temps.
6. **Notifications Apprise/Notifiarr** : brancher pour suivre l'activité en temps réel.
7. **Dry-run au début** : commenter les sections de suppression tant que vous n'avez pas validé le comportement sur 24-48 h.

## 🔄 Alternatives

### Open Source
- [[app-qbittorrent]] — UI native, mais sans automation
- **cross-seed** — Outil dédié à la recherche automatique de releases alternatives pour le cross-seed (complémentaire, pas concurrent)
- [[app-autobrr]] — Automation côté **acquisition** (téléchargement initial), qBit Manage côté **maintenance** (cleanup)
- **Huginn** — Agent d'automation généraliste, peut scripter l'API qBittorrent

### Propriétaires (ce que qBit Manage remplace)
- **qBittorrent Enhanced Edition** (fork Windows non officiel, fonctionnalités similaires intégrées)
- **uTorrent Pro / BitTorrent Pro** — Historique, ratio management, mais lourd et publicitaire
- **Sonarr/Radarr + custom scripts** — Empilement de scripts Bash/Python, moins intégré

## 🔐 Sécurité

- ⚠️ Le **mot de passe qBittorrent** est en clair dans le `config.yml` : **chmod 600** sur le fichier, ou mieux, utiliser **Docker secrets** (`/run/secrets/qbt_password` + variable `QBT_PASSWORD_FILE`)
- 🔐 **Web UI qBit Manage** (port 8181) : **ne pas exposer sur Internet** sans auth (reverse proxy + SSO [[app-authelia]] recommandé)
- 🛡️ **VPN obligatoire** pour le trafic BitTorrent ([[app-gluetun]]) : qBit Manage n'ajoute pas de VPN, il s'appuie sur celui de qBittorrent
- 🔑 **Tokens Notifiarr/Apprise** stockés dans le YAML : rotation régulière, pas d'exposition Git
- 🗑️ La **RecycleBin** doit être montée sur le même filesystem que la bibliothèque pour éviter les copies inutiles
- 📜 **Logs** : ils peuvent contenir des **passkeys de tracker** (corrigés en v4.8.0, mais surveiller), purger régulièrement
- 🚨 Tester en `dry-run` les règles `remove_unregistered` et `share_limits` avant activation

## 📚 Ressources

- [Repo GitHub StuffAnThings/qbit_manage](https://github.com/StuffAnThings/qbit_manage)
- [Wiki Local Installations](https://github.com/StuffAnThings/qbit_manage/wiki/Local-Installations)
- [Wiki Docker Installation](https://github.com/StuffAnThings/qbit_manage/wiki/Docker-Installation)
- [Wiki Config Setup](https://github.com/StuffAnThings/qbit_manage/wiki/Config-Setup)
- [Exemple de config.yml](https://github.com/StuffAnThings/qbit_manage/blob/master/config/config.yml.sample)
- [Changelog](https://github.com/StuffAnThings/qbit_manage/releases)

## Pages Liées
- [[cat-automation]] — Vue d'ensemble de la catégorie
- [[app-qbittorrent]] — Client torrent cible
- [[app-autobrr]] — Complément côté acquisition
- [[app-gluetun]] — VPN pour le trafic torrent
- [[app-traefik]] — Reverse proxy HTTPS
- [[app-authelia]] — SSO
- [[securisation-home-lab]] — Bonnes pratiques
- [[recettes-docker-compose]] — Templates Docker