unarr

⚠️ Beta — unarr is under active development. Features may change, and bugs are expected. Report issues here.

Powerful terminal tool for torrent search and management. Free and open source.

Search 30+ torrent sources, inspect torrent quality, discover popular content, find streaming providers, and manage your media collection — all from your terminal.

Installation

Quick install (Linux/macOS)

curl -fsSL https://get.torrentclaw.com/install.sh | sh

PowerShell (Windows)

irm https://get.torrentclaw.com/install.ps1 | iex

Homebrew (macOS/Linux)

brew install torrentclaw/tap/unarr

Docker

docker run -d --name unarr \
  --restart unless-stopped \
  --network host \
  --read-only --memory 512m \
  -v ~/.config/torrentclaw:/config \
  -v ~/Media:/downloads \
  torrentclaw/unarr

Run setup first to configure your API key:

docker run -it --rm \
  -v ~/.config/torrentclaw:/config \
  torrentclaw/unarr setup

Docker Compose

mkdir -p torrentclaw && cd torrentclaw
curl -fsSL https://raw.githubusercontent.com/torrentclaw/unarr/main/docker-compose.yml -o docker-compose.yml
docker compose up -d

docker-compose.yml

services:
  unarr:
    image: torrentclaw/unarr:latest
    container_name: unarr
    restart: unless-stopped
    user: "1000:1000"
    read_only: true
    tmpfs:
      - /tmp:size=64m,mode=1777
    volumes:
      - ./config:/config
      - ~/Media:/downloads
      - unarr-data:/data
    environment:
      - TZ=${TZ:-UTC}
      # - UNARR_API_KEY=tc_your_key_here
    deploy:
      resources:
        limits:
          memory: 512M
          cpus: "2.0"
    # Host network for full P2P performance
    network_mode: host
    # Or use bridge with ports:
    # ports:
    #   - "6881-6889:6881-6889/tcp"
    #   - "6881-6889:6881-6889/udp"

volumes:
  unarr-data:

Go install

go install github.com/torrentclaw/unarr/cmd/unarr@latest

GitHub Releases

Download prebuilt binaries for Linux, macOS, and Windows from GitHub Releases.

Build from source

git clone https://github.com/torrentclaw/unarr.git
cd unarr
make build

Quick Start

# 1. Run the init wizard (opens browser for API key)
unarr init

# 2. Search for content
unarr search "breaking bad" --type show --quality 1080p

# 3. Start the download daemon
unarr start

Commands

Getting Started

Command	Description
`unarr init`	First-time configuration wizard (API key, download dir, daemon)
`unarr config`	Edit all settings interactively (speed, organization, etc.)
`unarr migrate`	Import settings and wanted list from Sonarr/Radarr/Prowlarr [pre-beta]

Search & Discovery

Command	Description
`unarr search <query>`	Search for movies and TV shows with advanced filters
`unarr inspect <magnet\|hash\|name>`	TrueSpec analysis — quality, codec, seed health
`unarr popular`	Show popular movies and TV shows
`unarr recent`	Show recently added content
`unarr watch <query>`	Find where to watch — streaming + torrents

Downloads & Streaming

Command	Description
`unarr download <hash\|magnet>`	One-shot download (no daemon needed)
`unarr stream <hash\|magnet>`	Stream a torrent directly to mpv/vlc/browser

Daemon Management

Command	Description
`unarr start`	Start the download daemon (foreground)
`unarr stop`	How to stop the running daemon
`unarr status`	Show daemon status and active downloads
`unarr daemon install`	Install as system service (systemd/launchd)
`unarr daemon uninstall`	Remove the system service

System & Diagnostics

Command	Description
`unarr stats`	Show catalog statistics
`unarr doctor`	Diagnose configuration and connectivity
`unarr clean`	Remove temporary files, logs, and cached data
`unarr self-update`	Update unarr to the latest version
`unarr version`	Show version info
`unarr completion <shell>`	Generate shell completion scripts

Search

Search the catalog with advanced filters. Results include quality scores, seed health, and metadata from 30+ sources.

unarr search "inception" --sort seeders --min-rating 7 --lang es
unarr search "breaking bad" --type show --quality 1080p
unarr search "matrix" --json | jq '.results[].title'

Filters:

Flag	Description	Values
`--type`	Content type	`movie`, `show`
`--quality`	Video quality	`480p`, `720p`, `1080p`, `2160p`
`--lang`	Audio language (ISO 639)	`es`, `en`, `fr`, `de`, ...
`--genre`	Genre	`Action`, `Comedy`, `Drama`, `Horror`, ...
`--year-min`	Minimum release year	`2020`
`--year-max`	Maximum release year	`2026`
`--min-rating`	Minimum IMDb/TMDb rating	`0`-`10`
`--sort`	Sort order	`relevance`, `seeders`, `year`, `rating`, `added`
`--limit`	Results per page	`1`-`50`
`--page`	Page number	`1`, `2`, ...
`--country`	Country for streaming info	`US`, `ES`, `GB`, ...

Inspect

TrueSpec analysis — parse a torrent and show detailed quality specs.

unarr inspect "Oppenheimer.2023.1080p.BluRay.x265"
unarr inspect abc123def456abc123def456abc123def456abc1
unarr inspect "magnet:?xt=urn:btih:ABC123&dn=Movie.2023.1080p"

Accepts magnet URIs, 40-character info hashes, or torrent file names. Shows quality, codec, size, seeds, languages, source, quality score, health, and alternatives.

Watch

Find where to watch — streaming services alongside torrent options.

unarr watch "oppenheimer" --country ES
unarr watch "breaking bad" --json

Shows legal streaming options first (subscription, free, rent, buy), then torrent alternatives.

Stream

Stream a torrent directly to a media player without waiting for the full download.

unarr stream abc123def456abc123def456abc123def456abc1
unarr stream "magnet:?xt=urn:btih:..." --port 8080
unarr stream <hash> --player mpv
unarr stream <hash> --no-open   # just print the URL

Downloads pieces sequentially and serves the video over a local HTTP server. Auto-detects mpv, vlc, or your default browser.

Download

One-shot download by info hash or magnet link (no daemon required).

unarr download abc123def456abc123def456abc123def456abc1
unarr download "magnet:?xt=urn:btih:..." --method torrent

Daemon

The daemon receives download tasks from the web dashboard and executes them automatically.

# Start in foreground (Ctrl+C to stop)
unarr start

# Or install as a system service (auto-starts on boot)
unarr daemon install

# Check status
unarr status

# Uninstall the service
unarr daemon uninstall

The daemon connects via WebSocket for instant task delivery, with automatic HTTP fallback. It supports torrent, debrid, and usenet downloads concurrently, reports progress to the web dashboard, and handles graceful shutdown.

Service locations:

Linux: ~/.config/systemd/user/unarr.service (systemd)
macOS: ~/Library/LaunchAgents/com.torrentclaw.unarr.plist (launchd)

Diagnostics

# Run all diagnostic checks
unarr doctor

# Update to the latest version
unarr self-update
unarr self-update --force   # reinstall even if up to date

unarr doctor checks: config file, API key, server connectivity (with latency), agent registration, download directory, disk space, and version.

Clean

Remove temporary files, logs, resume data, and other artifacts generated by unarr. Shows what will be removed and asks for confirmation before deleting.

unarr clean            # Show files and confirm before removing
unarr clean --dry-run  # Show what would be removed (no prompt)
unarr clean --yes      # Skip confirmation
unarr clean --all      # Also remove the data directory

Cleans: log files, daemon state, stale usenet resume files (> 7 days), stream temp data, upgrade temp files, and stale atomic-write temps. Recent resume files are kept to preserve download progress for paused or interrupted downloads. Never removes your config file, downloaded media, or partial torrent/debrid downloads.

Alias (optional)

Create a shell alias for shorter commands:

# Add to ~/.bashrc or ~/.zshrc
alias un=unarr

# Then use:
un search "breaking bad" --type show
un popular --limit 5
un start

Global Flags

Flag	Description
`--json`	Output as JSON (for piping to `jq`, scripts)
`--no-color`	Disable colored output
`--api-key`	API key (overrides config file and env)
`--config`	Custom config file path

JSON Output

All query commands support --json for scripting:

# Pipe to jq
unarr search "matrix" --json | jq '.results[].title'

# Save to file
unarr popular --json > popular.json

# Use in scripts
SEEDS=$(unarr search "inception" --json | jq '.results[0].torrents[0].seeders')

Configuration

Config file

Location: ~/.config/unarr/config.toml

[auth]
api_key = "tc_your_api_key_here"
api_url = "https://torrentclaw.com"

[agent]
id = "auto-generated-uuid"
name = "My PC"

[downloads]
dir = "~/Media"
preferred_method = "auto"        # auto | torrent | debrid | usenet
max_concurrent = 3
max_download_speed = "0"         # e.g. "10MB", "500KB", "0" = unlimited
max_upload_speed = "0"

[organize]
enabled = true
movies_dir = "~/Media/Movies"
tv_shows_dir = "~/Media/TV Shows"

[daemon]
poll_interval = "30s"
heartbeat_interval = "30s"

[notifications]
enabled = true

[general]
country = "US"

Environment variables

Environment variables override config file values:

export UNARR_API_KEY=tc_your_api_key
export UNARR_API_URL=https://torrentclaw.com
export UNARR_COUNTRY=ES
export UNARR_DOWNLOAD_DIR=~/Media

Speed limits

Speed limits use human-readable format:

max_download_speed = "10MB"    # 10 megabytes/sec
max_upload_speed = "1MB"       # 1 megabyte/sec
max_download_speed = "500KB"   # 500 kilobytes/sec
max_download_speed = "0"       # unlimited (default)

Shell Completion

Generate tab-completion scripts for your shell:

# Bash — add to ~/.bashrc
eval "$(unarr completion bash)"

# Zsh — add to ~/.zshrc
eval "$(unarr completion zsh)"

# Fish
unarr completion fish > ~/.config/fish/completions/unarr.fish

# PowerShell — add to $PROFILE
unarr completion powershell >> $PROFILE

Completions provide tab-completion for commands, flags, and flag values (e.g. --type <Tab> shows movie and show).

Coming Soon

These commands are planned for future releases:

Command	Description
`unarr upgrade`	Find a better version of a torrent
`unarr moreseed`	Find same quality with more seeders
`unarr compare`	Compare two torrents side by side
`unarr scan`	Scan your media library for upgrades
`unarr add`	Search and add torrents to your client
`unarr monitor`	Watch for new episodes of a series
`unarr open`	Open content in the browser

Contributing

See CONTRIBUTING.md for development setup, code style, and guidelines.

License

MIT License — see LICENSE for details.

Name		Name	Last commit message	Last commit date
Latest commit History 69 Commits
.github		.github
.lefthook/commit-msg		.lefthook/commit-msg
cmd/unarr		cmd/unarr
internal		internal
scripts		scripts
.dockerignore		.dockerignore
.gitignore		.gitignore
.golangci.yml		.golangci.yml
.goreleaser.yml		.goreleaser.yml
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
DOCKERHUB.md		DOCKERHUB.md
Dockerfile		Dockerfile
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
SECURITY.md		SECURITY.md
cliff.toml		cliff.toml
docker-build.sh		docker-build.sh
docker-compose.yml		docker-compose.yml
go.mod		go.mod
go.sum		go.sum
install.ps1		install.ps1
install.sh		install.sh
lefthook.yml		lefthook.yml

Folders and files

Latest commit

History

Repository files navigation

unarr

Installation

Quick install (Linux/macOS)

PowerShell (Windows)

Homebrew (macOS/Linux)

Docker

Docker Compose

Go install

GitHub Releases

Build from source

Quick Start

Commands

Getting Started

Search & Discovery

Downloads & Streaming

Daemon Management

System & Diagnostics

Search

Inspect

Watch

Stream

Download

Daemon

Diagnostics

Clean

Alias (optional)

Global Flags

JSON Output

Configuration

Config file

Environment variables

Speed limits

Shell Completion

Coming Soon

Contributing

License

About

Resources

License

Code of conduct

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 10

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages