qBittorrent

TypeScript api wrapper for qBittorrent using ofetch

Install

npm install @ctrl/qbittorrent
Copy

Requires Node.js 24 or newer.

Use

import { QBittorrent } from '@ctrl/qbittorrent';

const client = new QBittorrent({
  baseUrl: 'http://localhost:8080/',
  username: 'admin',
  password: 'adminadmin',
});

async function main() {
  const res = await client.getAllData();
  console.log(res);
}
Copy

Authentication

The default authentication mode uses qBittorrent's username/password login flow and stores the returned WebUI session cookie.

qBittorrent v5.2.0 and WebAPI v2.14.1 added API key authentication. Pass an API key to use stateless bearer authentication instead of cookie login:

const client = new QBittorrent({
  baseUrl: 'http://localhost:8080/',
  apiKey: 'qbt_0000000000000000000000000000',
});
Copy

API keys can be created from the qBittorrent WebUI. They can also be rotated or deleted through the WebAPI:

const passwordClient = new QBittorrent({
  baseUrl: 'http://localhost:8080/',
  username: 'admin',
  password: 'adminadmin',
});

const apiKey = await passwordClient.rotateApiKey();
await passwordClient.deleteApiKey();
Copy

API

Docs: https://qbittorrent.ep.workers.dev
qBittorrent API Docs: https://github.com/qbittorrent/qBittorrent/wiki/WebUI-API-(qBittorrent-5.0)
qBittorrent API Key Docs: https://github.com/qbittorrent/qBittorrent/wiki/API-Key-Authentication-(≥v5.2.0)

Things that work differently from the other clients:

• label is the qBittorrent category
• qBittorrent ignores unknown hashes, pause, resume, queue and remove don't throw for them
• queueUp/queueDown need torrent queueing enabled, qBittorrent responds with a 409 otherwise. queuePosition is 0 when queueing is disabled or the torrent is seeding
• pauseTorrent/resumeTorrent use /torrents/stop and /torrents/start on qBittorrent 5 and /torrents/pause and /torrents/resume on 4.x

Normalized API

These functions are normalized through @ctrl/shared-torrent, which makes it easier to support multiple torrent clients. See below for alternative supported torrent clients.

getAllData

Returns all torrent data and an array of label objects. Data has been normalized and does not match the output of native listTorrents().

const data = await client.getAllData();
console.log(data.torrents);
Copy

getTorrent

Returns one torrent data from torrent hash

const data = await client.getTorrent('torrent-hash');
console.log(data);
Copy

pauseTorrent and resumeTorrent

Pause or resume one or more torrents

await client.pauseTorrent('torrent-hash');
await client.resumeTorrent(['torrent-hash', 'other-torrent-hash']);
Copy

removeTorrent

Remove one or more torrents. Does not remove data on disk by default.

// does not remove data on disk
await client.removeTorrent('torrent-hash', false);

// remove data on disk
await client.removeTorrent(['torrent-hash', 'other-torrent-hash'], true);
Copy

queueUp and queueDown

Move a torrent up or down the queue

await client.queueUp('torrent-hash');
await client.queueDown('torrent-hash');
Copy

addTorrent

Add a torrent from a magnet link or torrent file, has client specific options. Also see normalizedAddTorrent

import { readFileSync } from 'node:fs';

const result = await client.addTorrent(new Uint8Array(readFileSync('./linux.torrent')));
console.log(result);
Copy

normalizedAddTorrent

Add a torrent and return normalized torrent data, can start a torrent paused and add label

const result = await client.normalizedAddTorrent('magnet:?xt=urn:btih:...', {
  startPaused: false,
  label: 'linux',
});
console.log(result);
Copy

Errors

Failed requests throw a TorrentClientError from @ctrl/shared-torrent with a code of torrent_not_found, unauthorized, request_failed or client_error, the http status when there is one and the original error as the cause.

import { TorrentClientError } from '@ctrl/qbittorrent';

try {
  await client.getTorrent('torrent-hash');
} catch (error) {
  if (error instanceof TorrentClientError && error.code === 'torrent_not_found') {
    // not in the client
  }
}
Copy

export and create from state

If you're shutting down the server often (serverless?) you can export the state

const state = client.exportState();
const restored = QBittorrent.createFromState(config, state);
Copy

See Also

All of the following npm modules provide the same normalized functions along with supporting the unique apis for each client.

• shared types - @ctrl/shared-torrent
• deluge - @ctrl/deluge
• transmission - @ctrl/transmission
• utorrent - @ctrl/utorrent
• rtorrent - @ctrl/rtorrent
• rqbit - @ctrl/rqbit

Usenet clients with the same normalized approach:

• usenet shared types - @ctrl/shared-usenet
• nzbget - @ctrl/nzbget
• sabnzbd - @ctrl/sabnzbd

Start a test docker container

docker run -d \
  --name=qbittorrent \
  -e PUID=1000 \
  -e PGID=1000 \
  -e TZ=Etc/UTC \
  -e WEBUI_PORT=8080 \
  -p 8080:8080 \
  -p 6881:6881 \
  -p 6881:6881/udp \
  --restart unless-stopped \
  lscr.io/linuxserver/qbittorrent:latest
Copy

Start a test docker container for qBittorrent alpha

Use the official alpha image when testing against the newest WebAPI changes. The linuxserver latest image can lag behind the latest qBittorrent release.

mkdir -p /tmp/qbittorrent-alpha/config /tmp/qbittorrent-alpha/downloads

docker run -d \
  --name=qbittorrent-alpha \
  -e QBT_LEGAL_NOTICE=confirm \
  -e QBT_WEBUI_PORT=8080 \
  -e QBT_TORRENTING_PORT=6881 \
  -e PUID=1000 \
  -e PGID=1000 \
  -p 8080:8080 \
  -p 6881:6881 \
  -p 6881:6881/udp \
  -v /tmp/qbittorrent-alpha/config:/config \
  -v /tmp/qbittorrent-alpha/downloads:/downloads \
  qbittorrentofficial/qbittorrent-nox:alpha
Copy

The alpha image prints a temporary WebUI password in docker logs qbittorrent-alpha. Set the WebUI password to adminadmin before running the integration tests.