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 multi-version support (0.9.8 through 0.16.5) 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

🔄 Multi-Version

Choose from 0.9.6 to 0.16.5 or feature-bind builds

🔐 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

Symptoms

  • QuickBox Pro v3 installed and configured
  • User account created on the server
  • Sufficient disk space for torrent data and session files

Resolution

  • Use QuickBox's qb command for installation
  • Automatic configuration with reverse proxy
  • Per-user installation with isolated configurations

Basic Installation

Install rTorrent for a specific user (defaults to version 0.16.5):

qb install rtorrent -u username

Version-Specific Installation

Install a specific rTorrent version:

qb install rtorrent -u username -o '0.16.5'

CLI Commands

Command
qb install rtorrent -u username
Description
Install rTorrent with default version (0.16.5)
Command
qb install rtorrent -u username -o '0.16.0'
Description
Install 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

Available versions: 0.16.5This is the current recommended version, 0.16.2, 0.16.1, 0.16.0, 0.15.1, 0.10.0, 0.9.8, 0.9.7, 0.9.6, feature-bindThese versions are not recommended for new installs and will eventually be removed

CLI Options

-u, --usernameRequired

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

-o, --option

Specify rTorrent version to install/update (e.g., '0.16.5')

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.

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.

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.

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

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

Use Cases

Headless High-Performance Torrenting

  • Minimal resource usage with maximum throughput
  • Screen session for direct ncurses access when needed
  • Perfect for dedicated seedboxes and remote servers

Web-Based Management via ruTorrent

  • Install ruTorrent for full-featured PHP web interface
  • Plugins for RSS, automation, and advanced management
  • Classic interface preferred by many private tracker users

Modern UI via Flood

  • Install Flood for sleek, modern Node.js interface
  • Clean design with real-time updates
  • Unix socket support with authentication
🎨

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
qBittorrentruTorrent