Installation

Get Huntarr running on Docker, Unraid, Windows, macOS, or Linux in minutes.

Requirements

• Docker and Docker Compose — recommended for all platforms; works on Linux, macOS, Windows, and Unraid
• OR Python 3.10+ for running from source (advanced users)
• 512 MB RAM minimum (1 GB+ recommended if using NZB Hunt with many simultaneous threads)
• Network access to your *arr instances (Sonarr, Radarr, etc.) — same Docker network or routable IP
• A modern web browser for the Huntarr UI

Docker Installation (Recommended)

Docker is the recommended and most-supported way to run Huntarr. It provides consistent behavior across every platform and makes updates a single command.

Docker Compose

Create a docker-compose.yml file. Only /config is required; add /media and /downloads only if you use Movie Hunt / TV Hunt or NZB Hunt:

services:
  huntarr:
    image: huntarr/huntarr:latest
    container_name: huntarr
    ports:
      - "9705:9705"
    volumes:
      - /path/to/huntarr/config:/config          # Required: settings, database, logs
      - /path/to/media:/media                    # Optional: Movie Hunt / TV Hunt library
      - /path/to/downloads:/downloads            # Optional: NZB Hunt download output
    environment:
      - TZ=America/New_York                      # Set your timezone
      - PUID=1000                                # Optional: run as specific user
      - PGID=1000                                # Optional: run as specific group
    restart: unless-stopped

Start or update the container:

docker-compose up -d

Docker Run

Single-command option without Compose:

docker run -d \
  --name huntarr \
  -p 9705:9705 \
  -v /path/to/huntarr/config:/config \
  -v /path/to/media:/media \
  -v /path/to/downloads:/downloads \
  -e TZ=America/New_York \
  -e PUID=1000 \
  -e PGID=1000 \
  --restart unless-stopped \
  huntarr/huntarr:latest

Minimal install (third-party *arr only, no Media Hunt or NZB Hunt):

docker run -d \
  --name huntarr \
  -p 9705:9705 \
  -v /path/to/huntarr/config:/config \
  -e TZ=America/New_York \
  --restart unless-stopped \
  huntarr/huntarr:latest

Volume Mappings

Container Path	Purpose	Required
/config	All Huntarr data — settings, SQLite database, logs, NZB queue state, and backups	Yes
/media	Your media library root. Movie Hunt and TV Hunt use this for root folder configuration and disk scanning	Only if using Movie Hunt / TV Hunt
/downloads	NZB Hunt download location. Incomplete files land in /downloads/incomplete, completed in /downloads/complete	Only if using NZB Hunt

Unraid Installation

Huntarr is available through Unraid Community Applications — just search and click Install.

Steps

1. Open the Unraid web UI and go to the Apps tab (Community Applications).
2. Search for "Huntarr".
3. Click Install on the Huntarr template.
4. Review and configure the template settings:
   • Port: 9705 (change if already in use)
   • Config path: /mnt/user/appdata/huntarr
   • Media path (optional): Map to your media share (e.g., /mnt/user/media) — only needed for Movie Hunt / TV Hunt
   • Downloads path (optional): Map to your download directory — only needed for NZB Hunt
   • PUID: 99 (Unraid's nobody user)
   • PGID: 100 (Unraid's users group)
   • Timezone: Set to your local timezone (e.g., America/New_York)
5. Click Apply to pull the image and start the container.
6. Access Huntarr at http://your-unraid-ip:9705.

Windows Installation

Option 1: Docker Desktop (Recommended)

1. Install Docker Desktop for Windows.
2. Enable WSL 2 backend during installation (recommended by Docker for best performance).
3. Open PowerShell or Command Prompt and run:

docker run -d ^
  --name huntarr ^
  -p 9705:9705 ^
  -v huntarr-config:/config ^
  -e TZ=America/New_York ^
  --restart unless-stopped ^
  huntarr/huntarr:latest

Access Huntarr at http://localhost:9705.

To add media or download paths on Windows, use Windows-style paths with Docker Desktop:

-v C:\Users\YourName\Media:/media -v C:\Users\YourName\Downloads:/downloads

Option 2: Run from Source

1. Install Python 3.10+ (check "Add to PATH" during install).
2. Install Git for Windows.
3. Open PowerShell and run:

git clone https://github.com/emiliomm/huntarr-custom.git
cd Huntarr.io
pip install -r requirements.txt
python main.py

Access Huntarr at http://localhost:9705.

macOS Installation

Option 1: Docker Desktop (Recommended)

1. Install Docker Desktop for Mac (supports both Intel and Apple Silicon).
2. Open Terminal and run:

docker run -d \
  --name huntarr \
  -p 9705:9705 \
  -v huntarr-config:/config \
  -e TZ=America/New_York \
  --restart unless-stopped \
  huntarr/huntarr:latest

Access Huntarr at http://localhost:9705.

Option 2: Run from Source

brew install python@3.12 git
git clone https://github.com/emiliomm/huntarr-custom.git
cd Huntarr.io
pip3 install -r requirements.txt
python3 main.py

Access Huntarr at http://localhost:9705.

Linux Installation

Option 1: Docker (Recommended)

Install Docker if you haven't already:

curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER
# Log out and back in for group changes to take effect

Then run Huntarr:

docker run -d \
  --name huntarr \
  -p 9705:9705 \
  -v /opt/huntarr/config:/config \
  -v /path/to/media:/media \
  -v /path/to/downloads:/downloads \
  -e TZ=America/New_York \
  -e PUID=1000 \
  -e PGID=1000 \
  --restart unless-stopped \
  huntarr/huntarr:latest

Option 2: Run from Source with systemd

sudo apt update && sudo apt install -y python3 python3-pip git
git clone https://github.com/emiliomm/huntarr-custom.git /opt/huntarr
cd /opt/huntarr
pip3 install -r requirements.txt

Create a systemd service file at /etc/systemd/system/huntarr.service:

[Unit]
Description=Huntarr Media Hunter
After=network.target

[Service]
Type=simple
User=huntarr
WorkingDirectory=/opt/huntarr
ExecStart=/usr/bin/python3 /opt/huntarr/main.py
Restart=on-failure
RestartSec=10

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable --now huntarr
sudo systemctl status huntarr

Alternative Methods

LXC Containers (Proxmox)

Run Huntarr inside an LXC container by either installing Docker within the container or running from source. Use the Linux instructions above inside your LXC. For Docker-in-LXC, ensure the container is not unprivileged and has nesting enabled in the Proxmox container options.

Kubernetes / Helm

The Docker image huntarr/huntarr:latest works with any Kubernetes deployment. Key configuration:

• Container port: 9705
• Persistent volume claim for /config (ReadWriteOnce)
• Optional PVCs for /media (ReadWriteMany) and /downloads
• Environment variable TZ for timezone

Environment Variables

Variable	Default	Description
TZ	UTC	Timezone for scheduling and log timestamps (e.g., America/New_York). See TZ database names.
PUID	0 (root)	User ID to run the Huntarr process as. Unraid: 99, Linux: 1000.
PGID	0 (root)	Group ID to run as. Unraid: 100, Linux: 1000.
HUNTARR_PORT	9705	Internal web UI port. Change this (and the host port mapping) if 9705 conflicts with another service.
HUNTARR_LOG_LEVEL	INFO	Log verbosity. Options: DEBUG, INFO, WARNING, ERROR.

Updating Huntarr

Docker Compose (Recommended)

docker-compose pull
docker-compose up -d

Docker Run

docker pull huntarr/huntarr:latest
docker stop huntarr && docker rm huntarr
# Re-run your original docker run command

Unraid

Unraid notifies you of available updates. Click Update on the Huntarr container in the Docker tab. Your config data in /mnt/user/appdata/huntarr is preserved.

From Source

cd /opt/huntarr
git pull
pip3 install -r requirements.txt
sudo systemctl restart huntarr

Post-Installation

After installation, open http://your-server:9705 in your browser. On your first visit you'll be greeted by the Setup Wizard, which guides you through creating your admin account, connecting your first *arr app, and configuring basic hunt settings.

Troubleshooting