QBittorrentBot

QBittorrentBot is a Telegram bot that allows you to control your qBittorrent client directly through Telegram. With this bot, you can manage your torrent downloads, add magnet links, and much more—all from within your chat.

You can add multiple magnet links by simply placing one per line:

magnet:?xt=...
magnet:?xt=...

The bot allows you to:

• List active torrents
• Pause/resume torrents
• Delete torrents
• Add, remove, and modify categories

Table of Contents

• QBittorrentBot
• Table of Contents
  • Warning!
  • Configuration
    • Retrieve Telegram API ID and API HASH
    • YAML Configuration
    • Important:
  • Running
    • Build Docker
    • Running Without Docker
  • Contributing Translations on Transifex
  • How to Enable the qBittorrent Web UI
  • Contributors ✨
  • Star History

Warning!

Since version V2, the configuration format has changed. Please ensure your configuration file is updated correctly before starting the bot.

Configuration

Retrieve Telegram API ID and API HASH

As part of the transition to Aiogram, you no longer need the API_ID and API_HASH. You only need your bot_token to authenticate with the Telegram API.

YAML Configuration

QBittorrentBot now uses a YAML configuration file, replacing the old JSON format. The new configuration format includes settings for the qBittorrent client, Telegram bot, Redis (optional), and user roles.

Here’s an example configuration (config.yml):

client:
  type: qbittorrent
  host: http://localhost:8080/
  user: admin
  password: adminadmin

redis:
  url: redis://localhost:6379/0

telegram:
  bot_token: PUT_YOUR_TELEGRAM_BOT_TOKEN_HERE
  proxy: null

users:
  - user_id: 123456789
    role: administrator
    notify: true
    notification_filter: null
    locale: en

  - user_id: 987654321
    role: manager
    notify: true
    notification_filter:
      - Movies
      - TV
    locale: es

  - user_id: 192837465
    role: reader
    notify: false
    notification_filter: null
    locale: it

• client: Configuration for the qBittorrent client (host, username, password).
• telegram: Telegram bot settings (bot token, proxy settings if applicable).
• redis: Optional, for Redis configuration (useful for persistence and session management).
• users: List of users, each with settings for notifications, locale, and role.

Important:

• If notify is set to true, the user will receive notifications when a torrent finishes downloading.

Running

Build Docker

To run QBittorrentBot with Docker, follow these steps:

1. Clone the repository:

   git clone https://github.com/ch3p4ll3/QBittorrentBot.git

2. Move into the project directory:

   cd QBittorrentBot

3. Create your config.yml file.

4. In the project folder, navigate to the docker/ directory, where the docker-compose.yml example file is located.

   docker compose up -d

The docker-compose.yml file should already be pre-configured for you. It will automatically build the image and start the container.

This method will also mount the /app/config/ volume, ensuring that the bot uses your configuration settings.

Running Without Docker

If you prefer to run the bot natively, follow these steps. This project uses uv for high-performance dependency management.

1. Clone the repository

git clone https://github.com/ch3p4ll3/QBittorrentBot.git
cd QBittorrentBot

2. Install uv

If you don't have uv installed yet, follow the official installation guide.

3. Setup Configuration

Create your config.yml file based on the provided template.

4. Start the Bot

You don't need to manually install requirements into a global environment. Simply run:

uv run python -m src.main

Note: uv will automatically create a virtual environment, install the necessary dependencies from your pyproject.toml or requirements.txt, and execute the bot as a module.

Why the change?

Using python -m src.main instead of python3 main.py ensures that the Python interpreter correctly recognizes the src folder as a package, preventing common ImportError issues with relative paths.

Contributing Translations on Transifex

QBittorrentBot is an open-source project that thrives with contributions from the community. If you’re multilingual and want to help make QBittorrentBot accessible to more users, you can contribute translations via Transifex.

Here’s how you can help:

1. Visit the QBittorrentBot Transifex Project.
2. Sign up or log in to your Transifex account.
3. Navigate to the "Languages" tab and select the language you’d like to contribute to.
4. Find the string you want to translate and submit your translation.
5. If your language isn’t listed, you can request its addition.
6. Once your translations are reviewed and approved, they will be included in the project.

Thank you for contributing!

How to Enable the qBittorrent Web UI

To allow the bot to interact with your qBittorrent client, you need to enable the Web UI. Here’s how to do it:

1. Open qBittorrent and go to the menu bar.
2. Navigate to Tools > Options.
3. In the new window, select the Web UI tab.
4. Enable Enable the Web User Interface (Remote control).
5. Choose a port (default is 8080).
6. Set a username and password (default: admin / adminadmin).

Click OK to save the settings.

Contributors ✨

Thanks goes to these wonderful people (emoji key):

Bogdan 💻

joey00797 🌍

Rodolfo Ortega 🌍

Andrew Miroshnichenko 💻 🐛

This project follows the all-contributors specification. Contributions of any kind welcome!

Star History