Torrra: a torrent client with a Textual interface and a Jackett backend

A client assembled from an indexer and libtorrent

Torrra is described as a Python tool that lets you search and download torrents without leaving your CLI, and the project summary is more precise about what it is: a streamlined command line interface for torrent search and downloads, powered by Jackett or Prowlarr and by libtorrent, built with Textual, offering a TUI with pause and resume support. The three-way split explains the whole design. The indexer is not part of Torrra, it is Jackett or Prowlarr, which do the searching against trackers and expose an HTTP API. The transfer engine is libtorrent, the same library that underpins many other clients, bound here through libtorrent-python. The user interface is Textual, which is why the result is a full screen interface rather than a handful of prompts. The audience is someone who wants a terminal client and is willing to run an indexer service alongside it, because the tool is not a tracker scraper and does not talk to trackers directly.

One command to install, several other routes

The install is a single command, and the project is explicit that it wants to live in an isolated environment rather than in your project virtualenv:

uv tool install torrra
# or pipx install torrra

Beyond that, the documentation lists the other supported routes, and there are several: WinGet, an AUR package, a Homebrew formula, standalone binaries from the releases page, and a Docker image. The choice matters more than usual here because of the libtorrent dependency, which is a compiled library rather than a pure Python package, and a native build is a different proposition on each platform. The presence of a Homebrew formula maintained outside the project, a Nix flake in the repository with flake.nix and flake.lock, a package.nix, a pkgbuild-template/ directory for the Arch build, a torrra.spec for a PyInstaller-style build, an install.ps1 for Windows, and a Dockerfile with a separate Dockerfile.dev for development, is a good sign of how seriously the packaging is taken. The upstream project keeps a readthedocs site for the installation options, and the Docker image is published as stabldev/torrra.

Three ways to run it, from interactive to scriptable

The usage guide splits into three modes, and the distinction matters if you are scripting. The interactive mode launches the interface with an indexer, and the indexer can be named or given its details:

torrra # if default indexer is configured
# or torrra jackett
# or torrra jackett --url http://localhost:9117 --api-key <your_api_key>

The direct search mode bypasses the welcome screen and searches from the command line, which is the mode you want in a script:

torrra search "arch linux iso"
# or torrra search "arch linux iso" --no-cache

The direct download mode takes a magnet URI, a URL or a local .torrent file and starts the transfer without any searching step:

torrra download "magnet:?xt=urn:btih:..."
# or torrra download "/path/to/file.torrent"
# choose a destination for this torrent
torrra download "magnet:?xt=urn:btih:..." --save-path /downloads/linux

That last form is the one to remember, because a torrent client that puts everything in one directory is a library you will regret. The feature list notes that you can choose and persist a separate download directory for each torrent.

config.toml, and making an indexer the default

Persistent settings live in a config.toml file, where you configure your indexers, download paths and themes, and the point of the file is to avoid passing arguments on every run. The commands are the same shape as the rest of the CLI:

# set your Jackett URL and API key
torrra config set indexers.jackett.url http://localhost:9117
torrra config set indexers.jackett.api_key <your_api_key>

# set Jackett as the default indexer
torrra config set indexers.default jackett

After that, running torrra with no arguments uses the default indexer and lands in the interface. The structure of those keys is informative, because the same dotted path handles indexers, download paths and themes, so the configuration is one namespace rather than a set of ad hoc files. Two related features round it out. Caching is opt-in, which is why the search command has a --no-cache switch, and the search results can be sorted by seeders, size, title or leechers, with dead torrents hidden, which is the difference between a useful index and a wall of entries with zero seeds. The dependency list explains the caching choice: diskcache is a direct dependency, so the cache is on disk rather than in memory, and it survives restarts.

The container pair, and what the compose file reveals

The repository's compose file is the clearest description of the intended deployment, because it puts the client and its indexer side by side. The torrra service is built from the Dockerfile.dev context with stdin_open and tty enabled, which is what a Textual interface needs to attach to a terminal, and it keeps a named volume for the configuration at /root/.config. There is a commented-out line for mounting a downloads directory, which tells you the container's download location is something you have to wire up yourself. The jackett service runs the linuxserver/jackett image, publishes port 9117, keeps its own config volume and restarts unless stopped. The separation of the two volumes, one for the client and one for the indexer, is the point: the indexer has state of its own and should not be reset when you clear the client's settings. The application image itself is careful about how it runs, building on python:3.13-slim with uv installing the dependencies, and the runtime stage creating a non-root user with uid 1000, switching to it, and setting the entrypoint to the torrra command.

The dependency set, and the one that matters

The runtime dependencies are short and reveal the design. click handles the command line, textual provides the interface framework, httpx makes the HTTP calls to the indexer, diskcache provides the on-disk cache, platformdirs locates the configuration directory, libtorrent is the transfer engine, and tomli-w writes the configuration file with tomli pulled in only for Python versions below 3.11. That last detail is a small sign of care about supporting older interpreters, and the metadata reflects the same intent with a requires-python of 3.10 and classifiers for 3.10 through 3.14, an operating system classifier of OS Independent, and a console environment classification. The package is published to PyPI with the console script torrra mapped to torrra.__main__:cli, and the project requires Python 3.10 or newer. The repository also carries a development container, a compose file for the development environment, a pre-commit configuration, a uv lock file and an exported requirements.txt with hashes, which is what a project that publishes to PyPI and to distribution packaging channels tends to look like.

Where Torrra is the wrong tool

Four limits are clear. The first is that Torrra is not a self-contained client. It needs Jackett or Prowlarr running somewhere, which means an extra service, an API key, and the operational surface of a tracker indexer that will quietly fall out of date as trackers change. If you want one process that searches trackers itself, this is not it. The second is scope. The feature list covers search, download, pause and resume, per-torrent download directories, themes, caching and sorting, and it is a client rather than a library or a server, so there is no remote control, no web interface, no RSS feed generation and no media organisation. The third is the legal weight, which the tool does not mention and which is worth stating plainly. A torrent client will download whatever a magnet link or a tracker entry points at, and the responsibility for what that is sits with the operator, not with the library that moves the bytes. Nothing in the project verifies the legality of a download, and a search client that makes finding material easy makes misuse easy too. The fourth is the libtorrent dependency, which makes the install heavier than a pure Python client would be and is the reason the project ships so many installation routes.

Editorial conclusion

Adopt Torrra if you want torrent search and download in the terminal, you already run Jackett or Prowlarr, and you are comfortable with the pieces it assembles. Do not adopt it as a media server, a seeding client for a tracker, or anything that manages a library of files you do not have the right to fetch, since the tool is neutral about that and the responsibility is yours. Before you install, check the Python floor of 3.10 and the libtorrent dependency, which is the heaviest thing in the install, and note that the current release is v2.5.1 from 2026-10-05 with the last push on 2026-10-12.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. stabldev/torrra on GitHub