⚡ nzbfast

The fast Usenet downloader - user manual

1 · Welcome

nzbfast downloads from Usenet as fast as your line, your providers, and your machine allow - and usually that means as fast as your line. It is a single self-contained program: the engine, a web dashboard, a poster-wall media browser, a built-in indexer, realtime preview, native PAR2 repair, and native RAR extraction are all inside one executable. There is nothing else to install.

What makes it fast is architecture, not tweaks:

• Pipelined NNTP: many article requests ride each connection back-to-back, keeping every connection at full speed instead of waiting out round-trips.
• A one-pass pipeline: downloading, verification, and extraction overlap. Archive volumes are extracted in the stream; on a typical store-mode post the RAR files never touch your disk, so the job needs 1× the release size, not 2×, and finishes when the download finishes.
• Multi-provider union: every configured server contributes; an article missing on one backbone is fetched from another. Slow or dead servers never stall the queue.
• A memory budget: the engine adapts to a bounded RAM allowance and degrades to disk if needed. It never swaps your machine.

Measured against the field on identical hardware, jobs and providers, nzbfast has finished a 190 GB download in around 5 minutes on a 10 GbE line, with the leading alternatives 30–220% behind on the same tests where they completed them at all. The figures are in §3.

2 · Quick start

macOS

1. Open nzbfast-<version>-macos.dmg and drag NzbFast into Applications (universal: Apple Silicon + Intel).
2. First launch: macOS warns that nzbfast isn't Apple-notarized yet. Right-click the app → Open, or open System Settings → Privacy & Security, scroll down, and click Open Anyway. This is a one-time step.
3. The app window shows the dashboard with a welcome card. Click it and add at least one Usenet server (host, port 563, username, password). You can add more later in Settings.
4. Drop an .nzb anywhere on the dashboard, or just double-click .nzb files in Finder. Downloads land in ~/Downloads/nzbfast. Quit from the menu; downloads resume where they left off.

Prefer no app? The plain zip (binary + Start nzbfast.command launcher, same engine) still works as before. The steps are below, under "From a terminal".

Windows

1. Run nzbfast-setup-<version>.exe. It installs for your user only (no administrator password). Because this release is not yet code-signed, SmartScreen may show "Windows protected your PC". Click More info → Run anyway.
2. nzbfast lives in the system tray: double-click the tray icon (or use Open Dashboard in its right-click menu) to open the dashboard, then add your Usenet server from the welcome card. The tray menu also has Pause/Resume, your downloads folder, and Quit.
3. Double-clicking a .nzb file queues it. Windows Defender may ask once to allow local network listening. Allow it.

Prefer a portable copy? The -windows-x64.zip still works: unzip anywhere and double-click nzbfast.exe (or Start nzbfast.bat) for the terminal wizard.

From a terminal (any platform)

nzbfast setup            # interactive server setup (writes config.local.json)
nzbfast serve --open     # start the daemon and open the dashboard

3 · How nzbfast works

A quick vocabulary so the rest of the manual reads easily:

The pipeline runs download → decode → verify → extract concurrently. The Pipeline card on the dashboard shows all three lanes moving at once. When the last byte arrives, verification is already done and the file is already extracted; a typical job's "post-processing" time is zero. If repair is needed, only then are volumes materialised to disk, repaired in place by the native GF(2¹⁶) engine (renamed or byte-shifted obfuscated data is found and adopted by a sliding block scan), and re-extracted, all automatically.

Interrupted downloads (crash, power loss, kill -9) resume from the article journal: bytes already on disk are never fetched twice. The journal records where every article's bytes physically landed (even bytes that were direct-extracted into the final file), so a resume rebuilds from local disk and re-verifies everything it restored against the PAR2 block map before trusting it.

How that compares

Measured against SABnzbd 5.0.4 and NZBGet 26.2 on the same machine, the same providers and the same NZBs, timed to a usable file (download, verify, repair and extract all included), because that is when the job is actually done:

The gap is the post-processing the others still have to do after the last byte lands. Both competitors were tuned for the comparison, not left on defaults. SABnzbd in particular ships with request pipelining off, which costs it dearly, so it was switched on.

Two differences matter as much as the times:

• Disk space. One pass needs 1× the release size; clients that write archive volumes and then unpack them need 2×. On a test machine with 97 GB free, an 87 GB job finished here in 3 m 08 s and the other two could not run at all.
• Memory. On the 190 GB job, peak usage was 3.9 GB against SABnzbd's 9.3 GB , and nzbfast will do the same job in about 1 GB if told to (see Memory budget).

4 · The dashboard

Open http://localhost:6789 (or your machine's address from another device; the phone layout adapts automatically). Everything updates live, once a second. The cards, top to bottom:

Header bar

• Speed limit menu: fixed caps, auto · yield to LAN (an RTT-governed mode that backs off when someone else in the house needs the line), or unlimited.
• Pause for… stops everything for 15 min/30 min/1 h/3 h with automatic resume, or use the Pause button for an open-ended pause. Pause is immediate: the active transfer stops within seconds and resumes later from the journal, losing nothing. (Force-priority jobs keep downloading, SABnzbd-style.)
• An update banner appears here when a new version is available (see Updates).

Throughput

Live MB/s with a scrolling chart; the dashed watermarks mark this session's high/low, the faint line is a moving average. Below it, a histogram shows how the session's speed samples distribute: typical vs peak. Widen the window and the charts show more history (up to an hour).

Stat tiles

Downloaded this session, queue depth, completed/failed counts, session peak speed.

Resources: one machine, four ceilings

CPU, RAM (against nzbfast's memory budget), disk write rate and network on one normalized chart, with real values in the legend and a low-disk warning. No other NZB client shows you this; it exists to prove a point: nzbfast will max your line, not your machine.

Pipeline: stages overlap

Three lanes: download, verify (PAR2 blocks checked), extract. On a healthy job all three move together.

Providers

Per-server live rate, connection utilisation, share of traffic, session GB, and a lifetime article-completion score (colored when a server drops below 98%). A stacked area chart shows each provider's contribution over time. Rows re-order by live performance every 10 s (configurable in Settings → Interface) so your fastest provider is always on top.

Queue

• Drag rows to reorder (within a priority band; Force/High still run first); change priority inline.
• Click a row for the detail drawer: per-file progress bars, verify block counts, and which server contributed how much to this job.
• Badges show special states: deferred (slow), prefetching, paused (see Performance tools).
• A burn-down chart tracks total GB remaining across the queue.

Browse index

Search everything the built-in indexer has catalogued from your watched groups (see Automation) and download with one click, no external indexer needed. The status line shows scan progress; Scan now forces a pass.

Watchlist

Add titles by name, including ones not posted yet. When a matching release appears in the index it is grabbed automatically, with quality preferences and upgrade rules (a better copy replaces a worse one).

History

Recent downloads with status, size, location; failed jobs offer Retry (resumes from the journal). Encrypted archives show a 🔑 unlock control: enter the password and the job finishes in place. The verify-health strip charts bad PAR2 blocks per download: a rising tail means articles are arriving damaged.

Data usage

Per-provider daily bars and Today / 7-day / 30-day totals, essential for metered and block accounts. Block accounts show lifetime usage against their size.

Log, System benchmark, Connection tuning, Server diversity

An in-page log viewer, and the three self-measurement tools described in Performance tools.

5 · Adding downloads

Categories, priorities, passwords

• Categories are free-form labels; each becomes a subfolder of your download directory, and Smart Folders (see §10) can assign them by rule.
• Priorities: Force > High > Normal > Low. Force bypasses pause and quota.
• Passwords for encrypted archives are picked up automatically from <meta type="password"> inside the NZB or a Name{{password}}.nzb filename, and can be supplied per-job through the API or afterwards from History (🔑).

6 · The poster wall

Click 🎬 wall in the header. The wall turns your index into a media browser: every recognised film and TV release as a poster tile with rating, year, genres, cast and synopsis: your newsgroups, browsable as a catalogue.

• Tabs for Films / TV / Other, instant search, and seven sort orders: For you, Newest posts, Release year, Top rated, Title A-Z, Largest and Most posted.
• Matched only is on by default, hiding unidentified junk; a "+N unmatched" chip reveals it.
• For you ranks the wall against a taste profile built on this machine from your own completed history and watchlist: favoured genres, whether you lean film or TV, and roughly which era. Titles you already have sink to the bottom rather than disappearing, and a "Because you watch …" caption says what it keyed on. With no history yet it falls back to Most posted, so it is never an empty tab. Nothing about your taste leaves the daemon.
• Not interested on any tile hides that title, and hiding a few similar ones teaches the wall: it offers a one-click filter ("Hide all Reality titles from now on?"). Everything you have hidden, and every learned filter, is listed under Hidden & filters and can be undone there.
• A small availability dot on a tile is the oracle's verdict (§13): amber "?" means uncertain on your providers, red means its parts keep coming back missing. Whole groups being actively cleared show a reaped badge.
• Click a tile for the detail sheet: synopsis, IMDb rating and votes, cast, and ▶ Play (preview it immediately, see §7) or ⬇ Download.
• ✎ Fix match: if a title matched the wrong show or film, pick the right one from candidate posters, or enter title/year/kind manually. Manual text is never overwritten by the enricher. ↻ Refresh metadata re-fetches one title; Settings → Indexing can refresh all or wipe/rebuild the whole index.
• Metadata is keyless by default: TVmaze, iTunes, IMDb datasets, Wikidata, Wikipedia and AniList need no accounts. An OMDb key (free, email-only signup; there's a signup helper in Settings → Indexing) improves film matching; a TMDB key is honoured if you already have one.

7 · Preview & verify

You don't have to wait for a download to finish to know it's the right file. Open it while it downloads, check the content, language and quality are what you expected, and cancel early if they aren't, instead of finding out after the full download.

• ▶ Play on the wall (or /m3u/<id>) hands your media player an URL; the daemon starts or reuses the download behind it.
• The /stream/<nzo_id> endpoint serves the file with full HTTP range support while it downloads. Checking any point works: spot-check minute 40 and the articles for that region are promoted to the front of the download queue. It opens there in a couple of seconds instead of minutes. The head and tail of the file are fetched first so players find their index data immediately.
• Library mode: categories listed in library_cats become instant metadata-only entries: a .strm file appears at once, availability is verified in the background, and the real download starts when you first open it.

8 · Usenet servers

Settings → Usenet servers is the full editor: add, edit, remove, reorder, and switch any server in or out of the pool. Each server has:

Two further per-server options have no dashboard control yet: add them by hand to that server's entry in config.local.json (see §17) and restart.

• The tick beside each server is its on/off switch: ticked means the server is in the download pool, unticked means it is disabled. A disabled server keeps its credentials and settings and can still be tested; it is simply never asked for articles. Its row dims, the heading count ("2 of 3 active") drops, and the change applies from the next download. Handy for resting a block account you are saving, or for proving one provider is behind a problem without deleting it.
• Test does a real connect + TLS + login and reports round-trip time.
• Import from SABnzbd / NZBGet… scans the usual install locations, shows what it found, and copies servers in (skipping duplicates).
• Server edits apply from the next download: no restart.

9 · Settings reference

Nearly everything is configurable from the dashboard, under ⚙ Settings; the four exceptions are listed at the end of this section. Values marked live apply immediately; restart values apply on the next launch. Every change made here is persisted to settings.json and survives restarts (UI values win over command-line flags).

Speed & scheduling live

Next download live

Connections (per server), window (pipelining depth per connection), decoders (parallel decode threads). Sampled when each job starts. Defaults are right for most lines; use the tuning tools before raising blindly.

Fast verify (CRC32) (on by default) claims PAR2 blocks by CRC32 while the download is still running, which is 2-3x faster on a slow CPU. Every article's own checksum is still verified, and the final settle pass always uses full MD5, so this trades no correctness. Untick it to do per-block MD5 during the download too.

Disk & quota live

Minimum free space (pause new jobs below it), download quota per day or month (UTC; Force jobs bypass), memory limit, the engine's RAM budget (default: ¼ of RAM, clamped; raise it on a big-RAM box for maximum speed on huge jobs, and see what low memory costs before lowering it) restart.

Move completed to: after unpack, cleanup and renaming, finished downloads move here - a NAS share, a media drive, wherever your library lives. The category layout is preserved (a job that finished under tv/ lands under tv/ at the destination), and history follows the move, so connected apps import from and delete at the new location. If the destination is unreachable when a job finishes (share offline, out of space), the files stay in the download folder and the job still completes normally. Empty = off. Per-category destinations route specific categories elsewhere (tv=/Volumes/NAS/TV, movies=/Volumes/NAS/Movies); each listed path is that category's folder, so no extra category subfolder is created inside it. Unlisted categories follow Move completed to.

Nested archive depth (default 5) is how many archive-in-archive layers are unpacked automatically: a RAR set containing a 7z containing another RAR is normal on Usenet, and nzbfast follows the chain without a second pass. At the limit the deepest archive is simply left in place, unpacked no further, and the download still completes. Raise it only for unusually deep releases.

Naming & cleanup live

Rename finished downloads (on by default) gives the folder and the main file a clean, informative name: a film becomes Example Movie (2024), TV keeps Show - S01E02. Obfuscated or unrecognised names are left exactly as posted rather than guessed at.

The whole group runs after repair and unpack and before Move completed to, and is skipped entirely for a job still waiting on a password. Both delete steps apply only to releases recognised as film or TV: a software payload or an unclassifiable (obfuscated) set is never swept.

Folders & processing

Download folder restart, watch folder, post-processing script (run after every job with SABnzbd-compatible arguments and SAB_* environment; existing SAB scripts work unchanged), cleanup extensions (junk files deleted after completion), Smart Folders and TV filing (see §10).

Indexing live

Library, Security, Interface

Library: categories treated as instant library entries + re-check interval. Security: the full API key (everything) and the NZB key (add-only, safe to give indexer sites), both rotatable live. Interface: click sounds, desktop notifications on completion, provider re-sort interval.

Speed units live decides how every speed in the dashboard is shown: megabytes (MB/s, the download-manager norm, the default) or megabits (Mb/s, how ISPs quote line speeds). File sizes stay in bytes either way. This is a property of the daemon, not of your browser, so it applies to every device looking at this install.

Advanced: settings with no dashboard control

Four settings have no UI control and no command-line flag. Set them through the API (§16), e.g. /api?mode=config&name=verify_mode&value=lean&apikey=…. Like every other setting they persist to settings.json.

10 · Automation

Watchlist

The simplest automation: add a title on the dashboard, set quality preferences, done. New releases are grabbed as they appear in your indexed groups; better-quality copies upgrade earlier grabs; a calendar view shows what's coming.

RSS feeds

Settings → RSS: any newznab/indexer RSS URL with per-feed interval, category and filter rules (title patterns, size bounds). Matching items are downloaded automatically.

Smart Folders

Rules evaluated when a job is added: match by pattern/keywords and size, assign a category (first match wins). With TV filing on, finished TV episodes are renamed and filed as Show/Season 01/Show - S01E02.mkv, ready for Plex or Jellyfin without an external tool.

Scheduler

The weekly schedule (see §9) automates pause/resume/speed by time of day.

Scripts

A post-processing script receives SABnzbd's positional arguments and SAB_* environment variables: the large ecosystem of SAB scripts runs as-is.

11 · Sonarr, Radarr & friends

nzbfast speaks the SABnzbd API natively, so every *arr works out of the box, and it can act as their indexer too.

As the download client

1. In Sonarr/Radarr: Settings → Download Clients → add SABnzbd.
2. Host: your nzbfast machine · Port: 6789 · API key: your full API key (Settings → Security; the QR/copy control is next to it).
3. Category as desired (e.g. tv / movies). Test → green check → Save.

Queue, history, per-job status, "remove & delete", retry and category routing all behave as the *arrs expect.

As an indexer (newznab)

1. Settings → Indexers → add Newznab.
2. URL: http://<host>:6789/ · API path: /api · key: your API key.
3. nzbfast serves caps, search, tvsearch and movie queries from its own index of your watched groups, and /getnzb/<id> hands back the NZB.

12 · Phone & remote apps

nzbfast implements both major remote-control protocols, so nearly every mobile/tablet app works. Pick whichever protocol your app supports:

Apps that speak NZBGet (nzb360, LunaSea, NZB Unity…)

The full JSON-RPC surface these apps use is served: status, queue with reorder/pause/delete, history, add-NZB, speed limit, pause/resume, log.

Apps that speak SABnzbd

The dashboard on your phone

Just open http://<machine>:6789 in a mobile browser. The whole dashboard and wall have a touch layout. The Settings → Remote access panel shows the exact URLs and a QR code to scan.

13 · Performance tools

System benchmark

One click measures your three ceilings: network throughput (a real 8-second multi-connection probe), CPU verification rate, and disk write speed. It leads with the answer: your expected maximum download speed and which ceiling is the limit. The shortest bar is your bottleneck; the others show their headroom. Schedule it (6-hourly → weekly) and every run is logged to a history table, so you can see when your provider, ISP or hardware changed behaviour. Scheduled runs only happen while the queue is idle.

Connection tuning

Measures one provider at rising connection counts and recommends the setting: more sockets help until the provider or your line saturates, and some providers punish over-asking. Test all compares every provider, then bursts them all together to check the pool saturates your line.

Server diversity

STAT-samples articles across ages on every server and clusters providers by shared gaps: providers with ~100% shared missing articles are the same backbone (redundant for recovery); independent ones genuinely extend your coverage. Ends with a plain-language recommendation.

Automatic queue intelligence

• Auto-defer: a download limping on a single slow server while other jobs wait is parked at the back (journal keeps its progress) and retried when the queue is clear.
• Idle-server prefetch: servers that can't help the active job (their copies are gone) start downloading the next queued job meanwhile. No other client does cross-job overlap.
• Cross-job soak: while a finished job's tail (verify/extract) completes on disk, the next job's download already owns the line.

The availability oracle

Takedowns are the main reason a Usenet download fails, and they are predictable: the same release goes missing on one backbone while another still has it. nzbfast keeps a small ledger of what your own providers actually answered for, and spends a tiny idle budget of STAT probes (a few hundred an hour per server, never during a download) to keep it current. It never downloads payload to find out.

What you get from it:

• An availability verdict on wall tiles and index rows (§6): amber "?" for uncertain on your providers, red for confidently gone. No mark means it looks fine.
• A reaped badge on groups where fresh posts are already being taken down, so you can tell a dying group from an unlucky release.
• Skip providers the oracle says are gone (Settings, off by default, experimental): when the check is confident one provider's backbone has lost a release, skip straight past it for that download instead of waiting for it to fail. It will never skip your last remaining provider.

The verdict is a prediction from evidence, not a guarantee. For a hard answer on one NZB, nzbfast check (§15) counts the actual articles.

Memory budget: what low memory costs

All engine caches share one budget (default ¼ of physical RAM, clamped to 256 MB–16 GB). Set it explicitly with Memory limit in Settings, or --mem-limit on the command line.

nzbfast is built to soak your network and your disk at the same time, and RAM is what lets it do both in one pass: articles are decoded, verified and written straight to their final offsets, so archive volumes need never touch the disk at all. Starve it of memory and nothing breaks: every cache has a spill path, and the engine degrades to more disk I/O rather than swapping or failing. But that spill is not free, and on big jobs you can measure it.

Measured on one machine and one line (M1 Ultra, 10 GbE), same files at each budget. Every run produced a correct, fully verified, extracted result:

Peak memory tracks the budget, not the job: that 190 GB download completes in about 1.1 GB of RAM. What you trade for it is time, and only on large jobs.

• Up to ~35 GB, low memory is free. The working set fits regardless, so a 4 GB machine finishes such a job as fast as a 64 GB one.
• Past ~87 GB you pay 20–40%, but only when your line outruns your disk. Verification blocks and archive volumes that would have stayed in RAM get written out and read back instead, and that only costs time if the network can deliver faster than the disk can absorb the extra traffic. The 20–40% above was measured on 10 GbE; the same 87 GB job at the same budgets on a ~2.4 Gbps line showed no penalty at all (−1 to +7%, within run-to-run noise). The penalty is a function of how far the line outruns the disk, not of the job size. On a typical home connection a small budget is close to free even on very large jobs.
• The penalty plateaus. Once a job is large enough to spill, every constrained budget spills about the same amount: the 2 GB, 1 GB and 256 MB runs read back essentially the same number of blocks from disk, and finish within noise of each other. So a little more RAM below the threshold that avoids spilling entirely doesn't buy back the cost: give it enough to keep the job in memory, or the exact figure barely matters.

On a small NAS, also drop Connections (2–4) along with the budget. At a 256 MB budget and 2 connections, peak memory stays near 190 MB, comfortably inside what a 2 GB NAS has spare. Be aware that at that point the connection count, not the memory, is what limits you: the same 35 GB job took 286 s instead of 65 s. That is the honest shape of the trade: it will always finish, and finish correctly; it just won't soak the line.

Benchmarks are re-run for each release; method and per-machine figures are published alongside the results.

14 · Updates

• Updates are notify-only: nzbfast never downloads or replaces its own binary, and there is no code in it that can. When a new release exists, the header shows ⬆ v X available - download; the chip links to the official download page (the link is fixed in the app, it never comes from the update manifest). Install the new version the same way you installed the current one.
• nzbfast checks for new releases twice a day. Turn Check for updates (Settings) off and it never contacts the update manifest at all; an empty update check URL does the same.

15 · Command line

Everything the daemon does is also scriptable. The everyday commands:

Also available: inspect, probe, bench, bench-cpu, soak, fetch, spots/spot-search/spot-get (Spotnet), make-release-nzb/make-test-nzb (test fixtures), and post (uploads files as yEnc articles and writes the matching NZB; an operations tool, it requires an explicit --post-server and never picks a server for you). Every command takes --config and --help.

16 · API overview

Base endpoint: http://host:6789/api?mode=…&apikey=…&output=json. It is SABnzbd-compatible, so existing SAB integrations work unchanged. Two keys: the API key (full control) and the NZB key (add-only: addfile/addurl).

17 · Files & locations

18 · Troubleshooting

This manual ships with every release. Settings, endpoints and defaults referenced here match the version it shipped with.