Skip to content

Latest commit

 

History

History
270 lines (215 loc) · 9.54 KB

README.md

File metadata and controls

270 lines (215 loc) · 9.54 KB

Huntarr - Find Missing & Upgrade Media Items

Huntarr Logo

Want to Help? Click the Star in the Upper-Right Corner! ⭐
Application Status
Sonarr ✅ Ready
Radarr ✅ Ready
Lidarr ✅ Ready
Readarr ✅ Ready
Whisparr ✅ Ready
Bazarr ❌ Not Ready

Keep in mind this is very early in program development. If you have a very special hand picked collection (because some users are extra special), test before you deploy.

Table of Contents

Overview

This application continually searches your media libraries for missing content and items that need quality upgrades. It automatically triggers searches for both missing items and those below your quality cutoff. It's designed to run continuously while being gentle on your indexers, helping you gradually complete your media collection with the best available quality.

For detailed documentation, please visit our Wiki.

Other Projects

Community

Join the community on Discord!
Discord

PayPal Donations – For My Daughter's College Fund

My 12-year-old daughter is passionate about singing, dancing, and exploring STEM. She consistently earns A-B honors! Every donation goes directly into her college fund!

Donate with PayPal button

Indexers Approving of Huntarr:

How It Works

🔄 Continuous Automation Cycle

1️⃣

Connect & Analyze

Huntarr connects to your Sonarr/Radarr/Lidarr/Readarr instance and analyzes your media library to identify both missing content and potential quality upgrades.

2️⃣

Hunt Missing Content

  • 📊 Smart Selection: Choose between random or sequential processing
  • 🔍 Efficient Refreshing: Optionally skip metadata refresh to reduce disk I/O
  • 🔮 Future-Aware: Automatically skip content with future release dates
  • 🎯 Precise Control: Set exactly how many items to process per cycle

3️⃣

Hunt Quality Upgrades

  • ⬆️ Quality Improvement: Find content below your quality cutoff settings
  • 📦 Batch Processing: Configure exactly how many upgrades to process at once
  • 📚 Large Library Support: Smart pagination handles even massive libraries
  • 🔀 Flexible Modes: Choose between random or sequential processing

4️⃣

State Management

  • 📝 History Tracking: Remembers which items have been processed
  • 💾 Persistent Storage: State data is saved in the /config directory
  • ⏱️ Automatic Reset: State is cleared after your configured time period (default: 7 days)

5️⃣

Repeat & Rest

Huntarr waits for your configured interval (adjustable in settings) before starting the next cycle. This ensures your indexers aren't overloaded while maintaining continuous improvement of your library.

Web Interface

Huntarr's live homepage will provide you statics about how many hunts have been pursed regarding missing media and upgrade searches! Note: Numbers reflected are but all required for testing... damn you Whisparr!

image

Homepage

Huntarr includes a real-time log viewer and settings management web interface that allows you to monitor and configure its operation directly from your browser.

image

Logger UI

How to Access

The web interface is available on port 9705. Simply navigate to:

http://YOUR_SERVER_IP:9705

The URL will be displayed in the logs when Huntarr starts, using the same hostname you configured for your API_URL.

Web UI Settings

The web interface allows you to configure all of Huntarr's settings:

image

Settings UI

Volume Mapping

To ensure data persistence, make sure you map the /config directory to a persistent volume on your host system:

-v /your-path/appdata/huntarr:/config

Installation Methods

Docker Run

The simplest way to run Huntarr is via Docker (all configuration is done via the web UI):

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

To check on the status of the program, you can use the web interface at http://YOUR_SERVER_IP:9705 or check the logs with:

docker logs huntarr

Docker Compose

For those who prefer Docker Compose, add this to your docker-compose.yml file:

services:
  huntarr:
    image: huntarr/huntarr:latest
    container_name: huntarr
    restart: always
    ports:
      - "9705:9705"
    volumes:
      - /your-path/huntarr:/config
    environment:
      - TZ=America/New_York

Then run:

docker-compose up -d huntarr

Unraid Users

Run this from Command Line in Unraid:

docker run -d --name huntarr \
  --restart always \
  -p 9705:9705 \
  -v /mnt/user/appdata/huntarr:/config \
  -e TZ=America/New_York \
  huntarr/huntarr:latest

Tips

  • First-Time Setup: Navigate to the web interface after installation to create your admin account with 2FA option
  • API Connections: Configure connections to your *Arr applications through the dedicated settings pages
  • Search Frequency: Adjust Sleep Duration (default: 900 seconds) based on your indexer's rate limits.
  • Batch Processing: Set Hunt Missing and Upgrade values to control how many items are processed per cycle
  • Queue Management: Use Minimum Download Queue Size to pause searching when downloads are backed up
  • Skip Processing: Enable Skip Series/Movie Refresh to significantly reduce disk I/O and database load
  • Future Content: Keep Skip Future Items enabled to avoid searching for unreleased content
  • Authentication: Enable two-factor authentication for additional security on your Huntarr instance

Troubleshooting

  • API Connection Issues: Verify your API key and URL in the Settings page (check for missing http:// or https://)
  • Authentication Problems: If you forget your password, delete /config/user/credentials.json and restart
  • Two-Factor Authentication: If locked out of 2FA, remove credentials file to reset your account
  • Web Interface Not Loading: Confirm port 9705 is correctly mapped and not blocked by firewalls
  • Logs Not Showing: Check permissions on the /config/logs/ directory inside your container
  • Missing State Data: State files in /config/stateful/ track processed items; verify permissions
  • Docker Volume Issues: Ensure your volume mount for /config has correct permissions and ownership
  • Command Timeouts: Adjust command_wait_attempts and command_wait_delay in advanced settings
  • Debug Information: Enable Debug Mode temporarily to see detailed API responses in the logs

Change Log

Visit: https://github.com/plexguide/Huntarr/releases/