Transmission

Lightweight BitTorrent client that “just works”

Transmission is a fast, easy-to-use BitTorrent client designed with sensible defaults that work out of the box. Ubuntu chose Transmission as its default BitTorrent client largely due to its easy learning curve. QuickBox Pro installs the modern v4 (4.x+, Qt6-based) build by default on every supported distro, with the legacy v3 (3.00) available as an opt-in where it is still compiled. Every install ships per-user systemd services, an nginx reverse proxy, and pre-configured RPC access.

Installation

Install from the Dashboard

Open App Dashboard → Package Management (/dashboard?mode=packages), find Transmission in the catalog (browse Download Clients or search), and click Install. The version selector defaults to the latest (v4) build for a new install; the legacy 3.x series appears as a choice only on distros where it is still compiled (Debian 12 and Ubuntu 22). The dashboard streams the install log live and Transmission appears in your Application Control panel when it finishes. Reinstall, Update, and Remove are available from the same panel.

When you update an existing install, the dashboard keeps the major you already have — a v3 install stays on v3 unless you explicitly pick v4 in the selector. Picking v4 migrates the install for all users.

What you see and can manage is gated by your account: admins manage any user’s apps; regular users manage their own. For the full package flow see App Management.

Install from the CLI (automation)

The CLI runs the same install and is suited to automation and scripting. By default it installs the latest modern v4 (4.x+, Qt6) build. Use -o '<version>' to pin an exact build resolved from the compiled-packages manifest; the version’s major decides the packaging branch — 4.x+ installs the modern single-package build, 3.x installs the legacy multi-part build. --v3 and --v4 remain as aliases that install the latest build within that major:

qb install transmission -u username              # latest modern v4 (default)
qb install transmission -u username --v4          # latest v4 (explicit alias)
qb install transmission -u username --v3          # latest legacy 3.x (Debian 12 / Ubuntu 22 only)
qb install transmission -u username -o '4.0.6'    # pin an exact build from the manifest

Version availability by distro

The legacy v3 (3.00) build ships only where QuickBox provides compiled 3.00 packages:

On distros where v3 is unavailable, --v3 falls back to installing v4 and prints a notice explaining that the legacy build is not compiled for that distro.

CLI Commands

Dual Packaging Model

Transmission uses different packaging depending on the version series:

• Modern v4 (4.x+) — installed as a single +allmods .deb that bundles all components. Qt6 dependencies are resolved and installed from the compiled-packages manifest alongside the main package. This is the default.
• Legacy v3 (2.x/3.x) — installed as separate subpackages: transmission-daemon, transmission-cli, transmission-common, transmission-gtk, and transmission-qt. All are held at the installed version to prevent accidental upgrades.

This means --v3/--v4 does not just change the version number; it changes the entire packaging structure — which is why switching branch replaces the installation for all users.

Accessing Transmission

After installation, access Transmission at:

https://your-server-ip/transmission/

Login credentials:

• Username: Your QuickBox username
• Password: Your QuickBox password (RPC authentication)

Browser Download Index

In addition to the Transmission Web UI, QuickBox installs a per-user browser file index that lists your Transmission download folder in a dark-themed fancyindex view. Useful for quickly grabbing a single finished file without loading the torrent client.

https://your-server-ip/username.transmission.downloads

• The listing is the folder set as download-dir in the Transmission settings. With the default folder it also contains the watch/ folder. Change the download folder in Transmission and QuickBox re-renders the index on its own, usually within seconds, with an hourly check as a safety net. If the folder can’t be served (it is a symlink, it is outside your home folder, /mnt and /media, it doesn’t exist, or the web server can’t read it), the index keeps serving the default folder and the dashboard shows a note beginning “Showing the default folder.” See Open download folder for each note.
• Removing Transmission keeps your finished downloads. qb remove transmission deletes the client’s configuration and data but never the download folder or what is inside it, and the remove output names the folder it kept. With the default folder, that includes watch/. Reinstalling writes your download-dir back into the fresh settings.
• The index is stitched together per user: if you also have qBittorrent, rTorrent, Deluge, 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.
• 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 -u username (one user) or qb fix dlindex (all users). See the Download Clients overview and the qb fix reference.

Initial Configuration

1. Web Interface Setup

On first access, the web interface is pre-configured:

• RPC authentication: Enabled with your QuickBox credentials
• RPC whitelist: Restricted to 127.0.0.1 for security
• Download directory: /home/username/torrents/transmission/downloads
• Watch directory: /home/username/torrents/transmission/watch

No additional setup required—Transmission is ready to use immediately.

2. Configure Watch Directory (Optional)

Enable automated torrent loading:

1. Navigate to Preferences (gear icon) → Network
2. Verify watch directory is enabled: /home/username/torrents/transmission/watch
3. Drop .torrent files into the watch folder—they’ll be added automatically

3. Connect to *arr Applications (Optional)

If using Sonarr, Radarr, or other *arr applications:

1. In your *arr app, go to Settings → Download Clients → Add (+)
2. Select Transmission from the list
3. Enter connection details:
   • Host: 127.0.0.1
   • Port: Your RPC port (check ~/.config/Transmission/settings.json → rpc-port)
   • URL Path: /transmission/
   • Username: Your QuickBox username
   • Password: Your QuickBox password
4. Test and save

Service Management

Transmission runs as a systemd service for reliability and automatic startup.

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

Troubleshooting

Transmission Won’t Start

journalctl -u transmission@username -f

Check for port conflicts:

grep -i 'rpc-port' ~/.config/Transmission/settings.json
# Default: 15105

Web Interface Not Accessible

Configuration File Corruption

# Stop service
systemctl stop transmission@username
 
# Backup current configuration
cp ~/.config/Transmission/settings.json ~/.config/Transmission/settings.json.backup
 
# Edit or regenerate configuration
nano ~/.config/Transmission/settings.json
 
# Restart service
systemctl start transmission@username

Permission Issues

qb fix permissions -u username
systemctl restart transmission@username

Version Switch Issues

A bare qb update transmission keeps the installed major, so migrating a v3 install to v4 needs the explicit flag. If the in-place migration fails, do a clean reinstall:

# Migrate v3 → v4 in place
qb update transmission -u username --v4
 
# If the migration fails, clean reinstall on v4 (the default)
qb remove transmission -u username
qb install transmission -u username

VPN routing

Transmission can route all of its torrent traffic through a VPN tunnel using QuickBox Pro’s app-scoped routing, with either a WireGuard or an OpenVPN backend. When routing is enabled, Transmission downloads, seeds, and announces to trackers from the VPN peer’s exit IP instead of your server’s real IP.

Transmission downloads, seeds, and announces its ratio from the VPN exit IP, and all of that keeps working whatever your provider. Whether other peers can start a connection to you depends on the provider, and the routing card shows a Port forwarding section for it: with ProtonVPN (NAT-PMP) or AirVPN (a port from your account) the dashboard keeps Transmission’s peer port on the provider’s forwarded port; with a provider that forwards none (like NordVPN) your tracker may show you as not connectable, which only means other peers can’t start a connection to you. You may seed to slightly fewer peers, because two peers that are both not connectable can’t reach each other. A provider that forwards a port (ProtonVPN, AirVPN) removes that limit. The section works the same for every torrent client; see qBittorrent routing for the full walkthrough. Port forwarding works with the WireGuard backend. A client routed over OpenVPN works the same way as the NordVPN case above: downloading, seeding and ratio are unaffected.

Transmission is a per-user template service (transmission@<user>), so several users can each route their own instance independently. Its WebUI stays reachable at its usual https://yourserver.com/username/transmission/ address through the dashboard proxy while routed. It appears in the App-Scoped Routing card once Transmission is installed and its service is running.

How to enable VPN routing for Transmission:

1. Go to System > VPN Control (/system/vpn) in the dashboard
2. Upload at least one WireGuard .conf or OpenVPN .ovpn file if you have not done so already
3. Scroll to the App-Scoped Routing card on the VPN Control page
4. Select Transmission from the app list
5. Choose the tunnel backend and a peer configuration from the dropdown
6. Click Enable Routing

Transmission restarts inside its VPN network namespace and its torrent traffic exits through the VPN peer from that point forward.

The default kill-switch stale threshold for Transmission is 30 minutes, matching qBittorrent and the other downloaders. You can adjust it between 60 seconds and 24 hours on the app row inside the App-Scoped Routing card.

For full details on routing configuration, kill switch settings, and live metrics, see the VPN Control dashboard page.

Best Practices

FAQ

Related Applications

Additional Resources