Nudgarr keeps your Radarr and Sonarr libraries improving automatically. Three independent pipelines handle Cutoff Unmet searches, missing content Backlog nudges, and CF Score upgrades for files that score below your quality profile cutoff. Set your limits, configure your schedule, and let it run.
Images are available on Docker Hub and GitHub Container Registry (GHCR).
| Registry | Image |
|---|---|
| Docker Hub | mmagtech/nudgarr:latest |
| GHCR | ghcr.io/mmagtech/nudgarr:latest |
Tags: latest · v5.0.2 · 5.0.2
- Copy
.env.exampleto.envand fill in your values - Run
docker compose up -d - Open
http://<your-host>:8085
PUID=1000
PGID=1000
PORT=8085
CONFIG_PATH=/your/path/to/appdata/nudgarr
TZ=UTC
# SECRET_KEY=your-secret-key # optional, auto-generated if not setA ready-to-use docker-compose.yml is included in the repo root. Copy it alongside a .env file — see .env.example for all available options.
Nudgarr includes a full web UI accessible from any browser on your network. No separate app required — just navigate to http://your-host:8085 after setup.
The interface covers everything in one place: instance management, sweep status and history, confirmed imports with quality upgrade tracking, exclusions, notifications, and per-instance configuration. The UI is fully responsive and works on any screen size — every feature, including CF Score, Intel, and Overrides, is accessible on mobile.
Core
- Cron-based scheduler with configurable expression and timezone support, or manual-only mode
- Skip Queued — items already in the download queue are silently bypassed; max per run always filled from actionable items
- Per-instance enable/disable — disabled instances skipped in sweeps and health checks
- Per-app sample modes — Random, Alphabetical, Oldest Added, Newest Added independently for Radarr and Sonarr
- Configurable cooldown, batch size, sleep, and jitter controls for indexer rate limit compliance
- Per-app Backlog Nudge toggles with Missing Added Days age filter and per-instance caps
- Radarr minimumAvailability filter — movies that haven't reached their availability threshold are automatically skipped
UI
- Web UI with sidebar navigation — Monitor group (Sweep, Library, Intel), Configure group (Instances, Pipelines, Settings, Overrides, Filters, Notifications), System group (Advanced)
- Sidebar is always visible; unsaved changes shown as an amber dot on the relevant nav item
- Sweep panel — three pipeline cards (Cutoff Unmet, Backlog, CF Score) with aggregate totals and per-instance breakdowns; Sweep Health, Last Sweep, and Imports Confirmed summary cards; full-width paginated feed of every item searched in the current sweep with pipeline badges
- Library panel — consolidated view switcher for History, Imports, CF Score, and Exclusions in one place
- Intel panel — lifetime performance dashboard showing Import Summary (turnaround, searches per import, pipeline breakdown with conversion rate), Instance Performance, Upgrade History, CF Score Health, and Exclusion Intel. All stats are hard facts derived directly from the database.
- Search history with sweep type, instance, library added date, search count, sortable columns, and title search
- Clickable titles in History and Imports — opens the item directly in the configured Radarr or Sonarr instance
- Auto-exclusion badge and confirmed import tracking with lifetime totals, period toggle, type filtering, title search, and quality upgrade history per item
- Apprise notifications — sweep complete, import confirmed, auto-exclusion, and error triggers per instance
- Configurable log level (DEBUG / INFO / WARNING / ERROR) set live from the Advanced tab with no container restart
- Diagnostic download includes the last 250 lines of
nudgarr.logwith URLs masked - First-run onboarding walkthrough and What's New modal on upgrade
Mobile
- Fully responsive desktop UI — all features available on any screen size, no separate layout or URL
- Sidebar collapses to a compact nav on narrow screens; pipeline cards, grids, and tables reflow at phone width
- Tables (History, Imports, CF Score) scroll horizontally with the title column pinned
- iOS and Android browser toolbar matches the app via
theme-color
Power User
- CF Score Scan — finds monitored items where the custom format score is below the quality profile cutoff even when Radarr and Sonarr don't flag them via their normal wanted system. Enable in Advanced to unlock the CF Score tab.
- Auto-Exclusion — titles searched N times with no confirmed import are automatically excluded. Configure separate thresholds for Radarr and Sonarr in Advanced. Auto-unexclude after X days returns titles to eligibility.
- Tag & Quality Profile Filters — exclude items from sweep by tag or quality profile, configured per instance. Items matching an excluded tag or profile are skipped before cooldown runs and never consume a search slot.
- Per-Instance Overrides — tune cooldown, max cutoff unmet, max backlog, max missing days, sample mode, backlog enabled, and notifications independently per instance. Unset fields inherit the global value. Enable in Advanced and configure in the Overrides tab. Full details on the wiki.
- Maintenance Window — suppress scheduled sweeps during a defined time window. Manual Run Now always bypasses it. Configure in Settings.
- Backlog Grace Period — delay the first search on a missing item until a configured number of hours after its availability date, giving indexers time to populate.
- Exclusions — click the ⊘ icon on any History row to permanently exclude a title from future searches. Exclusions are global across all instances. Manage the full list in the History tab.
Full documentation is available on the Nudgarr Wiki, including:
Nudgarr runs as the user you specify — no permission issues with your /config volume.
| Platform | Typical values |
|---|---|
| Unraid | PUID=99 PGID=100 (nobody:users) |
| Linux | PUID=1000 PGID=1000 |
| Synology | Match your DSM user — check with id over SSH |
Defaults to 1000:1000 if not set.
| File | Purpose |
|---|---|
/config/nudgarr-config.json |
All settings |
/config/nudgarr.db |
SQLite database — history, stats, exclusions, and app state |
/config/logs/nudgarr.log |
Rotating log file — 5 MB per file, 3 backups. Log level set in Advanced tab. |
Nudgarr is a local network tool. The login screen provides basic access control — it is not a hardened security layer. Passwords use PBKDF2-HMAC-SHA256 with a unique random salt, and failed attempts trigger a progressive lockout.
Run on your LAN only. For remote access use a VPN (Tailscale, WireGuard) or a reverse proxy with HTTPS. Do not expose port 8085 to the internet.
v5.0.0 is a full frontend rewrite to Alpine.js with a sidebar navigation layout. The 14-file vanilla JS split is replaced by a single app.js and ui.html. The horizontal tab bar is gone -- navigation is now a sidebar with Monitor, Configure, and System groups. History, Imports, CF Score, and Exclusions are consolidated into a single Library panel with a view switcher. CF Score can now be toggled independently per app (Radarr/Sonarr) and per instance. No config changes required. Pull the new image and restart. New config keys are injected automatically on first start.
v5.0.2 is a patch release: dependency bumps (flask, requests, urllib3) and Docker build upgrades pip to address reported CVEs. No config changes required. Pull the new image and restart.
v5.0.1 is a patch release: Library History type/title filters, CF Score table sort/search/total and instance filter fix, Exclusions/Imports UI tweaks, default panel validation for library / pipelines, and documentation updates. No config changes required. Pull the new image and restart.
v4.3.0 rebuilds the Intel tab with five focused cards showing hard facts from your database with no scoring or assumptions. Includes the sample mode overhaul (Round Robin across all pipelines, full CF Score mode control), auto-exclusion queue fix, and KPI number formatting for mobile. No config changes required. Pull the new image and restart. New config keys are injected automatically on first start.
v4.2.1 — folded into v4.3.0, never publicly shipped.
v4.2.0 adds CF Score Scan, Intel tab, Sweep tab redesign, responsive desktop UI (mobile UI removed), sticky header, exclusion event tracking, backlog sample mode split, maintenance window, grace period, and Settings tab cleanup. No config changes required. Pull the new image and restart. Migrations v10 and v11 run automatically on first start. Existing data is fully preserved.
v4.1.0 adds auto-exclusion, import stats period toggle, and logging improvements. No config changes required. Pull the new image and restart. Migration v9 runs automatically on first start. From this version onwards, static assets include version query strings — browsers automatically receive fresh JS and CSS after a container upgrade without requiring a hard refresh.
v4.0.0 is the foundations release. No config changes required, no data migration needed. Pull the new image and restart. If upgrading directly from v3.1.x or earlier, upgrade to v3.2.0 first.
For full version history see CHANGELOG.md.
See CONTRIBUTING.md for project structure and development guide. For usage questions, the wiki is the first stop.
Join the community on Reddit at r/nudgarr — share configs, ask questions, and follow development updates.