WebUI Configuration¶

Configure qBitrr's modern React-based web interface for monitoring and managing your qBitrr instance.

Overview¶

The qBitrr WebUI provides:

Real-time monitoring - Live process status and logs
Media browsing - View movies, shows, and albums from Arr instances
Configuration management - Edit config.toml from the web
System information - Version, uptime, and health metrics
Responsive design - Works on desktop, tablet, and mobile

Access: http://localhost:6969/ui (default)

Authentication and first-run¶

On new installs, authentication is required by default. When you open the WebUI for the first time, you will see a create credentials screen: choose a username and password to secure qBitrr. After you set them, you are logged in and local username/password login is enabled. You can change the password later via Set Password in WebUI settings.

First-run flow: Open /ui → create username and password → set password & sign in → use the WebUI.
Existing configs: If your config file was created before this behavior (or does not set AuthDisabled), the app continues to treat auth as disabled for backward compatibility until you set AuthDisabled = false or configure a password.
Disable auth: To run without login (e.g. behind your own reverse proxy or in a fully trusted environment), set AuthDisabled = true in the [WebUI] section of config.toml. See AuthDisabled below.

Configuration Section¶

WebUI settings are configured in the [WebUI] section:

[WebUI]
# Listen address
Host = "0.0.0.0"

# Listen port
Port = 6969

# Optional authentication token
Token = ""

# Live updates
LiveArr = true

# Group settings
GroupSonarr = true
GroupLidarr = true

# Default theme
Theme = "Dark"

Host¶

Host = "0.0.0.0"

Type: String (IP address) Default: "0.0.0.0"

IP address the WebUI server listens on.

Options:

"0.0.0.0" - (Default) Listen on all network interfaces
"127.0.0.1" - Localhost only (secure, but can't access remotely)
"192.168.1.100" - Specific network interface

Use cases:

Host	Use Case	Security	Remote Access
`0.0.0.0`	Docker, network access	Medium	✅ Yes
`127.0.0.1`	Localhost only	High	❌ No
Specific IP	Bind to one interface	Medium	✅ Limited

Recommendations:

# Docker (with reverse proxy)
Host = "0.0.0.0"

# Native (with reverse proxy)
Host = "127.0.0.1"

# Native (direct access)
Host = "0.0.0.0"  # Use with Token for security

Port¶

Port = 6969

Type: Integer Default: 6969

TCP port the WebUI listens on.

Access URL: http://<host>:<port>/ui

Common ports:

Port = 6969   # Default
Port = 8080   # Alternative
Port = 443    # HTTPS (with reverse proxy)

Port conflicts:

If port 6969 is in use:

# Check what's using the port
sudo lsof -i :6969
sudo netstat -tulpn | grep 6969

# Change to alternative
Port = 6970

Token¶

Token = ""

Type: String Default: "" (empty, no authentication)

Bearer token for API authentication.

When empty: - WebUI and API are publicly accessible - No authentication required - Anyone with network access can use the WebUI

When set: - All /api/* endpoints require authentication - Must include Authorization: Bearer header in API requests - WebUI automatically handles token for you

Setting up authentication:

[WebUI]
Token = "my-secure-token-12345"

Generating secure tokens:

# Linux/macOS
openssl rand -hex 32

# Or
python3 -c "import secrets; print(secrets.token_hex(32))"

# Output: a1b2c3d4e5f6...

Using authenticated API:

curl -H "Authorization: Bearer my-secure-token-12345" \
  http://localhost:6969/api/processes

Security Recommendation

Always set a token if:

qBitrr is accessible from the internet
You're not using a reverse proxy with authentication
Multiple users have network access

Token can be omitted if:

Behind reverse proxy with its own authentication
Only accessible from localhost
Running in a trusted private network

AuthDisabled¶

AuthDisabled = false

Type: Boolean Default (new installs): false (auth required; user is prompted to create credentials) Default (configs without this key): Treated as true for backward compatibility (auth disabled)

When false, the WebUI requires authentication. On first run with no password set, the user sees the create-credentials screen. When true, no login is required and the WebUI is open to anyone with network access.

Use cases:

Value	Use case
`false`	New installs; require username/password (default for newly generated configs).
`true`	Disable auth (e.g. behind reverse proxy with its own auth, or trusted network).

Example (disable auth):

[WebUI]
AuthDisabled = true

BehindHttpsProxy¶

BehindHttpsProxy = false

Type: Boolean Default: false

Set to true when the WebUI is reached over HTTPS (e.g. behind a reverse proxy such as Nginx, Caddy, or Traefik).

When true:

The app trusts the X-Forwarded-Proto header so request.is_secure and generated URLs (e.g. OIDC redirect) reflect the client-facing HTTPS.
Werkzeug's ProxyFix middleware is applied (x_proto=1).
The session cookie is set with the Secure flag so browsers only send it over HTTPS.

When false (default):

No proxy headers are trusted; suitable for plain HTTP or when qBitrr is not behind a proxy.
Session cookie is not marked Secure, so login works over HTTP.

When to enable

Enable BehindHttpsProxy when you access the WebUI via https:// and your reverse proxy sets X-Forwarded-Proto: https. Leave false for local http://localhost or plain HTTP to avoid login/session issues.

Example (HTTPS behind Nginx):

[WebUI]
Host = "127.0.0.1"
Port = 6969
BehindHttpsProxy = true

LiveArr¶

LiveArr = true

Type: Boolean Default: true

Enable live updates for Arr instance views (Radarr/Sonarr/Lidarr tabs).

When true: - Real-time status updates - Progress bars update automatically - No manual page refresh needed - Uses polling every few seconds

When false: - Static snapshots - Must manually refresh page - Lower resource usage - Reduced API calls to Arr instances

Recommendation: true for best user experience.

Performance consideration:

# High-resource system
LiveArr = true  # Enable real-time updates

# Low-resource system (Raspberry Pi, etc.)
LiveArr = false  # Reduce load

GroupSonarr¶

GroupSonarr = true

Type: Boolean Default: true

Group Sonarr episodes by series in the WebUI.

When true (grouped):

└─ Breaking Bad
   ├─ S01E01 - Pilot
   ├─ S01E02 - Cat's in the Bag
   └─ S01E03 - ...and the Bag's in the River

When false (flat list):

├─ Breaking Bad S01E01 - Pilot
├─ Breaking Bad S01E02 - Cat's in the Bag
└─ Breaking Bad S01E03 - ...and the Bag's in the River

Recommendation: true for better organization.

GroupLidarr¶

GroupLidarr = true

Type: Boolean Default: true

Group Lidarr albums by artist in the WebUI.

When true (grouped):

└─ Pink Floyd
   ├─ The Dark Side of the Moon
   ├─ The Wall
   └─ Wish You Were Here

When false (flat list):

├─ Pink Floyd - The Dark Side of the Moon
├─ Pink Floyd - The Wall
└─ Pink Floyd - Wish You Were Here

Recommendation: true for better navigation.

ViewDensity¶

ViewDensity = "Comfortable"

Type: String Default: "Comfortable" Options: "Comfortable", "Compact"

UI density setting for tables and lists.

"Comfortable" - More spacing, easier to read
"Compact" - Denser layout, shows more data per screen

Note: Users can toggle this in the WebUI settings. This sets the initial default.

Theme¶

Theme = "Dark"

Type: String Default: "Dark" Options: "Dark", "Light"

Default color theme for the WebUI.

"Dark" - Dark mode (easier on eyes, lower power consumption)
"Light" - Light mode (better in bright environments)

Note: Users can toggle theme in the WebUI itself. This sets the initial default.

Complete Configuration Examples¶

Example 1: Default (Public Access)¶

[WebUI]
Host = "0.0.0.0"
Port = 6969
Token = ""  # No authentication
LiveArr = true
GroupSonarr = true
GroupLidarr = true
Theme = "Dark"
ViewDensity = "Comfortable"

Access: http://localhost:6969/ui

Use case: Local network, trusted environment.

Example 2: Secured with Token¶

[WebUI]
Host = "0.0.0.0"
Port = 6969
Token = "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"
LiveArr = true
GroupSonarr = true
GroupLidarr = true
Theme = "Dark"
ViewDensity = "Comfortable"

Access: http://localhost:6969/ui (token handled automatically by WebUI)

Use case: Exposed to internet or untrusted network.

Example 3: Localhost Only (with Reverse Proxy)¶

[WebUI]
Host = "127.0.0.1"
Port = 6969
Token = ""  # Reverse proxy handles auth
LiveArr = true
GroupSonarr = true
GroupLidarr = true
Theme = "Dark"
ViewDensity = "Comfortable"

Nginx reverse proxy:

location /qbitrr/ {
    proxy_pass http://127.0.0.1:6969/;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
}

Access: https://yourdomain.com/qbitrr/ui

Example 4: Low Resource System¶

[WebUI]
Host = "0.0.0.0"
Port = 6969
Token = ""
LiveArr = false  # Disable auto-refresh
GroupSonarr = false  # Flat lists
GroupLidarr = false  # Flat lists
Theme = "Dark"

Use case: Raspberry Pi, low-power devices.

Reverse Proxy Configuration¶

Nginx¶

server {
    listen 80;
    server_name qbitrr.example.com;

    location / {
        proxy_pass http://localhost:6969;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_cache_bypass $http_upgrade;
    }
}

qBitrr config:

[WebUI]
Host = "127.0.0.1"  # Only listen on localhost
Port = 6969
BehindHttpsProxy = true  # When using HTTPS reverse proxy; trusts X-Forwarded-Proto and sets Secure cookie

Apache¶

<VirtualHost *:80>
    ServerName qbitrr.example.com

    ProxyPreserveHost On
    ProxyPass / http://localhost:6969/
    ProxyPassReverse / http://localhost:6969/

    <Location />
        Require all granted
    </Location>
</VirtualHost>

Enable required modules:

sudo a2enmod proxy
sudo a2enmod proxy_http
sudo systemctl restart apache2

Traefik (Docker)¶

services:
  qbitrr:
    image: feramance/qbitrr:latest
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.qbitrr.rule=Host(`qbitrr.example.com`)"
      - "traefik.http.services.qbitrr.loadbalancer.server.port=6969"
      - "traefik.http.routers.qbitrr.entrypoints=websecure"
      - "traefik.http.routers.qbitrr.tls.certresolver=letsencrypt"

Caddy¶

qbitrr.example.com {
    reverse_proxy localhost:6969
}

Docker Port Mapping¶

Docker Run:

docker run -d \
  --name qbitrr \
  -p 6969:6969 \
  -v /path/to/config:/config \
  feramance/qbitrr:latest

Docker Compose:

version: '3'
services:
  qbitrr:
    image: feramance/qbitrr:latest
    container_name: qbitrr
    ports:
      - "6969:6969"  # External:Internal
    volumes:
      - /path/to/config:/config

Alternative port mapping:

ports:
  - "8080:6969"  # Access on port 8080 externally

Access: http://localhost:8080/ui

WebUI Settings¶

WebUI host, port, and token are configured in config.toml under the [WebUI] section. They are not currently overridable via environment variables; use the config file or the in-app config editor.

Troubleshooting¶

WebUI Not Loading¶

Symptom: Cannot access http://localhost:6969/ui

Solutions:

Check qBitrr is running:

# Docker
docker ps | grep qbitrr

# Systemd
systemctl status qbitrr

# Process
ps aux | grep qbitrr

Verify port:

# Check if port is listening
sudo netstat -tulpn | grep 6969
sudo lsof -i :6969

Check logs:

# Docker
docker logs qbitrr | grep -i webui

# Native
tail -f ~/logs/WebUI.log

Verify configuration:
```
[WebUI]
Host = "0.0.0.0"
Port = 6969
```

401 Unauthorized¶

Symptom: API requests return 401 errors

Solutions:

Check token is set:
```
[WebUI]
Token = "your-token"
```

Include token in requests:

curl -H "Authorization: Bearer your-token" \
  http://localhost:6969/api/processes

Clear browser cache and cookies

Check WebUI logs:

tail -f ~/logs/WebUI.log | grep -i "401\|auth"

Connection Refused¶

Symptom: Browser shows "Connection refused"

Solutions:

Check Host binding:

# If accessing remotely, must not be 127.0.0.1
Host = "0.0.0.0"

Check firewall:

# UFW
sudo ufw allow 6969

# Firewalld
sudo firewall-cmd --add-port=6969/tcp --permanent
sudo firewall-cmd --reload

Docker: Check port mapping:
```
docker port qbitrr
```

Slow Performance¶

Symptom: WebUI is slow or unresponsive

Solutions:

Disable live updates:
```
LiveArr = false
```

Disable grouping:

GroupSonarr = false
GroupLidarr = false

Check resource usage:
```
docker stats qbitrr
htop
```
Clear browser cache
Reduce log retention:
Fewer logs = faster log view
Consider log rotation

CORS Errors¶

Symptom: Browser console shows CORS errors

Solutions:

Access via correct URL:
Use http://localhost:6969/ui
Not http://127.0.0.1:6969/ui (different origin)
Configure reverse proxy correctly:
Set proper headers
See reverse proxy examples above

Security Best Practices¶

1. Use a Strong Token¶

# Generate secure token
openssl rand -hex 32

[WebUI]
Token = "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6"

2. Bind to Localhost with Reverse Proxy¶

[WebUI]
Host = "127.0.0.1"  # Only localhost

Use Nginx/Apache/Caddy for external access with HTTPS.

3. Use HTTPS¶

Never expose WebUI over HTTP on the internet.

Options:

Reverse proxy with Let's Encrypt
Cloudflare Tunnel
VPN (Tailscale, WireGuard)

4. Restrict Network Access¶

Docker:

services:
  qbitrr:
    networks:
      - internal  # Private network only

networks:
  internal:
    internal: true  # No external access

Firewall:

# Only allow from specific IP
sudo ufw allow from 192.168.1.0/24 to any port 6969

5. Regular Updates¶

Keep qBitrr updated for security patches:

# Docker
docker pull feramance/qbitrr:latest
docker restart qbitrr

# PyPI
pip install -U qbitrr2

Performance Tuning¶

For Large Libraries¶

[WebUI]
LiveArr = false  # Disable auto-refresh
GroupSonarr = false  # Faster rendering
GroupLidarr = false  # Faster rendering

In WebUI: - Use search/filters to reduce displayed items - Limit log entries shown

For Low-Resource Systems¶

[WebUI]
Host = "127.0.0.1"
Port = 6969
Token = ""
LiveArr = false
GroupSonarr = false
GroupLidarr = false
Theme = "Dark"  # Lower power on OLED

WebUI Configuration¶

Overview¶

Authentication and first-run¶

Configuration Section¶

Host¶

Port¶

Token¶

AuthDisabled¶

BehindHttpsProxy¶

LiveArr¶

GroupSonarr¶

GroupLidarr¶

ViewDensity¶

Theme¶

Complete Configuration Examples¶

Example 1: Default (Public Access)¶

Example 2: Secured with Token¶

Example 3: Localhost Only (with Reverse Proxy)¶

Example 4: Low Resource System¶

Reverse Proxy Configuration¶

Nginx¶

Apache¶

Traefik (Docker)¶

Caddy¶

Docker Port Mapping¶

WebUI Settings¶

Troubleshooting¶

WebUI Not Loading¶

401 Unauthorized¶

Connection Refused¶

Slow Performance¶

CORS Errors¶

Security Best Practices¶

1. Use a Strong Token¶

2. Bind to Localhost with Reverse Proxy¶

3. Use HTTPS¶

4. Restrict Network Access¶

5. Regular Updates¶

Performance Tuning¶

For Large Libraries¶

For Low-Resource Systems¶

See Also¶