torx — a simple, fast torrent downloader

Download a torrent with one command. Files always go to your Downloads folder.

torx 'magnet:?xt=urn:btih:...'
torx ~/Downloads/movie.torrent

That's it. No options to learn, no folder to pick. Run, watch the progress bar, done.

---

Contents

• Install
• Using it
• Where things go
• Why it's fast
• How torx compares to µTorrent
• Troubleshooting
• Building a binary to share
• Project layout
• Contributing
• Disclaimer
• License

---

Install

# Requires Python 3.12 (libtorrent wheels don't exist for newer Python yet).
brew install uv         # one-time, macOS
cd torx
uv sync                 # one-time, installs everything
uv tool install --editable .   # optional: make `torx` runnable from anywhere

If you skipped the last step, prefix every command with uv run: uv run torx ....

Using it

Basic download

torx 'magnet:?xt=urn:btih:...'

You'll see a live progress display:

torx  — torrent downloader

Source:  magnet link (Sintel)
Saving:  /Users/you/Downloads

  ╭───────────────────────────────────────────────────────────────────╮
  │                                                                   │
  │  Sintel                                                           │
  │                                                                   │
  │  ████████████████░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░  35.2%    │
  │                                                                   │
  │      Status   Downloading                                         │
  │       Speed   1.7 MB/s                                            │
  │  Downloaded   45.5 MB of 129.3 MB                                 │
  │   Time left   about 1 minute                                      │
  │     Sharing   18 people, 12 have the full file                    │
  │                                                                   │
  ╰───────────────────────────────────────────────────────────────────╯

When it finishes:

Done!  Sintel
       129.3 MB saved to /Users/you/Downloads/Sintel

Pause and resume

Press Ctrl+C anytime — your progress is saved. Run the exact same command later (from any folder) and it continues where it left off.

Keep sharing after the download

torx 'magnet:...' --share

After the download finishes, torx keeps sharing the file with other people on the network. Press Ctrl+C to stop.

(BitTorrent works because everyone shares. --share is the friendly thing to do.)

Common situations

The magnet link won't paste? Wrap it in single quotes:

torx 'magnet:?xt=urn:btih:...'

Want to see what's happening under the hood?

torx 'magnet:...' --debug

Adds a "Technical details" panel: which port is open, how many DHT nodes are connected, which trackers are responding, the fastest peers, etc.

Need a different port? (Almost never — try --debug first to see if port 6881 isn't working.)

torx 'magnet:...' --port 16881

Scripting or want JSON output?

torx 'magnet:...' --json | jq -r '.progress'

Faster downloads of well-mirrored content (e.g. Linux ISOs): provide a direct HTTP mirror.

torx ubuntu.torrent --mirror 'https://releases.ubuntu.com/24.04/ubuntu-24.04-desktop-amd64.iso'

Watching while it downloads? Use --stream to prioritize the first and last pieces of the file so media players can preview right away.

torx 'magnet:...' --stream

Want to know if slowness is your link or the swarm? Use --speedtest to measure your network capacity before starting.

torx 'magnet:...' --speedtest

The progress display will show your current speed alongside the measured capacity (e.g. 1.2 MB/s (43% of 2.8 MB/s capacity)).

Where things go

• Downloads: ~/Downloads/<torrent name>/
• Resume state: ~/Library/Application Support/torx/resume/ (macOS), ~/.local/state/torx/resume/ (Linux), %LOCALAPPDATA%\torx\resume\ (Windows)
• Detailed log: ~/Library/Logs/torx/torx.log (macOS) / ~/.local/state/torx/torx.log (Linux) / %LOCALAPPDATA%\torx\Logs\torx.log (Windows)

Why it's fast

torx is built on libtorrent — the same engine inside qBittorrent and Deluge. It ships with download-throughput-focused settings out of the box:

What it tunes	Why
32 disk I/O threads, 16 hashing threads	Disk + SHA verification stop being the bottleneck on fast connections
Piece extent affinity	2–3× faster on spinning hard drives
4 MiB socket buffers (send + recv)	Removes the OS-level bandwidth-delay-product ceiling at >100 Mbps
16 MiB disk write queue	Smooths over fsync stalls at NVMe speeds
4 MiB per-peer recv buffer	Fast seeders can burst whole pieces without backpressure
Aggressive connection ramp + 60 s inactive-peer timeout	Reaches peak peer count fast; frees stuck slots fast
Per-torrent: 300 connections, 30 upload slots	Tit-for-tat: more upload slots = faster downloads
Webseed pipeline: 16 in-flight × 64 MiB requests	One CDN mirror can saturate a 1 Gbps line
DHT pre-warm on magnet links	Finds peers in seconds instead of waiting for trackers
2000 DHT peers per torrent	More candidates for under-tracked content
Announces to every tracker in every tier	More peer sources
Auto-augments public torrents with 6 curated trackers	More peers for under-tracked content
DHT + PEX + LSD + UPnP + NAT-PMP all on	Multiple peer-discovery channels
Encryption enabled both directions	Required by some swarms; harmless otherwise

Rarest-piece-first + endgame mode + memory-mapped disk I/O are libtorrent defaults.

How torx compares to µTorrent

torx is a command-line tool; µTorrent is a desktop GUI. They aren't drop-in replacements for each other, but if you're a µTorrent user weighing alternatives, here's an honest side-by-side.

Where torx is different

• No ads, no bundled offers, no telemetry. torx is MIT-licensed and ships nothing other than the downloader itself. By contrast, µTorrent's free Windows builds have been ad-supported for years, and in 2015 the installer bundled the "Epic Scale" cryptocurrency miner — a decision that drew significant public criticism at the time.
• One command. torx <magnet> is the entire interface. No first-run wizard, no settings panel, no upsells.
• Scriptable. --json output and clean exit codes make torx easy to chain in shell pipelines or CI jobs. µTorrent is GUI-first.
• Throughput-tuned out of the box — large socket buffers, generous disk queue, aggressive peer ramp (see Why it's fast). µTorrent's defaults are conservative.
• Modern macOS / Apple Silicon support. torx runs natively on Python 3.12 on Apple Silicon. µTorrent's macOS client has seen limited maintenance in recent years.
• Resumes anywhere. Re-run the same command from any folder and torx picks up where it left off — no "add torrent" dialog.

Where a GUI client wins

• A graphical dashboard for managing many torrents at once, with categories, labels, and right-click menus.
• Built-in RSS auto-download, scheduler, IP filtering, and a remote web UI.
• Discoverable for non-technical users — no terminal required.

Fairer comparisons

torx is more naturally compared against other CLI clients like aria2c or transmission-cli. If you want a GUI but share the concerns above about µTorrent's free builds, qBittorrent is a popular FOSS alternative — also built on libtorrent, no ads, actively maintained across macOS, Linux, and Windows.

µTorrent® is a trademark of Rainberry, Inc. References here are for comparison only; torx is not affiliated with, endorsed by, or sponsored by Rainberry, Inc. or BitTorrent, Inc.

Troubleshooting

libtorrent fails to install. Make sure you're on Python 3.12 — pre-built wheels do not exist for newer versions yet. With uv, run uv python install 3.12 and then uv sync again.

Slow or stuck at 0%. Run with --debug to see if peers are being discovered. If DHT nodes stay at 0, your firewall may be blocking UDP — try --port 16881 or open port 6881/UDP.

Resume doesn't work. Resume files live in your platform's state directory (see Where things go). Delete that folder to start fresh.

Magnet link contains & characters and the shell mangles it. Always wrap magnet links in single quotes.

Building a binary to share

uv add --dev pyinstaller
uv run pyinstaller --name torx --onefile --collect-all libtorrent src/torx/__main__.py
# Output: dist/torx (macOS/Linux) or dist/torx.exe (Windows)

For macOS distribution, code-sign and notarize the resulting binary. For Windows, a code-signing cert avoids most AV false positives.

Project layout

src/torx/
├── __init__.py
├── __main__.py        # entry point for `python -m torx`
├── cli.py             # typer CLI
├── downloader.py      # libtorrent session + Progress/Diagnostics
├── speedtest.py       # network capacity measurement
└── ui.py              # rich live display + welcome/done/error banners

Contributing

Contributions are welcome. For anything more than a typo fix, please open an issue first to discuss what you'd like to change.

1. Fork the repo and create a feature branch.
2. uv sync to install dependencies.
3. Make your change and test against a real torrent (the Sintel magnet is a good neutral test).
4. Open a PR with a clear description of the problem and the fix.

Disclaimer

torx is a general-purpose BitTorrent client. BitTorrent is a content-agnostic peer-to-peer protocol used to distribute Linux distributions, scientific datasets, public-domain media (e.g. the Internet Archive), and many other legitimate works.

You are responsible for ensuring you have the legal right to download and share any content you use this tool with. The authors and contributors do not host, endorse, or condone copyright infringement, and accept no liability for misuse.

License

Released under the MIT License.