# `torrra`
> A Python tool that lets you find and download torrents without leaving your CLI.
[](https://pypi.org/project/torrra/)
[](https://aur.archlinux.org/packages/torrra)
[](https://github.com/stabldev/torrra/releases)
[](https://github.com/stabldev/torrra/blob/main/LICENSE)
[](https://github.com/stabldev/torrra/issues)
## Overview
`torrra` provides a streamlined command-line interface for your torrent needs. It allows you to search for and download torrents, and manage active downloads without leaving your terminal, offering a fast and efficient solution for command-line users.
## Table of Contents
- [Features](#features)
- [Installation](#installation)
- [Cross-Platform](#cross-platform-recommended)
- [Arch Linux](#arch-linux)
- [Standalone Binaries](#standalone-binaries-no-python-required)
- [Docker](#docker)
- [Local Development](#local-development)
- [Usage](#usage)
- [CLI Commands & Flags](#cli-commands--flags)
- [TUI Controls](#tui-controls)
- [Configuration](#configuration)
- [Managing Your Configuration](#managing-your-configuration)
- [Config Options](#config-options)
- [Indexer Support](#indexer-support)
- [Roadmap](#roadmap)
- [Contributing](#contributing)
- [License](#license)
## Features
- Integrate with services like [`Jackett`](https://github.com/Jackett/Jackett) and [`Prowlarr`](https://github.com/Prowlarr/Prowlarr).
- Fetch and download magnet links directly, powered by [`Libtorrent`](https://libtorrent.org/).
- A responsive download manager built with [`Textual`](https://textual.textualize.io/).
- Pause and resume torrent downloads using keyboard shortcuts.
- Operates as both a `CLI` tool and a full-screen terminal `UI`.
- Toggle between dark and light themes.
## Installation
`torrra` offers several installation methods to suit your environment.
### Cross-Platform (recommended)
Using `pipx` ensures `torrra` is installed in an isolated environment, preventing conflicts with your system's Python packages.
```bash
pipx install torrra
```
> This method supports **Linux**, **macOS**, and **Windows**. `libtorrent` is installed automatically via pip.
### Arch Linux
1. **From AUR (builds from source):**
```bash
yay -S torrra
```
2. **From AUR Binary Package (faster installation):**
```bash
yay -S torrra-bin
```
> `torrra-bin` includes a precompiled standalone binary for x86_64 Linux, requiring no Python dependencies.
### Standalone Binaries (No Python Required)
Download pre-built executables directly from [GitHub Releases](https://github.com/stabldev/torrra/releases):
| OS | File |
| :------ | :--------------------------- |
| Linux | `torrra-vX.Y.Z-linux-x86_64` |
| Windows | `torrra-vX.Y.Z-windows.exe` |
| macOS | `torrra-vX.Y.Z-macos-x86_64` |
> On Linux/macOS, ensure the binary is executable: `chmod +x torrra-vX.Y.Z-*-x86_64`.
### Docker
`torrra` is also available as a Docker image, allowing you to run it in an isolated environment without installing Python dependencies directly on your host system.
The official image is hosted on Docker Hub: [`stabldev/torrra`](https://hub.docker.com/r/stabldev/torrra).
#### Quick Usage
```bash
docker run --rm -it stabldev/torrra:latest --jackett
```
> Replace `--jackett` with your preferred provider flag. You can also pass URL and API key directly: `--jackett http://localhost:9117 your_api_key`.
> You must mount any required config or download directories if needed.
#### With Config and Downloads Folder Mounted
```bash
docker run --rm -it \
-v ~/.config/torrra:/root/.config/torrra \
-v ~/Downloads:/downloads \
stabldev/torrra:latest --jackett
```
> Ensure your `config.toml` inside `~/.config/torrra` is set up correctly.
#### Image Tags
- `stabldev/torrra:latest` - always points to the latest release
- `stabldev/torrra:<version>` - for a specific release (e.g., `x.y.z`)
### Local Development
To set up `torrra` for development:
```bash
git clone https://github.com/stabldev/torrra
cd torrra
uv sync # or `pip install -e .`
uv run torrra
```
## Usage
To start `torrra`, you must specify a provider. For example, to use [`Jackett`](https://github.com/Jackett/Jackett):
```bash
torrra --jackett
```
> Uses Jackett with credentials from your saved configuration.
Or pass your own `URL` and `API_KEY` directly. For example, to use [`Prowlarr`](https://github.com/Prowlarr/Prowlarr):
```bash
torrra --prowlarr http://localhost:9696 your_api_key
```
> Omitting a provider flag will result in an error.
### CLI Commands & Flags
#### Top-level commands
| Command | Description |
| :-------------- | :------------------------------------------- |
| `torrra` | Launches the interactive TUI |
| `torrra config` | Manages configuration settings |
| `torrra --help` | Displays help for the top-level CLI commands |
#### Provider flags (used with `torrra`)
| Flag | Description |
| :----------------- | :---------------------------------------------------------------------------- |
| `-h`, `--help` | Displays help for the main application |
| `-v`, `--version` | Shows the current `torrra` version |
| `-j`, `--jackett` | Uses Jackett as the torrent indexer. Optionally accepts `URL` and `API_KEY`. |
| `-p`, `--prowlarr` | Uses Prowlarr as the torrent indexer. Optionally accepts `URL` and `API_KEY`. |
### TUI Controls
| Key | Action |
| :------ | :--------------------------- |
| `↑↓` | Navigate through results |
| `Tab` | Focus the next widget |
| `Enter` | Start download for selection |
| `p` | Pause the current download |
| `r` | Resume a paused download |
| `q` | Quit `torrra` |
## Configuration
`torrra`'s behavior can be customized via a `config.toml` file located in your OS-specific user config directory:
- **Linux/macOS:** `~/.config/torrra/config.toml`
- **Windows:** `%APPDATA%\torrra\config.toml`
> The actual path is automatically resolved using [`platformdirs`](https://pypi.org/project/platformdirs/).
Example `config.toml`:
```toml
[general]
download_path = "/home/username/Downloads" # Default folder for saving torrents
remember_last_path = true # Reuse the last used path as default
```
### Managing Your Configuration
Use the built-in `torrra config` command to manage settings:
```bash
torrra config -g general.download_path # Get a specific config value
torrra config -s general.remember_last_path False # Set a key-value pair
torrra config -l # List all config settings
```
#### Config Options
| Flag | Description |
| :---------------------- | :------------------------------------------------------- |
| `-g`, `--get KEY` | Retrieves a config value (e.g., `general.download_path`) |
| `-s`, `--set KEY VALUE` | Sets a key-value pair |
| `-l`, `--list` | Lists all configuration settings |
| `-h`, `--help` | Displays help for the config command |
## Indexer Support
Currently supported:
- [`Jackett`](https://github.com/Jackett/Jackett) (via `--jackett` or `-j`)
- [`Prowlarr`](https://github.com/Prowlarr/Prowlarr) (via `--prowlarr` or `-p`)
Planned:
- Support for custom indexers
## Roadmap
Ongoing development focuses on enhancing `torrra`'s capabilities:
- [x] Jackett integration
- [x] Prowlarr support
- [x] Torrent download `UI` with pause/resume
- [x] Config file support
- [x] Standalone binary & AUR packaging
- [x] Magnet info preview (seeders/leechers before download)
- [ ] Advanced filtering/sorting
- [ ] Nyaa & anime-specific indexers
- [ ] Keyboard shortcuts overlay / help screen
## Contributing
`torrra` is an open-source project, and contributions are highly valued.
- If you find an issue, please [open an issue](https://github.com/stabldev/torrra/issues) with detailed steps to reproduce.
- We welcome new features or indexer integrations. Fork the repository and submit a Pull Request.
- General feedback and feature requests are always appreciated.
## License
**MIT License.** Copyright (c) [stabldev](https://github.com/stabldev)
Raw data
{
"_id": null,
"home_page": null,
"name": "torrra",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.13",
"maintainer_email": null,
"keywords": "cli, download, filesharing, jackett, libtorrent, magnet, p2p, terminal, textual, torrent, torrent-client, torrent-search, tui",
"author": null,
"author_email": "stabldev <thestabldev@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/40/57/363906fbc34fe833be104babcb585ed35ed059a4144dbeb5d91c27efa53b/torrra-1.1.1.tar.gz",
"platform": null,
"description": "# `torrra`\n\n> A Python tool that lets you find and download torrents without leaving your CLI.\n\n[](https://pypi.org/project/torrra/)\n[](https://aur.archlinux.org/packages/torrra)\n[](https://github.com/stabldev/torrra/releases)\n[](https://github.com/stabldev/torrra/blob/main/LICENSE)\n[](https://github.com/stabldev/torrra/issues)\n\n\n\n## Overview\n\n`torrra` provides a streamlined command-line interface for your torrent needs. It allows you to search for and download torrents, and manage active downloads without leaving your terminal, offering a fast and efficient solution for command-line users.\n\n## Table of Contents\n\n- [Features](#features)\n- [Installation](#installation)\n - [Cross-Platform](#cross-platform-recommended)\n - [Arch Linux](#arch-linux)\n - [Standalone Binaries](#standalone-binaries-no-python-required)\n - [Docker](#docker)\n - [Local Development](#local-development)\n- [Usage](#usage)\n - [CLI Commands & Flags](#cli-commands--flags)\n - [TUI Controls](#tui-controls)\n- [Configuration](#configuration)\n - [Managing Your Configuration](#managing-your-configuration)\n - [Config Options](#config-options)\n- [Indexer Support](#indexer-support)\n- [Roadmap](#roadmap)\n- [Contributing](#contributing)\n- [License](#license)\n\n## Features\n\n- Integrate with services like [`Jackett`](https://github.com/Jackett/Jackett) and [`Prowlarr`](https://github.com/Prowlarr/Prowlarr).\n- Fetch and download magnet links directly, powered by [`Libtorrent`](https://libtorrent.org/).\n- A responsive download manager built with [`Textual`](https://textual.textualize.io/).\n- Pause and resume torrent downloads using keyboard shortcuts.\n- Operates as both a `CLI` tool and a full-screen terminal `UI`.\n- Toggle between dark and light themes.\n\n## Installation\n\n`torrra` offers several installation methods to suit your environment.\n\n### Cross-Platform (recommended)\n\nUsing `pipx` ensures `torrra` is installed in an isolated environment, preventing conflicts with your system's Python packages.\n\n```bash\npipx install torrra\n```\n\n> This method supports **Linux**, **macOS**, and **Windows**. `libtorrent` is installed automatically via pip.\n\n### Arch Linux\n\n1. **From AUR (builds from source):**\n\n```bash\nyay -S torrra\n```\n\n2. **From AUR Binary Package (faster installation):**\n\n```bash\nyay -S torrra-bin\n```\n\n> `torrra-bin` includes a precompiled standalone binary for x86_64 Linux, requiring no Python dependencies.\n\n### Standalone Binaries (No Python Required)\n\nDownload pre-built executables directly from [GitHub Releases](https://github.com/stabldev/torrra/releases):\n\n| OS | File |\n| :------ | :--------------------------- |\n| Linux | `torrra-vX.Y.Z-linux-x86_64` |\n| Windows | `torrra-vX.Y.Z-windows.exe` |\n| macOS | `torrra-vX.Y.Z-macos-x86_64` |\n\n> On Linux/macOS, ensure the binary is executable: `chmod +x torrra-vX.Y.Z-*-x86_64`.\n\n### Docker\n\n`torrra` is also available as a Docker image, allowing you to run it in an isolated environment without installing Python dependencies directly on your host system.\n\nThe official image is hosted on Docker Hub: [`stabldev/torrra`](https://hub.docker.com/r/stabldev/torrra).\n\n#### Quick Usage\n\n```bash\ndocker run --rm -it stabldev/torrra:latest --jackett\n```\n\n> Replace `--jackett` with your preferred provider flag. You can also pass URL and API key directly: `--jackett http://localhost:9117 your_api_key`.\n> You must mount any required config or download directories if needed.\n\n#### With Config and Downloads Folder Mounted\n\n```bash\ndocker run --rm -it \\\n -v ~/.config/torrra:/root/.config/torrra \\\n -v ~/Downloads:/downloads \\\n stabldev/torrra:latest --jackett\n```\n\n> Ensure your `config.toml` inside `~/.config/torrra` is set up correctly.\n\n#### Image Tags\n\n- `stabldev/torrra:latest` - always points to the latest release\n- `stabldev/torrra:<version>` - for a specific release (e.g., `x.y.z`)\n\n### Local Development\n\nTo set up `torrra` for development:\n\n```bash\ngit clone https://github.com/stabldev/torrra\ncd torrra\nuv sync # or `pip install -e .`\nuv run torrra\n```\n\n## Usage\n\nTo start `torrra`, you must specify a provider. For example, to use [`Jackett`](https://github.com/Jackett/Jackett):\n\n```bash\ntorrra --jackett\n```\n\n> Uses Jackett with credentials from your saved configuration.\n\nOr pass your own `URL` and `API_KEY` directly. For example, to use [`Prowlarr`](https://github.com/Prowlarr/Prowlarr):\n\n```bash\ntorrra --prowlarr http://localhost:9696 your_api_key\n```\n\n> Omitting a provider flag will result in an error.\n\n### CLI Commands & Flags\n\n#### Top-level commands\n\n| Command | Description |\n| :-------------- | :------------------------------------------- |\n| `torrra` | Launches the interactive TUI |\n| `torrra config` | Manages configuration settings |\n| `torrra --help` | Displays help for the top-level CLI commands |\n\n#### Provider flags (used with `torrra`)\n\n| Flag | Description |\n| :----------------- | :---------------------------------------------------------------------------- |\n| `-h`, `--help` | Displays help for the main application |\n| `-v`, `--version` | Shows the current `torrra` version |\n| `-j`, `--jackett` | Uses Jackett as the torrent indexer. Optionally accepts `URL` and `API_KEY`. |\n| `-p`, `--prowlarr` | Uses Prowlarr as the torrent indexer. Optionally accepts `URL` and `API_KEY`. |\n\n### TUI Controls\n\n| Key | Action |\n| :------ | :--------------------------- |\n| `\u2191\u2193` | Navigate through results |\n| `Tab` | Focus the next widget |\n| `Enter` | Start download for selection |\n| `p` | Pause the current download |\n| `r` | Resume a paused download |\n| `q` | Quit `torrra` |\n\n## Configuration\n\n`torrra`'s behavior can be customized via a `config.toml` file located in your OS-specific user config directory:\n\n- **Linux/macOS:** `~/.config/torrra/config.toml`\n- **Windows:** `%APPDATA%\\torrra\\config.toml`\n\n> The actual path is automatically resolved using [`platformdirs`](https://pypi.org/project/platformdirs/).\n\nExample `config.toml`:\n\n```toml\n[general]\ndownload_path = \"/home/username/Downloads\" # Default folder for saving torrents\nremember_last_path = true # Reuse the last used path as default\n```\n\n### Managing Your Configuration\n\nUse the built-in `torrra config` command to manage settings:\n\n```bash\ntorrra config -g general.download_path # Get a specific config value\ntorrra config -s general.remember_last_path False # Set a key-value pair\ntorrra config -l # List all config settings\n```\n\n#### Config Options\n\n| Flag | Description |\n| :---------------------- | :------------------------------------------------------- |\n| `-g`, `--get KEY` | Retrieves a config value (e.g., `general.download_path`) |\n| `-s`, `--set KEY VALUE` | Sets a key-value pair |\n| `-l`, `--list` | Lists all configuration settings |\n| `-h`, `--help` | Displays help for the config command |\n\n## Indexer Support\n\nCurrently supported:\n\n- [`Jackett`](https://github.com/Jackett/Jackett) (via `--jackett` or `-j`)\n- [`Prowlarr`](https://github.com/Prowlarr/Prowlarr) (via `--prowlarr` or `-p`)\n\nPlanned:\n\n- Support for custom indexers\n\n## Roadmap\n\nOngoing development focuses on enhancing `torrra`'s capabilities:\n\n- [x] Jackett integration\n- [x] Prowlarr support\n- [x] Torrent download `UI` with pause/resume\n- [x] Config file support\n- [x] Standalone binary & AUR packaging\n- [x] Magnet info preview (seeders/leechers before download)\n- [ ] Advanced filtering/sorting\n- [ ] Nyaa & anime-specific indexers\n- [ ] Keyboard shortcuts overlay / help screen\n\n## Contributing\n\n`torrra` is an open-source project, and contributions are highly valued.\n\n- If you find an issue, please [open an issue](https://github.com/stabldev/torrra/issues) with detailed steps to reproduce.\n- We welcome new features or indexer integrations. Fork the repository and submit a Pull Request.\n- General feedback and feature requests are always appreciated.\n\n## License\n\n**MIT License.** Copyright (c) [stabldev](https://github.com/stabldev)\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A Python tool that lets you find and download torrents without leaving your CLI.",
"version": "1.1.1",
"project_urls": {
"Bug Tracker": "https://github.com/stabldev/torrra/issues",
"homepage": "https://github.com/stabldev/torrra",
"repository": "https://github.com/stabldev/torrra"
},
"split_keywords": [
"cli",
" download",
" filesharing",
" jackett",
" libtorrent",
" magnet",
" p2p",
" terminal",
" textual",
" torrent",
" torrent-client",
" torrent-search",
" tui"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "43526ea33331efa8f7f0362e147921c1251eb4a4d7ef4556de367b107f3c1285",
"md5": "da5eda5a793518b6ed9016fe002a7810",
"sha256": "cc4bf0924835a3d8df15950743e6a8c0b99476601d633d22fc0d665a5b090ed2"
},
"downloads": -1,
"filename": "torrra-1.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "da5eda5a793518b6ed9016fe002a7810",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.13",
"size": 20460,
"upload_time": "2025-07-23T08:12:40",
"upload_time_iso_8601": "2025-07-23T08:12:40.221728Z",
"url": "https://files.pythonhosted.org/packages/43/52/6ea33331efa8f7f0362e147921c1251eb4a4d7ef4556de367b107f3c1285/torrra-1.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "4057363906fbc34fe833be104babcb585ed35ed059a4144dbeb5d91c27efa53b",
"md5": "b43482868047d0712f09de346725a32c",
"sha256": "3535d125bd992e7a4845d15cace50e647f08d8083a1455cb8a58d0234e7456dc"
},
"downloads": -1,
"filename": "torrra-1.1.1.tar.gz",
"has_sig": false,
"md5_digest": "b43482868047d0712f09de346725a32c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.13",
"size": 865417,
"upload_time": "2025-07-23T08:12:41",
"upload_time_iso_8601": "2025-07-23T08:12:41.765536Z",
"url": "https://files.pythonhosted.org/packages/40/57/363906fbc34fe833be104babcb585ed35ed059a4144dbeb5d91c27efa53b/torrra-1.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-23 08:12:41",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "stabldev",
"github_project": "torrra",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "torrra"
}
JSON
