Documentation

NZB Hunt

A complete Usenet download client built directly into Huntarr. No SABnzbd or NZBGet required.

What is NZB Hunt?

NZB Hunt is Huntarr's built-in Usenet download client. It handles the full download pipeline end-to-end: connecting to your NNTP servers, downloading articles in parallel, assembling files, verifying with PAR2, extracting RAR archives, and moving completed downloads to their final destination — all without any external download manager.

It is designed to work seamlessly with Movie Hunt and TV Hunt as their download backend, but it can also receive NZBs from Index Master or from external apps that have an NZBGet/SABnzbd-compatible API.

NZB Hunt is currently in Beta. Core downloading, extraction, and queue management work reliably. Some advanced features are still being refined. Join to report issues or suggest improvements.

Key Features

Multi-Server NNTP

Connect multiple Usenet servers simultaneously. Each server can have its own connection count (up to 120 total threads), SSL setting, priority, and enabled/disabled state.

Direct Unpack

Begins extracting RAR archives while downloading is still in progress — no waiting for the full download to finish before extraction starts. Enabled by default on new installs.

PAR2 Verification & Repair

Automatically verifies downloaded files using PAR2 data and repairs corruption when possible, before extraction begins.

Encrypted RAR Handling

Detects password-protected RAR archives automatically. Configurable action: abort the download (default on new installs) or pause and wait.

Speed Limiting

Set a global download speed cap in MB/s. Per-server bandwidth usage is tracked over 1 hour, 24 hours, 30 days, and all-time.

Full Queue Management

Pause, resume, reprioritize (Force / High / Normal / Low / Stop), and remove individual downloads. Bulk-remove completed or failed items from history.

Category Organization

Downloads are automatically sorted into category subfolders based on which Movie Hunt or TV Hunt instance requested them (e.g., complete/Movies-MyInstance/).

Duplicate Detection

Two modes: Identical (blocks exact same NZB content hash) and Smart (blocks same release name unless the new one is a PROPER/REPACK). Prevents wasted bandwidth on duplicate downloads.

Initial Setup

  1. Navigate to NZB Hunt in the sidebar.
  2. Go to Settings → Servers and click Add Server.
  3. Enter your NNTP server details:
    • Host: Your provider's server address (e.g., ssl-eu.astraweb.com)
    • Port: 563 for SSL (recommended), 119 for plain
    • SSL: Enabled (strongly recommended)
    • Username / Password: Your Usenet account credentials
    • Connections: Number of simultaneous connections (start with 8–20; your provider has a limit)
  4. Click Test to verify the connection, then Save.
  5. Go to Settings → Folders and set your incomplete download path (e.g., /downloads/incomplete).
  6. Completed downloads land in /downloads/complete/ with category subdirectories automatically created.
Docker volume required. Map /downloads in your Docker container to a host path with enough storage. NZB Hunt stores incomplete downloads in /downloads/incomplete and moves them to /downloads/complete when done. See the Installation page for volume mapping details.

Connecting NZB Hunt to Movie Hunt / TV Hunt

To use NZB Hunt as the download backend for Movie Hunt or TV Hunt:

  1. In Movie Hunt or TV Hunt, go to Indexers & Clients → Download Clients.
  2. Click Add Client and select NZB Hunt from the list.
  3. NZB Hunt connects internally — no URL or API key needed when running inside the same Huntarr instance.
  4. Save. Huntarr will now route NZBs from Movie Hunt / TV Hunt directly to NZB Hunt's queue.

Processing Settings

Setting Default (New Install) Description
Direct Unpack On Extract RARs while still downloading. Faster completion but requires more disk I/O.
Encrypted RAR Action Abort What to do when a password-protected RAR is detected. Abort removes it from the queue; Pause waits for intervention.
Abort Hopeless On Automatically fail downloads that cannot complete due to too many missing articles.
Abort Threshold 5% Failure percentage above which a download is considered hopeless and aborted.
Max Retries 3 How many times to retry a failed article segment before marking it as missing.
Propagation Delay 0 min Minutes to wait after a download completes before post-processing begins (for incomplete propagation on very new posts).
Disconnect on Empty On Drop NNTP connections when the queue is empty to reduce server load.
Identical Detection On Block downloads where the NZB content hash exactly matches something already in the queue.
Smart Detection On Block downloads with the same release name (unless it's a PROPER, REAL, or REPACK).

Advanced Settings

Setting Default Description
Receive Threads 2 Number of worker threads for processing downloaded article data. Increase if CPU is not a bottleneck.
Direct Unpack Threads 3 Simultaneous extraction threads when Direct Unpack is active.
Size Limit Unlimited Optional maximum NZB size in GB. NZBs larger than this are rejected.
Required Completion Rate 100.2% Minimum article completion percentage required to attempt extraction. Values slightly above 100% are fine due to PAR2 repair capacity.

Understanding the Queue

  • Queued — waiting to start downloading
  • Downloading — actively fetching articles from NNTP servers
  • Assembling — combining articles into full files
  • Extracting — unpacking RAR archives (or running PAR2 verification/repair)
  • Completed — moved to the complete folder and ready for import
  • Failed — download aborted (too many missing articles, encrypted RAR, or other error)
  • Paused — manually paused or paused by the encrypted RAR handler

Bandwidth Tracking

NZB Hunt tracks bandwidth usage per server over four windows:

  • Last 1 hour
  • Last 24 hours
  • Last 30 days
  • All-time total

This is useful for monitoring your Usenet provider's monthly data allowance. Bandwidth stats are visible in NZB Hunt → Settings → Servers and can be reset per-server at any time.

Tips & Best Practices

  • Start with fewer connections — most providers allow 20–50. Start lower and increase if speeds are below your internet capacity.
  • Use SSL on port 563 — encrypts your article traffic and improves compatibility with most modern providers.
  • Add a backup server — add a second lower-priority server (e.g., a block account with long retention) to fill in gaps from your primary.
  • Keep Direct Unpack enabled — it significantly reduces end-to-end time from download to imported file.
  • Monitor failed downloads — if a lot of downloads fail with "missing articles," your indexer's NZB files may be pointing to posts that have expired on your provider's retention.
  • Ensure /downloads is on fast local storage — NME direct unpack is I/O intensive. Avoid network shares for the downloads path if possible.