Skip to main content

Installation

Setting up kbarr from scratch. No Docker experience required.

1. Install Docker​

kbarr runs entirely via Docker Compose. If you don't have Docker installed:

Verify the install:

docker --version
docker compose version

2. Download kbarr​

Create a folder for kbarr and download the two files it needs:

mkdir kbarr && cd kbarr
curl -LO https://github.com/kingbenny101/kbarr/releases/latest/download/docker-compose.yml
curl -LO https://github.com/kingbenny101/kbarr/releases/latest/download/example.env
cp example.env .env

3. Configure the environment​

Open .env in a text editor. The only value you must set is LIBRARY_DIR_HOST:

# Path on your machine where kbarr stores all media.
# qBittorrent saves downloads into <LIBRARY_DIR_HOST>/downloads
# kbarr writes organised files into <LIBRARY_DIR_HOST>/media
LIBRARY_DIR_HOST=/path/to/your/library

Everything else has defaults you can leave alone.

Library path explained​

kbarr organises finished downloads with hardlinks, avoiding file duplication. Hardlinks only work when source and destination share a filesystem, so everything lives under one folder:

/your/library/
├── downloads/    ← qBittorrent saves here
└── media/        ← kbarr writes organised files here

Both paths must be on the same disk. On different disks, kbarr copies files instead.

tip

Running on a NAS or external drive? Point LIBRARY_DIR_HOST to a path on that drive. Don't split downloads/ and media/ across mounts.

4. Start kbarr​

docker compose up -d

kbarr is now running at http://localhost:8282 (or the PORT you set in .env).

The default login is admin / admin. Change it immediately under Settings → General → Account.

5. Set up AniDB credentials​

kbarr uses AniDB to fetch anime metadata, episode lists, and artwork. Access requires registering an API client.

  1. Register an API client at anidb.net/client
  2. In kbarr, go to Settings → Metadata
  3. Enter your Client ID and Client Version
note

AniDB rate-limits API access strictly. kbarr handles this automatically with pacing and backoff — do not run multiple instances using the same client.

6. Set up a torrent indexer​

kbarr supports kbdex and Prowlarr as torrent indexers. Use either or both.

Option A — kbdex (recommended)​

kbdex is an AniDB-aware torrent search engine built alongside kbarr. It matches releases using AniDB series IDs rather than title text, which means it finds the right torrent even when release names use different romanisations or languages. It requires no API key — just point kbarr at your running kbdex instance.

  1. Deploy kbdex — see the kbdex README for setup instructions
  2. In kbarr, go to Settings → Indexer → kbdex
  3. Enter the URL kbdex is accessible at (e.g. http://localhost:8000)

Option B — Prowlarr​

Prowlarr is an indexer manager that aggregates many torrent sites (Nyaa, AniDex, etc.) into a single search API. It requires its own installation and configuration.

  1. Install Prowlarr — see the Prowlarr installation docs
  2. Add your indexers inside Prowlarr (e.g. Nyaa, AniDex)
  3. In kbarr, go to Settings → Indexer → Prowlarr and enter:
    • URL — the address Prowlarr is accessible at (e.g. http://localhost:9696)
    • API key — found in Prowlarr under Settings → General → Security

You can enable both at the same time — kbarr merges results from all active providers.

7. Set up a download client​

kbarr supports qBittorrent as a download client.

qBittorrent​

kbarr does not run qBittorrent — it connects to your existing instance.

  1. Make sure qBittorrent is installed and accessible from your host machine
    • If running natively, it's usually at http://localhost:8080
    • If running in Docker, ensure it's on the same network or exposed on a port
  2. In qBittorrent, set the Default save path to <LIBRARY_DIR_HOST>/downloads
    • In the qBittorrent Web UI: Tools → Options → Downloads → Default Save Path
  3. In kbarr, go to Settings → Downloader → qBittorrent and enter:
    • URL — e.g. http://localhost:8080
    • Username and Password — your qBittorrent Web UI credentials
Download path inside Docker

If qBittorrent runs inside Docker, its save path is expressed in its own filesystem namespace. Make sure the path it saves to maps to <LIBRARY_DIR_HOST>/downloads on the host so kbarr can read the finished files.

Use Test connection in the settings to verify everything is wired up correctly.

Updating​

To update kbarr to the latest version:

docker compose pull
docker compose up -d

Uninstalling​

docker compose down -v

This stops all containers and removes the internal Postgres volume. Your LIBRARY_DIR_HOST folder and .env file are not touched.