Skip to Content
DocsApplicationsDownload ClientsSABnzbd
SABnzbd

SABnzbd

Automated Usenet Binary Newsreader

SABnzbd is a free, open-source Usenet binary newsreader written in Python. It automates downloading from Usenet with powerful post-processing including unpacking, repair, and organization. On QuickBox, SABnzbd runs as a per-user daemon with a Python 3.11 virtual environment at /opt/username/SABnzbd, self-signed SSL certificates for secure connections, par2cmdline-turbo for high-speed repairs, and a web interface published through the nginx reverse proxy.

Usenet Downloads

Automated binary downloading from Usenet newsgroups with NZB support

Post-Processing

Automatic unpacking, repair, and file organization with custom scripts

SSL/HTTPS

Per-user SSL certificates for secure connections to Usenet providers

par2cmdline-turbo

High-speed repair with optimized par2 implementation compiled from source

Python 3.11 venv

Isolated virtual environment with system-site-packages support

Category System

Smart categorization for automated *arr application integration

Usenet Provider Required

SABnzbd requires a Usenet provider subscription to download content. You’ll need server credentials (host, port, username, password) from your provider to configure SABnzbd.

Installation

Have your Usenet provider credentials (host, port, username, password) ready — you enter them in the SABnzbd web interface after installation.

Install from the Dashboard

Open App Dashboard → Package Management (/dashboard?mode=packages), find SABnzbd in the catalog (browse Download Clients or search), and click Install. The install dialog offers a channel choice — Stable (default) or Beta — for the SABnzbd release you want. The dashboard streams the install log live and SABnzbd appears in your Application Control panel when it finishes. Reinstall, Update, and Remove are available from the same panel.

The default channel is Stable; pick Beta only if you want development releases. See Channels & Versions for how channels work. 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. It installs the Stable release by default; add --beta for the development release:

qb install sabnzbd -u username
Command
qb install sabnzbd -u username
Description
Install SABnzbd with latest stable version
Command
qb install sabnzbd -u username --beta
Description
Install beta/development release of SABnzbd
Command
qb reinstall sabnzbd -u username
Description
Reinstall while preserving QuickBox integration
Command
qb update sabnzbd -u username
Description
Update SABnzbd to latest stable version
Command
qb remove sabnzbd -u username
Description
Remove SABnzbd and clean up files
Command
qb help sabnzbd
Description
Display comprehensive help information

CLI Options

-u, --usernameRequired

Target QuickBox username for install/remove/update operations

--beta

Install the beta/development release of SABnzbd

Automatic Port Assignment

QuickBox automatically assigns ports starting from base values:

  • HTTP port: Base 65080 (auto-incremented per user if port is in use)
  • HTTPS port: Base 65131 (auto-incremented per user if port is in use)

The system checks if each port is available and increments until a free port is found. Your assigned ports are stored in the QuickBox dashboard and in ~/.config/SABnzbd/sabnzbd.ini.

Directory Layout

/opt/username/SABnzbd
.venv/# Python 3.11 virtual environment
SABnzbd.py# Main SABnzbd executable
sabnzbd/# SABnzbd source code
scripts/# Post-processing scripts
/home/username/.config/SABnzbd
sabnzbd.ini# Main configuration file (auto-written with QuickBox defaults)
sabnzbd.log# Application log
Downloads/# Download directories
Downloads/complete/# Completed downloads
Downloads/incomplete/# In-progress downloads
admin/# Admin folder with SSL certificates
scripts/# User post-processing scripts (FileBot integration)
/home/username/.ssl
cacert.pem# CA bundle fetched from curl.se
username-selfsigned.crt# Self-signed cert generated per user (1095 days validity)
username-selfsigned.key# TLS key; permissions 750

Network & Access

SABnzbd binds to localhost on auto-assigned HTTP/HTTPS ports (base ports 65080/65131, auto-incremented per user if already in use). QuickBox publishes the UI through nginx at:

https://yourserver.com/username/sabnzbd/

Authentication Layers:

  • Primary: SABnzbd’s built-in authentication (username/password configured in SABnzbd settings)
  • Secondary: nginx Basic Auth with /etc/htpasswd.d/htpasswd.username (optional additional layer)

During installation, QuickBox automatically configures SABnzbd with your QuickBox username/password for convenience. You can change SABnzbd’s credentials later in Config → General → Security.

Proxy details

Traffic terminates at nginx over HTTPS, then proxies to https://127.0.0.1:<assigned_https_port>/username/sabnzbd. Ports are auto-incremented from base values (65080/65131) until an available port is found, then written to the service and nginx configs. SABnzbd runs with self-signed SSL certificates for the internal connection.

API Access

The /username/sabnzbd/api endpoint bypasses nginx Basic Auth to allow *arr applications and other automation tools to connect using only the API key. All other paths have dual authentication (nginx + SABnzbd).

Dual Authentication

SABnzbd has its own built-in login. The nginx Basic Auth in front of it is an optional secondary layer for the web UI. The /username/sabnzbd/api endpoint skips nginx Basic Auth so *arr apps can connect with just the API key — all other paths require both.

Services

SABnzbd uses a templated systemd unit (sabnzbd@.service) running as a simple daemon:

# Check status
systemctl status sabnzbd@username
 
# View logs
journalctl -u sabnzbd@username -f
 
# Restart service
systemctl restart sabnzbd@username
 
# Stop service
systemctl stop sabnzbd@username
 
# Start service
systemctl start sabnzbd@username

The service runs SABnzbd in its Python virtual environment and restarts it automatically on failure.

Logs

Runtime logs live at /home/username/.config/SABnzbd/sabnzbd.log. You can also view systemd logs with journalctl -u sabnzbd@username -f.

Initial Configuration

On first access, SABnzbd presents a Quick-Start Wizard to configure your Usenet provider and basic settings:

1. Complete Quick-Start Wizard

  1. Language Selection - Choose your preferred language
  2. Server Setup - Enter Usenet provider credentials
    • Host: Your provider’s server address (e.g., news.yourprovider.com)
    • Port: Usually 563 for SSL or 119 for standard
    • Username/Password: From your Usenet provider account
    • Connections: Maximum simultaneous connections (check provider limits)
  3. Security - API key is auto-generated, save it for *arr apps

2. Configure Categories

Create categories for automated downloads:

  1. Navigate to Config → Categories
  2. Create categories matching your *arr apps: sonarr, radarr, lidarr, readarr
  3. Set appropriate download paths for each category
  4. Configure post-processing options (unpacking, deletion of archives)

Configuration

Connect *arr apps to SABnzbd using these settings:

Setting
Host
Value
localhost
Setting
Port
Value
443
Setting
API Key
Value
Found on your QuickBox dashboard → Service Control → SABnzbd → API Key
Setting
Use SSL
Value
Enabled
Setting
URL Base
Value
/username/sabnzbd
Setting
Username
Value
SABnzbd username (initially your QuickBox username, changeable in SABnzbd)
Setting
Password
Value
SABnzbd password (initially your QuickBox password, changeable in SABnzbd)
Setting
Category
Value
Create as needed: sonarr, radarr, lidarr, etc.
Not seeing the URL Base option?

If you are not seeing the URL Base field, click the cog icon to enable advanced settings in the download client configuration.

Authentication Note(s)

*arr applications connect directly to SABnzbd using SABnzbd’s built-in authentication, not nginx’s Basic Auth. Make sure you’re using the correct username/password configured in SABnzbd (Config → General → Security).

Why use port 443 and not the SABnzbd HTTPS port directly? Because QuickBox terminates SSL at nginx, so all external connections use standard HTTPS (443) with the URL base to route to SABnzbd. This simplifies firewall rules and ensures secure connections and never exposes SABnzbd’s internal port directly.

FileBot Post-Processing (courtesy setup)

View the FileBot documentation for full FileBot setup and configuration.

QuickBox can wire SABnzbd to FileBot during FileBot installation:

  1. Install FileBot with the SABnzbd option:
qb install filebot -u username -o sabnzbd -mp /path/to/media
  1. QuickBox drops ~/.config/SABnzbd/scripts/sabnzbd-postprocess.sh and rewrites it with your username and media path.
  2. QuickBox automatically updates sabnzbd.ini to enable the script for anime, movies, and tv categories.
  3. In SABnzbd → Settings → Categories, verify the script is assigned to relevant categories.
What the script does

Invokes /usr/local/bin/username/filebot with the AMC preset, duplicates to your media path, skips conflicts, and honors /home/username/.config/Filebot/.excludes.

The script copies matched media into your configured media path using FileBot’s AMC preset (duplicate action, skip on conflict), honoring your exclude list. QuickBox assigns it to the anime, movies, and tv categories automatically.

Manual Configuration

If you need to manually configure FileBot post-processing:

  1. Create or edit categories in SABnzbd → Config → Categories
  2. Assign the script to each category where you want automatic processing
  3. Set download paths per category if desired
  4. Test by adding a download with the appropriate category
Testing the integration

After setup, add a test NZB file with a category that has the script assigned. Check /home/username/.config/Filebot/amc.log for FileBot processing output and verify files appear in your media directory.

Troubleshooting FileBot Integration

Symptom
Script not executing
Solution
Verify script_dir = scripts in [misc] section of sabnzbd.ini
Symptom
Permission denied errors
Solution
Ensure script has execute permissions: chmod +x ~/.config/SABnzbd/scripts/*.sh
Symptom
FileBot license error
Solution
Install FileBot with valid license: qb install filebot -u username
Symptom
Files not moving to media folder
Solution
Check CONFIG_OUTPUT path in script matches your media directory
Symptom
No processing logs
Solution
Check amc.log in SABnzbd download directory or ~/.config/Filebot/
Symptom
Script shows in SABnzbd but not working
Solution
Verify SABnzbd service restarted after FileBot install
FileBot License Required

FileBot requires a valid license for full functionality. The script will execute but may have limited capabilities without a license. Purchase a license from filebot.net  and activate it via qb install filebot when prompted.

Python Environment & Dependencies

SABnzbd on QuickBox runs in an isolated Python 3.11 virtual environment with the following characteristics:

Component
Python Version
Details
Python 3.11 (installed in virtual environment)
Component
Virtual Environment
Details
/opt/username/SABnzbd/.venv
Component
Python Executable
Details
/opt/username/SABnzbd/.venv/bin/python3.11
Component
System Site Packages
Details
Enabled (--system-site-packages flag)
Component
Par2 Utility
Details
par2cmdline-turbo (compiled from source for high-speed repairs)
Component
Requirements
Details
Installed from SABnzbd requirements.txt (includes cryptography, feedparser, etc.)
Component
Encoding
Details
UTF-8 (via PYTHONIOENCODING=utf-8 environment variable)
Why Python 3.11?

SABnzbd benefits from Python 3.11’s performance improvements (10-60% faster than 3.10) and better error messages. The virtual environment isolates dependencies while --system-site-packages allows access to system-wide packages.

Troubleshooting

SABnzbd Won’t Start

Check service status and logs:

# Check service status
systemctl status sabnzbd@username
 
# View recent logs
journalctl -u sabnzbd@username -n 50
 
# View live logs
journalctl -u sabnzbd@username -f
 
# Check SABnzbd's own log file
tail -f ~/.config/SABnzbd/sabnzbd.log

Common causes:

  • Port conflicts (another service using 65080 or 65131)
  • Corrupted Python virtual environment
  • Permission issues on config directory
  • Missing or corrupted SSL certificates

Check for port conflicts:

# Check assigned ports
grep -E 'https_port|port' ~/.config/SABnzbd/sabnzbd.ini
 
# Check if ports are in use
ss -tulpn | grep -E '65080|65131'

Cannot Connect to Usenet Server

Symptoms

  • Connection refused errors in SABnzbd logs
  • Authentication failures with Usenet provider
  • SSL handshake failures
  • Downloads not starting

Resolution

  • Verify credentials are correct on provider website
  • Check SSL port (usually 563) vs standard port (119)
  • Ensure firewall allows outbound connections
  • Verify provider account is active and paid up

Python Virtual Environment Issues

If SABnzbd fails to start with Python-related errors:

# Check Python version in venv
/opt/username/SABnzbd/.venv/bin/python3.11 --version
 
# Check if venv is intact
ls -la /opt/username/SABnzbd/.venv/bin/
 
# Reinstall SABnzbd (preserves config)
qb reinstall sabnzbd -u username

Symptoms of corrupted venv:

  • ImportError or ModuleNotFoundError in logs
  • SABnzbd fails to start with Python traceback
  • Missing Python executable or pip in .venv/bin/

Permission Issues

Fix file ownership and permissions:

# Check current ownership
ls -la /opt/username/SABnzbd
ls -la ~/.config/SABnzbd
 
# Fix permissions via QuickBox
qb fix permissions -u username
 
# Or manually fix
sudo chown -R username:username /opt/username/SABnzbd ~/.config/SABnzbd
sudo chmod 0750 ~/.config/SABnzbd/sabnzbd.ini
 
# Restart service
systemctl restart sabnzbd@username

SSL Certificate Issues

If you see SSL handshake errors or certificate warnings:

# Check certificate files exist
ls -la ~/.ssl/
ls -la ~/.config/SABnzbd/admin/
 
# Verify certificate validity
openssl x509 -in ~/.ssl/username-selfsigned.crt -noout -dates
 
# Regenerate certificates if needed
cd ~/.ssl
openssl req -config /opt/quickbox/config/system/ssl/openssl.conf \
  -x509 -nodes -days 1095 -newkey rsa:2048 \
  -keyout username-selfsigned.key \
  -out username-selfsigned.crt
 
# Copy to SABnzbd admin folder
cp -f ~/.ssl/*.{crt,key,pem} ~/.config/SABnzbd/admin/
chown username:username ~/.config/SABnzbd/admin/*
 
# Restart service
systemctl restart sabnzbd@username

*arr Apps Can’t Connect

If Sonarr/Radarr/etc. can’t connect to SABnzbd:

Symptom
Connection refused
Solution
Verify SABnzbd is running: systemctl status sabnzbd@username
Symptom
SSL handshake failed
Solution
Ensure "Use SSL" is checked and port is the HTTPS port (65131+)
Symptom
API key invalid
Solution
Copy exact API key from SABnzbd → Config → General → Security
Symptom
Unable to connect to localhost
Solution
Use 127.0.0.1 instead of localhost
Symptom
URL Base error
Solution
Set URL Base to /username/sabnzbd (enable advanced settings)
Symptom
401 Unauthorized
Solution
Verify SABnzbd username/password (not nginx auth, SABnzbd auth)
Symptom
Authentication failed
Solution
Check credentials in SABnzbd → Config → General → Security
Test API Connection

Test SABnzbd API access from command line (replace port and API key with your values):

curl -k "https://127.0.0.1:65131/username/sabnzbd/api?mode=version&apikey=YOUR_API_KEY"

Should return JSON with SABnzbd version information. If this fails, SABnzbd isn’t responding properly.

Important: SABnzbd Authentication

*arr applications authenticate directly to SABnzbd using SABnzbd’s own username/password system, which is separate from nginx Basic Auth. Make sure you’re entering the correct credentials configured in SABnzbd (Config → General → Security), not your nginx/htpasswd credentials.

Downloads Stalling or Failing

If downloads won’t start or complete:

Symptoms

  • Downloads stuck at 0% or paused
  • Articles missing or incomplete
  • SSL certificate verification failures to Usenet server
  • PAR2 repair failures
  • Unpacking errors after download

Resolution

  • Verify Usenet provider credentials and account status
  • Check SSL port (563) vs standard port (119) settings
  • Ensure provider account is active with remaining data quota
  • Verify download has enough PAR2 files for repair
  • Check disk space: df -h /home/username
  • Review SABnzbd logs for specific error messages

Web Interface Not Loading

If nginx reverse proxy isn’t working:

# Check nginx configuration
sudo nginx -t
 
# Check if nginx is running
systemctl status nginx
 
# Verify nginx config file exists
ls -la /etc/nginx/software/username.sabnzbd.conf
 
# Check htpasswd file
ls -la /etc/htpasswd.d/htpasswd.username
 
# Reload nginx
sudo systemctl reload nginx

Configuration Reset

# Backup current configuration
cp ~/.config/SABnzbd/sabnzbd.ini ~/.config/SABnzbd/sabnzbd.ini.backup
 
# Remove configuration (will be regenerated)
rm ~/.config/SABnzbd/sabnzbd.ini
 
# Restart service
systemctl restart sabnzbd@username

Downloads / browse index page not loading

QuickBox builds a per-user nginx fancyindex view of each user’s completed downloads, and SABnzbd’s completed folder is included in it. This browse index is a single shared per-user config — /etc/nginx/software/username.dlindex.conf — that covers every download client that user has installed, not SABnzbd alone. It has no service of its own.

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; SABnzbd itself keeps running

Resolution

  • Rebuild for one user: qb fix dlindex -u username
  • Rebuild for all users: qb fix dlindex
  • The fix re-renders /etc/nginx/software/username.dlindex.conf, runs nginx -t, and reloads nginx only on a successful test
  • See the qb fix reference: /docs/cli-reference/fix#fix-dlindex

The same fix applies to the browse page for every download client — see the Download Clients overview.

Best Practices

Do

  • Use qb update sabnzbd to keep SABnzbd and dependencies updated
  • Configure categories for different *arr applications
  • Enable SSL connections to your Usenet provider when available
  • Monitor disk space regularly—Usenet downloads can be large
  • Set appropriate retention for history and logs
  • Use post-processing scripts for advanced automation
  • Configure bandwidth limits during peak hours if needed
  • Keep API key secure—treat it like a password

Don't

  • Don't share your API key publicly—it grants full access to SABnzbd
  • Don't manually edit systemd or nginx configs without backing up first
  • Don't expose SABnzbd directly to the internet without nginx in front
  • Don't ignore incomplete downloads—check Usenet provider health
  • Don't disable SSL for Usenet connections—unencrypted NZB traffic is visible
  • Don't set connection count higher than provider allows—risks bans
  • Don't delete Python venv manually—use qb remove instead
  • Don't manually edit sabnzbd.ini while service is running

Media Management

Sonarr ⭐Radarr ⭐LidarrReadarr

Indexers

Prowlarr ⭐NZBHydra2

Post-Processing

FileBot ⭐

Notifications

Notifiarr

Additional Resources

SABnzbd Official Documentation

Official wiki with configuration and usage guides

SABnzbd GitHub Repository

Source code and issue tracking

par2cmdline-turbo GitHub

Optimized par2 repair utility used by QuickBox

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
ruTorrentTransmission