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
Automatic Transcoding
Re-encode your library to H.265/HEVC (or any FFmpeg-supported format) to reclaim disk space
Library Watching
Continuous file monitoring plus scheduled full library scans pick up new and changed files
FFmpeg Powered
CPU encoding by default with optional Nvidia NVENC hardware acceleration for GPU owners
Plugin Pipeline
Composable plugin flows for transcoding, remuxing, audio, subtitle, and file naming tasks
Worker Pool
Run multiple transcode workers in parallel and tune the count to your hardware
Built-In Scheduler
Restrict heavy transcoding to off-peak hours with per-worker event schedules
Custom Library Path
Point Unmanic at any folder in your home tree at install time with the --library flag
Live Dashboard
Watch pending tasks, active workers, and completed conversions update in real time
Every QuickBox user who installs Unmanic gets their own Python environment, configuration, database, plugins, and cache. Users do not share libraries, settings, or transcode queues.
When to use it
Good fit
- You want to shrink a large media library by re-encoding it to H.265/HEVC, hands-off
- You want every file in your library normalized to one container and codec
- You want automated post-download cleanup — remux, strip streams, reorder audio
- You can schedule heavy work for off-peak hours with the built-in scheduler
Look elsewhere
- Your server is CPU-constrained and cannot spare cores for sustained transcoding
- You only need on-the-fly transcoding for playback — Plex, Emby, and Jellyfin already do that
- You need per-file manual renaming and metadata control — see FileBot instead
- You want to keep original files untouched — Unmanic replaces files in place
Unmanic re-encodes files in place — the original file is replaced by the converted output. Test your plugin flow on a small folder before pointing Unmanic at an entire library, and keep backups of anything irreplaceable.
Installation
Install from the QuickBox CLI
Install Unmanic for a specific user under the per-user subpath:
qb install unmanic -u usernameInstall with a custom library path — the folder Unmanic watches and transcodes:
qb install unmanic -u username -l '/home/username/Media'Install and publish on a dedicated subdomain in one call — this issues the Let’s Encrypt certificate and writes the subdomain nginx vhost as part of the install:
qb install unmanic -u username -d unmanic.example.comCLI commands
| Command | Description |
|---|---|
qb install unmanic -u username | Install Unmanic under the per-user subpath |
qb install unmanic -u username -l <path> | Install with a custom library path |
qb install unmanic -u username -d <domain> | Install and publish on a dedicated subdomain with SSL in one call |
qb reinstall unmanic -u username | Reinstall Unmanic — rebuilds the app environment and resets its settings |
qb update unmanic -u username | Update to the latest release — settings and database are preserved |
qb remove unmanic -u username | Remove Unmanic and its settings — your media library is never touched |
qb help unmanic | Display help information |
Install flags
| Flag | Description |
|---|---|
-u <username> | Target QuickBox user for the per-user install (required) |
-d <domain> | Install in subdomain mode — issues SSL and writes the subdomain vhost |
-l <path>, --library <path> | Library path Unmanic watches and transcodes. Defaults to /home/username/Media, or /home/username/rclone/cache when Rclone is installed |
Install from the Dashboard
The recommended way to install Unmanic is from the QuickBox Pro dashboard:
- Open App Dashboard → Package Management (
/dashboard?mode=packages) - Find Unmanic under the Automation & Tools category
- (Optional) Switch Custom Library Path to Custom and enter the folder Unmanic should watch — the default is your Media folder
- (Optional) Enter a custom domain to publish Unmanic on its own subdomain with SSL
- Submit — a live install log streams in the response modal
The dashboard runs the same install pipeline as the CLI and installs Unmanic for the currently signed-in user.
QuickBox picks a free port near the upstream default of 8888 and binds Unmanic to 127.0.0.1 only — the app is never reachable directly from the internet. All access goes through the nginx reverse proxy.
Access and authentication
After installation, open Unmanic at:
https://your-server/username/unmanic/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.
Unmanic ships no built-in authentication, and its plugin system can execute arbitrary commands on your account. The QuickBox authentication gate in front of the reverse proxy is the only thing standing between the open internet and your Unmanic instance — on both the per-user subpath and any custom subdomain. Never disable nginx authentication for Unmanic, and never expose its internal port directly.
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.comThe 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 usernameThis 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.
You do not need a GPU to use Unmanic. CPU encoding with libx265 produces excellent quality and works on every server — it is simply slower than hardware encoding. If an NVENC encoder fails with driver errors, switch the plugin back to the CPU encoder.
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:
- 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.
- Worker schedules — also under Settings → Workers, restrict transcoding to off-peak hours so the heavy work runs while the server is otherwise idle.
A library conversion is a marathon, not a sprint. Pair a modest worker count with an overnight schedule and Unmanic will steadily chew through the queue without anyone noticing it is running.
Configuration and files
When Rclone is installed for the user, the default library path is /home/username/rclone/cache; otherwise it is /home/username/Media. Pass -l <path> (or —library <path>) at install time to choose a different folder, or change it later in the Unmanic web UI under Settings → Library.
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:
- Go to Plugins in the web UI
- Install a video transcoder plugin (for example Transcode Video Files) from the plugin repository
- Configure it — pick your target codec (H.265/HEVC on CPU is the standard choice)
- 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 usernameThe 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 usernameRemove deletes the application environment, its settings, database, plugins, and cache, plus any custom subdomain vhost.
Removing Unmanic never touches the library folder — your media files stay exactly where they are, including any files Unmanic already converted.
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 -fUnmanic’s own application log is at /home/username/.config/Unmanic/.unmanic/logs/unmanic.log.
Troubleshooting
Unmanic will not start
Symptoms
- systemctl status unmanic@username shows failed or activating
- The web UI returns a 502 from nginx
- journalctl shows Python tracebacks on startup
Resolution
- Read the journal first: journalctl -u unmanic@username -n 50
- Confirm the launcher exists: ls /opt/username/lib/python/Unmanic/.venv/bin/unmanic
- If the environment is broken (for example after a distro upgrade), run qb update unmanic -u username — it rebuilds the Python environment when missing
- If problems persist, qb reinstall unmanic -u username performs a clean rebuild
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@usernameNVENC 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/cacheBrowser 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
Do
- Test your plugin flow on a small folder before unleashing it on a full library
- Keep the QuickBox authentication gate enabled — it is Unmanic's only protection
- Use a low worker count and an off-peak schedule on a shared server
- Keep backups of irreplaceable media — Unmanic replaces files in place
- Keep Unmanic updated with
qb update unmanic -u username - Use
libx265CPU encoding unless you have a working Nvidia driver stack
Don't
- Don't disable nginx authentication for Unmanic — the app has no login of its own and plugins can run arbitrary commands
- Don't expose Unmanic's internal port directly — always go through the nginx reverse proxy
- Don't point Unmanic at a library you have no backup of until you trust your plugin flow
- Don't crank the worker count on a shared server — the per-service core cap means more workers just split the same budget
- Don't install plugins from sources you do not trust — plugins execute code on your account
- Don't transcode media you intend to keep at original quality — re-encoding is lossy
FAQ
Nice=15), so other applications and users always take precedence. Within that budget, tune the worker count and use Unmanic's built-in scheduler under Settings → Workers to keep heavy transcoding in off-peak hours.libx265 is the default and works on every QuickBox server with nothing extra to install. Nvidia NVENC is an optional, advanced setup for users who already have a GPU — QuickBox does not install Nvidia drivers or GPU packages./home/username/.config/Unmanic/ — settings at .unmanic/config/settings.json, the SQLite database at .unmanic/config/unmanic.db, logs, plugins, and the transcode cache. The nested .unmanic folder is upstream behavior.qb update unmanic -u username upgrades the application and restarts the service — your settings, database, plugins, and library are untouched, and the database migrates itself automatically on the next start. A reinstall, by contrast, is a clean rebuild that resets the app's settings.qb remove unmanic -u username deletes the application environment, settings, database, plugins, and cache — but the library folder and every media file in it are left exactly as they are, including files Unmanic already converted.-l <path> (or --library <path>), or set it in the dashboard install dialog. On an existing install, change it in the Unmanic web UI under Settings → Library. The default is /home/username/Media, or /home/username/rclone/cache when Rclone is installed.-d <domain> to qb install unmanic at install time (Path A), retrofit an existing install with qb install lecert --unmanic -d <domain> -u <username> (Path B), or use the dashboard's System → SSL Control page with Unmanic as the target (Path C). The QuickBox authentication gate stays active on the subdomain./unmanic/ URL base, so on the per-user subpath the full dashboard address looks like https://your-server/username/unmanic/ui/dashboard/. This is normal — just open https://your-server/username/unmanic/ and the app routes you to the right place.Related applications
Resources
Join the Community
Media server operators sharing configs, getting support, and shaping the future of QuickBox Pro.