Unmanic

Automated library optimization and re-encoding

Unmanic is a library optimizer that watches your media folders and automatically transcodes files into a unified target format — most commonly H.265/HEVC — to reclaim disk space. It is powered by FFmpeg, configured through a composable plugin pipeline, and includes a built-in scheduler so heavy transcoding can run during off-peak hours. QuickBox Pro installs Unmanic per user from the official PyPI release into an isolated Python virtual environment with a pre-bundled web UI — no Node build, no Docker. The app runs as a per-user systemd service behind the nginx reverse proxy, protected by your QuickBox authentication gate.

Key features

When to use it

Installation

Install from the Dashboard

Open App Dashboard → Package Management (/dashboard?mode=packages), find Unmanic under the Automation category (or search), and click Install. The install dialog has two optional inputs:

1. Custom Library Path — switch to Custom and enter the folder Unmanic should watch and transcode. The default is your Media folder.
2. Custom domain — enter a domain to publish Unmanic on its own subdomain with an SSL certificate (see Custom subdomain with SSL).

Submit and a live install log streams in the response modal. Unmanic appears in your Application Control panel when it finishes, where Reinstall, Update, and Remove are also available. What you see is gated by your account: admins manage any user’s apps; regular users manage their own. See App Management for the full flow.

Install from the CLI (automation)

The CLI runs the same install pipeline as the Dashboard and is suited to automation and scripting. The library path (-l/--library) and subdomain (-d) are the install-dialog inputs above, available as flags:

qb install unmanic -u username
qb install unmanic -u username -l '/home/username/Media'
qb install unmanic -u username -d unmanic.example.com
qb reinstall unmanic -u username
qb update unmanic -u username
qb remove unmanic -u username
qb help unmanic

Full flag reference: CLI Reference.

Access and authentication

After installation, open Unmanic at:

The app redirects you to its dashboard view automatically. You can also reach it from the QuickBox Pro dashboard navigation or the App Dashboard.

When you first open the page, your browser shows a standard authentication prompt. Sign in with your QuickBox username and password — this is QuickBox’s own protection layer in front of the app, not an Unmanic account.

The QuickBox dashboard’s app controls include an nginx authentication toggle for each application. For most apps this is a convenience; for Unmanic it is a safety control — leave it enabled.

Custom subdomain with SSL

By default Unmanic serves under the per-user subpath of your main dashboard domain. You can also publish it on a dedicated subdomain (for example unmanic.example.com) with a Let’s Encrypt certificate. There are three ways to set this up: a single-call install (Path A), a post-install retrofit from the CLI (Path B), and the dashboard SSL Control page (Path C).

The QuickBox authentication gate stays active on the subdomain vhost — moving Unmanic to its own domain does not expose it without credentials.

Path A — Subdomain at install time

Point a DNS record (A or CNAME) for your chosen subdomain at the server, then run:

qb install unmanic -u username -d unmanic.example.com

The install issues the certificate, writes the subdomain vhost, and starts the service in one call. Saved DNS provider credentials are auto-detected and switched to the appropriate DNS challenge automatically.

Path B — Retrofit a subdomain to an existing install

If Unmanic is already installed and you want to move it to a dedicated subdomain, issue the certificate with the Unmanic-specific lecert flag:

qb install lecert --unmanic -d unmanic.example.com -u username

This uses the same shape as every other lecert-managed application (--emby, --jellyfin, --plex, --komga, etc.).

Wildcard or DNS challenge: add --dns --dns-provider cloudflare (or another supported provider). See the Let’s Encrypt application reference for the full list of supported DNS providers.

Testing without rate-limit exposure: add --staging to issue against the Let’s Encrypt staging CA, or --dry-run to validate the ACME challenge without writing any certificate or nginx changes.

Path C — Dashboard SSL Control

The dashboard’s SSL Control page at System → SSL Control (/system/ssl) exposes the same flow: pick Unmanic as the target, enter your domain and username, choose the challenge method, and submit. See the SSL Certificates dashboard page for end-to-end SSL setup, supported DNS providers, and renewal behavior.

Hardware and GPU acceleration

Unmanic encodes with CPU (libx265/libx264) by default, and that works out of the box on every QuickBox server — FFmpeg is already part of the base system and nothing extra needs to be installed.

Nvidia NVENC hardware acceleration is an optional, advanced setup for users who already have an Nvidia GPU in the server. QuickBox does not install Nvidia drivers or GPU packages — if you want NVENC you must install the Nvidia driver stack and an NVENC-capable FFmpeg yourself, then select the NVENC encoder in your Unmanic transcode plugin settings. See the upstream Unmanic documentation  for GPU setup guidance.

Performance and scheduling

Transcoding is one of the most CPU-intensive workloads you can run on a server. QuickBox governs the Unmanic service so it cannot starve other users or applications:

• Low priority — the service runs at a reduced CPU priority (Nice=15), so interactive workloads always win the scheduler
• Core cap — the service is capped at roughly two CPU cores (CPUQuota=200%) regardless of how many workers you configure

Within that budget, Unmanic’s own controls are the knobs you tune:

1. Worker count — in the Unmanic web UI under Settings → Workers, set how many files are transcoded in parallel. On a shared server, one or two workers is usually right.
2. Worker schedules — also under Settings → Workers, restrict transcoding to off-peak hours so the heavy work runs while the server is otherwise idle.

Configuration and files

Common tasks

Change the library Unmanic watches

Open the Unmanic web UI and go to Settings → Library to change the library path or scan behavior. Enable the library scanner schedule and the file monitor so new downloads are picked up automatically.

Set up a transcode flow

Unmanic’s processing is driven entirely by plugins:

1. Go to Plugins in the web UI
2. Install a video transcoder plugin (for example Transcode Video Files) from the plugin repository
3. Configure it — pick your target codec (H.265/HEVC on CPU is the standard choice)
4. Add the plugin to your library’s plugin flow under Settings → Library

Files that already match the target format are skipped, so re-running over the same library is safe.

Tune workers and schedule

Under Settings → Workers, set the worker count (parallel transcodes) and define worker event schedules to pause or resume transcoding at set times — for example, pause at 08:00 and resume at 01:00 so conversions only run overnight.

Update Unmanic

qb update unmanic -u username

The update upgrades the application in place and restarts the service. Your settings, database, plugins, and library are preserved — the database migrates automatically on the next start.

Remove Unmanic

qb remove unmanic -u username

Remove deletes the application environment, its settings, database, plugins, and cache, plus any custom subdomain vhost.

Service management

Unmanic runs as a per-user systemd service. Replace username with the actual QuickBox username:

# Check status
systemctl status unmanic@username
 
# Restart the service
systemctl restart unmanic@username
 
# Stop the service
systemctl stop unmanic@username
 
# Follow live logs
journalctl -u unmanic@username -f

Unmanic’s own application log is at /home/username/.config/Unmanic/.unmanic/logs/unmanic.log.

Troubleshooting

Unmanic will not start

Transcoding is slowing down the server

The service is already capped at two cores and low priority, but inside that budget you control the load. Reduce the worker count to 1 under Settings → Workers, and add a worker schedule so transcoding only runs off-peak. Check current load with:

systemctl status unmanic@username

NVENC encoder errors

If a transcode fails with hevc_nvenc or CUDA errors, the server does not have working Nvidia drivers and an NVENC-capable FFmpeg. Switch the transcoder plugin back to the CPU encoder (libx265) — see Hardware and GPU acceleration.

Disk filling up during conversions

In-progress transcodes are written to the cache directory at /home/username/.config/Unmanic/cache before replacing the original file. Large libraries with many parallel workers need headroom there — reduce the worker count if free space is tight, and clear any leftovers from interrupted conversions:

du -sh /home/username/.config/Unmanic/cache

Browser keeps asking for a password

That prompt is the QuickBox authentication gate — sign in with your QuickBox username and password. If the credentials are rejected, your QuickBox password may have changed; the gate always uses your current QuickBox account password.

Best practices

FAQ

Related applications

Resources