To start using the bot, you must first create a directory that will contain Docker Compose, configuration files, logs, and runtime data.

We recommend using a dedicated project directory.

Example:

/home/user/docker/QBittorrentBot

This directory will be the project root for the bot.

Inside the project directory, use the following structure:

QBittorrentBot/
├── docker-compose.yml
└── data/
    ├── config.yml
    └── logs/

Explanation:

• docker-compose.yml Located in the project root. All start, stop, and update commands must be executed from this directory.

• data/ Persisted storage mounted into the container as /app/data. This directory contains:

  • config.yml – bot configuration
  • logs/ – application logs

The bot configuration is stored in:

data/config.yml

You may create this file before or after starting the bot.

• If config.yml exists, the bot will load it at startup.
• If it does not exist, the bot will automatically generate a default config.yml inside the data/ directory on first launch.

After the initial generation, you must edit the file and restart the bot once to apply the initial configuration.

If a configuration file from a previous version (config.json) is found in the data/ directory, the bot will:

1. Automatically remove the old config.json
2. Create a new config.yml using the current configuration format

QBittorrentBot automatically reloads the configuration file whenever a change is detected. Most configuration updates take effect without restarting the bot.

For detailed configuration options, see: Configuration File

Create a file named docker-compose.yml in the project root directory (QBittorrentBot/) with the following content:

services:
  bot:
    image: "ch3p4ll3/qbittorrent-bot:latest"
    container_name: qbittorrent-bot
    restart: unless-stopped
    depends_on:
      - cache
    volumes:
      - "./data:/app/data"

  cache:
    image: redis:8
    container_name: redis-cache
    restart: unless-stopped

From the same directory (where docker-compose.yml is located), start the bot:

docker compose up -d

To update QBittorrentBot to the latest version, navigate to the project root directory and run:

docker compose pull
docker compose up -d

Docker Compose will download the new image and restart the containers automatically.

Here’s a polished version of your “Running without Docker” section that includes instructions for running with UV and makes everything clearer and more structured:

Using Docker is strongly recommended, as it isolates the application from the host system and avoids dependency-related issues.

If Docker cannot be used, you can run the bot directly in two ways: standard Python mode or UV mode.

When running without Docker, you are responsible for:

• Ensuring the correct Python version is installed
• Managing dependencies manually (unless using UV)
• Setting up Redis if you plan to use it
• Supervising the bot process (e.g., with systemd)