Skip to Content
DocsApplicationsDownload ClientsrTorrent
rTorrent

rTorrent

High-performance ncurses BitTorrent client with Unix socket SCGI

rTorrent is a quick and efficient BitTorrent client built on the libTorrent library (not to be confused with libtorrent-rasterbar). Written in C++ with an ncurses text interface, rTorrent excels at headless operation via screen sessions and XMLRPC/SCGI for remote control. QuickBox Pro globally installs rTorrent with dynamic multi-version support and per-user configuration via Unix sockets.

High Performance

Lightweight C++ client optimized for high-speed, low-resource torrenting

Unix Socket SCGI

Per-user Unix sockets for secure XMLRPC communication

Screen Sessions

Runs in detached screen for headless operation with attach support

Dynamic Versions

Available versions resolved from the compiled-packages manifest — no manual database updates needed

Nginx SCGI Proxy

Secure nginx reverse proxy to Unix sockets with SSL and authentication

Web UI Ready

Works with ruTorrent and Flood for web-based management

Global Installation

rTorrent is a globally installed application available to all users on the server. Each user gets their own configuration, session, and Unix socket for isolation.

Installation

Install from the Dashboard

Open App Dashboard → Package Management (/dashboard?mode=packages), find rTorrent in the catalog (browse Download Clients or search), and click Install. The install dialog lets you pick the rTorrent version — the available builds are resolved from the compiled-packages catalog for your distro, and the matching libtorrent-rakshasa version is paired automatically. The dashboard streams the install log live and rTorrent appears in your Application Control panel when it finishes. Reinstall, Update, and Remove are available from the same panel.

What you see and can manage is gated by your account: admins manage any user’s apps; regular users manage their own. See Channels & Versions for how version resolution and beta channels work, and App Management for the full package flow.

Install from the CLI (automation)

The CLI runs the same install and is suited to automation and scripting. Without a version it installs the latest available build; pass -o to pin a specific version:

qb install rtorrent -u username
qb install rtorrent -u username -o '0.16.7'

The paired libtorrent-rakshasa version is resolved automatically for the version you select (e.g., -o '0.10.0' installs libtorrent 0.14.0, -o '0.9.8' installs libtorrent 0.13.8).

CLI Commands

Command
qb install rtorrent -u username
Description
Install rTorrent with the latest available version
Command
qb install rtorrent -u username -o '0.16.7'
Description
Install a specific rTorrent version
Command
qb reinstall rtorrent -u username
Description
Reinstall while preserving QuickBox integration
Command
qb update rtorrent -u username -o '0.16.5'
Description
Update rTorrent to a specific version
Command
qb remove rtorrent -u username
Description
Remove rTorrent and clean up files
Command
qb help rtorrent
Description
Display comprehensive help information

CLI Options

-u, --usernameRequired

Supply Admin username for install/reinstall/remove/update operations

-o

Specify rTorrent version to install or update to (e.g., -o '0.16.7'). Available versions are resolved dynamically from the compiled-packages manifest.

Available Versions

Available versions are resolved dynamically from the compiled-packages catalog for your distro and update automatically as new builds are published.

Current versions include: 0.16.7This is the current recommended version, 0.16.5, 0.16.2, 0.16.1, 0.16.0, 0.15.1, 0.10.0, 0.9.8, 0.9.7, 0.9.6These versions are not recommended for new installs and will eventually be removed, and feature-bind (builds from the latest master branch commit).

Debian 13+ Compatibility

Debian 13 (Trixie) and later only support rTorrent 0.9.8 and higher. Versions 0.9.7 and 0.9.6 are not compatible due to libtorrent dependencies.

Hide Update (Dashboard)

When a newer rTorrent version is available in the compiled-packages manifest, the v4 dashboard shows an update badge on the rTorrent app card. Non-admin users do not see this badge (the hideUpdateForNonAdmin flag is set for rTorrent). Any user can dismiss the update notification for their account via the dashboard, and it will reappear only when a newer version becomes available.

Accessing rTorrent

rTorrent itself has no web interface—use ruTorrent or Flood for web-based management.

Attach to Screen Session

To access the ncurses interface directly:

screen -r rtorrent

Detach with:

  • Windows: Ctrl+A , D
  • Mac: ⌃ Control+A , D
QuickBox Dashboard Integration

rTorrent is automatically integrated into your QuickBox dashboard. Find it in the Service Control panel with status information. Install ruTorrent or Flood for web access.

Browser Download Index

Separate from ruTorrent and Flood, QuickBox installs a per-user browser file index that lists the contents of your rTorrent download directory in a dark-themed fancyindex view. Useful for quickly grabbing a single finished file without loading a web client.

https://your-server-ip/username.rtorrent.downloads
How it works

The nginx template at /etc/nginx/software/username.dlindex.conf exposes /home/username/torrents/rtorrent through the shared fancyindex snippet. Access is protected by auth_basic against /etc/htpasswd.d/htpasswd.username, which is the same credential file used for other QuickBox user endpoints.

  • The listing path matches the rTorrent base directory (cfg.basedir, default ~/torrents/rtorrent/), so the download/, watch/, and log/ subfolders and the .sessions/ metadata are all visible.
  • The index is stitched together per user: if you also have qBittorrent, Deluge, Transmission, NZBGet, or SABnzbd installed, their completed-download locations are appended into the same username.dlindex.conf so each client gets its own URL. It is one shared browse-index config covering all of that user’s download clients, not an rTorrent-only feature.
  • The feature has no service of its own — it is pure nginx. If the page fails to load — returns a 502 or 404, shows blank, or errors — while the rest of the dashboard works normally, the per-user config is broken or missing. Rebuild it with qb fix dlindex (see Troubleshooting).
Open download folder from the dashboard

The v4 dashboard exposes this same index as an Open download folder link in the Download Activity panel (the slide-out reached from the download icon in the system metrics bar). It opens the per-user file index for rTorrent in a new tab.

Initial Configuration

1. Unix Socket Communication

QuickBox automatically configures:

  • SCGI socket: /var/run/username/.rtorrent.sock
  • Listening port range: Random from 2000-61000 (1500 port range per user)

The socket is used by ruTorrent, Flood, and *arr applications for communication.

Flood shim installed?

If you installed Flood for a user, QuickBox also installs rtorrent-scgi-shim@username, which binds /var/run/username/.rtorrent.sock and forwards to /var/run/username/.rtorrent-real.sock. Flood should use /var/run/username/.rtorrent.sock and the .rtorrent.rc and ruTorrent should use the real socket /var/run/username/.rtorrent-real.sock. See the Flood docs → Shim details.

2. Install Web Interface (Optional)

Install a web interface for remote management:

# ruTorrent (recommended for rTorrent)
qb install rutorrent -u username
 
# Flood (modern alternative)
qb install flood -u username

3. Connect to *arr Applications (Optional)

When configuring Sonarr, Radarr, or other *arr applications, use the nginx SCGI route:

  1. In your *arr app, go to Settings → Download Clients → Add (+)
  2. Select rTorrent from the list
  3. Enter connection details:
    • Host: yourserver.com
    • Port: 443
    • Use SSL: Yes
    • URL Path: Empty
    • XMLRpc Path: /USERNAME
    • Username: Your QuickBox username
    • Password: Your QuickBox password
  4. Test and save
SCGI via nginx

The /USERNAME path is routed by nginx (/etc/nginx/software/username.scgi.conf) to the Unix socket at /var/run/username/.rtorrent.sock. This eliminates the need to expose rTorrent directly—all connections go through nginx with SSL and authentication.

File Locations

rTorrent’s layout is not fixed. Every path derives from cfg.basedir in the user’s ~/.rtorrent.rc, and cfg.basedir is user-configurable — if you relocate the base directory, every dependent path follows it. The values below are the shipped defaults.

/
home/
└── username/
│ ├── .rtorrent.rc# rTorrent configuration file (fixed location). Defines cfg.basedir and all derived paths.
│ └── torrents/
│ │ └── rtorrent/# cfg.basedir — the base directory all other paths hang off (relocatable)
│ │ │ ├── .sessions/# Session / resume directory (cfg.session)
│ │ │ ├── download/# Default download directory (cfg.download)
│ │ │ ├── log/# Log directory (cfg.logs). The main log is a timestamped file rtorrent-<time>.log; execute.log holds scripted-command output.
│ │ │ └── watch/# Watch directory (cfg.watch) — contains load/ and start/ for auto-loading torrents
var/
└── run/
│ └── username/
│ │ └── .rtorrent.sock# SCGI Unix socket used by ruTorrent, Flood, and *arr apps
Log files are timestamped

rTorrent’s main log has no fixed filename — it is rtorrent-<system.time>.log inside the log directory. The dashboard log viewer resolves the newest rtorrent-*.log (plus execute.log) automatically. Do not look for a fixed rtorrent.log.

Backup and Restore

rTorrent supports both a Full Backup and a Config Only backup from the dashboard (Application Backups tab, or by expanding rTorrent in Application Control). Backups are written to ~/.QuickBox/software/rtorrent/backup/.

Backup typeWhat it captures
Full Backup
The .rtorrent.rc, the session directory, and the watch directories — all resolved from cfg.basedir in your .rtorrent.rc. If you relocated the base directory, the backup follows wherever the config points.
Config Only
Just the .rtorrent.rc configuration file.
No application rollback

Because rTorrent is a single, system-wide install (not a per-user /opt directory), there is no application rollback flow — restore re-applies a backup over the live paths.

For the full backup workflow, owner visibility rules, and where backups live on disk, see App Management → Application Backups.

Service Management

rTorrent runs as a systemd service inside a detached screen session.

systemctl status rtorrent@username     # Check status
systemctl restart rtorrent@username    # Restart service
journalctl -u rtorrent@username -f     # View live logs
systemctl enable rtorrent@username     # Start on boot
systemctl disable rtorrent@username    # Prevent auto-start

Troubleshooting

rTorrent Won’t Start

journalctl -u rtorrent@username -f

Check for configuration errors:

cat ~/.rtorrent.rc | grep -E 'error|warn'

Socket Permission Issues

Symptoms

  • rTorrent socket not accessible
  • Permission denied errors in logs
  • ruTorrent cannot connect to rTorrent

Resolution

  • Verify socket exists: ls -la /var/run/username/.rtorrent.sock
  • Check socket permissions: should be owned by username
  • Fix permissions: qb fix permissions -u username
  • Restart service: systemctl restart rtorrent@username

Downloads or browse index page not loading

Symptoms

  • The per-user downloads / file-browse index page fails to load — returns a 502 or 404, shows blank, or errors — while the rest of the dashboard works normally
  • Only the directory-listing page is affected; rTorrent itself keeps running
  • ruTorrent, Flood, and the *arr apps still work, so the client backend is fine

Resolution

  • Rebuild the per-user browse-index nginx config: qb fix dlindex -u username (one user) or qb fix dlindex (all users)
  • The fix re-renders /etc/nginx/software/username.dlindex.conf and reloads nginx on a successful test
  • See the qb fix reference: /docs/cli-reference/fix#fix-dlindex

The browse index is a single shared per-user nginx config (/etc/nginx/software/username.dlindex.conf) that covers all of that user’s download clients, not just rTorrent. If it fails to load — 502, 404, blank, or error — while rTorrent and the rest of the dashboard work normally, that config is broken or missing. Rebuild it with qb fix dlindex. This is a different problem from the Socket Permission Issues above, which take rTorrent (and therefore ruTorrent, Flood, and the *arr connections) completely offline. This same fix applies to the browse page for every download client — see the Download Clients overview.

Port Range Conflicts

# Check configured port range
grep -E 'port_range|port_random' ~/.rtorrent.rc
 
# Verify no conflicts with other services
ss -tulpn | grep -E '(2000|3000|4000|5000|6000)'

Screen Session Lost

# List all screen sessions
screen -ls
 
# Reattach if session exists
screen -r rtorrent
 
# If no session, restart service
systemctl restart rtorrent@username

Best Practices

Do

  • Use qb update rtorrent to upgrade versions safely
  • Monitor service health with systemctl status rtorrent@username
  • Use watch folders for automated torrent loading
  • Install ruTorrent or Flood for web-based management
  • Keep rTorrent updated to latest stable version for your distro
  • Use nginx SCGI proxy for all remote connections
  • Configure appropriate upload/download limits in .rtorrent.rc
  • Regularly check logs for errors: journalctl -u rtorrent@username

Don't

  • Don't install rTorrent from system package managers—use QuickBox only
  • Don't manually edit systemd or nginx configs without backing up first
  • Don't use versions below 0.9.8 on Debian 13 (Trixie) or later
  • Don't delete .rtorrent.sock manually—managed by rTorrent
  • Don't expose SCGI socket directly without nginx authentication
  • Don't manually edit .rtorrent.rc while service is running
  • Don't forget to detach from screen (Ctrl+A, D) instead of closing terminal
  • Don't mix rTorrent versions with incompatible libtorrent versions

FAQ

Available versions are resolved dynamically from the packages.lst manifest in the QuickBox/compiled-packages repository. The CLI fetches and caches this manifest (1-hour TTL) and filters by your distro codename. No manual database updates are needed.
The CLI resolves the latest available version for your distro from the packages.lst manifest and installs that. If the manifest is unreachable, it falls back to 0.16.7.
The feature-bind option (-o 'feature-bind') builds both libtorrent and rTorrent from the latest master branch commits instead of installing a precompiled .deb. Use this for bleeding-edge builds.
rTorrent updates require admin CLI access (qb update rtorrent -u username), so the hideUpdateForNonAdmin flag is set. Admins see the badge and can dismiss it; non-admins see the installed version without a distracting update prompt.
The paired libtorrent-rakshasa version is resolved automatically. For example: rTorrent 0.16.7 pairs with libtorrent 0.16.7, rTorrent 0.10.0 pairs with libtorrent 0.14.0, and rTorrent 0.9.8 pairs with libtorrent 0.13.8.

Web Interfaces

ruTorrent ⭐Flood

Media Management

Sonarr ⭐Radarr ⭐LidarrReadarr

Indexers

Prowlarr ⭐Jackett

Other Download Clients

qBittorrentDelugeTransmission

Additional Resources

rTorrent GitHub Repository

Official rTorrent source code and documentation

rTorrent Wiki

Configuration guides and advanced usage

libTorrent Documentation

Underlying library documentation

Join the Community

Media server operators sharing configs, getting support, and shaping the future of QuickBox Pro.

Dedicated Support
Feature Previews
Community Configs
Active Discussions
Join Discord Server
Last updated on
qBittorrentruTorrent