Frequently Asked Questions

This comprehensive FAQ covers common questions and issues that users encounter when setting up and using Huntarr. Use the table of contents below to quickly find answers to your questions.

Table of Contents

Installation & Setup

What are the different ways to install Huntarr?

Huntarr can be installed using several methods:

  • Docker (Recommended): Most reliable and consistent across platforms
  • Windows Installer: Native .exe installer for Windows users
  • macOS Installer: Native .pkg installer for Intel and Apple Silicon Macs
  • Unraid: Available through Community Applications
  • From Source: For advanced users and development
Recommendation: Docker is the primary supported method and ensures the most consistent experience across all platforms.

How do I install Huntarr using Docker?

The simplest Docker installation command is:

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

For Docker Compose, add this to your docker-compose.yml:

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

Why does Windows Defender block the installer?

Windows Defender SmartScreen may show a warning because the installer isn't signed by Microsoft. This is normal for many open-source applications.

To proceed: Click "More info" in the upper left corner of the SmartScreen dialog, then click "Run anyway" to continue with installation.

The Docker version doesn't have this issue and is the recommended installation method.

How do I handle macOS security warnings?
macOS may show a security warning because the app isn't signed by Apple. To install:
  1. Download the appropriate installer (.pkg) for your Mac (Intel or Apple Silicon)
  2. When you see the security warning, go to System Settings → Privacy & Security
  3. Scroll down to the security section and click "Open Anyway"
The installer will create configuration directories at: ~/Library/Application Support/Huntarr/config/
What port does Huntarr use and can I change it?
Huntarr uses port 9705 by default. You can access the web interface at http://YOUR_SERVER_IP:9705
Changing the port: If port 9705 is already in use, you can change it in your Docker run command or docker-compose.yml file by modifying the port mapping (e.g., -p 8080:9705).

Configuration & API Connections

How do I connect Huntarr to my *arr applications?
After installation, access the web interface and navigate to Settings:
  1. Go to the specific app settings (Sonarr, Radarr, etc.)
  2. Enter your app's URL (e.g., http://10.10.10.1:8989)
  3. Enter your API key (found in your app's Settings → General)
  4. Test the connection
Important: Omit the trailing slash (/) at the end of URLs. Use http://10.10.10.1:8989 instead of http://10.10.10.1:8989/
What applications does Huntarr support?
Currently supported applications:
  • ✅ Sonarr - TV Shows
  • ✅ Radarr - Movies
  • ✅ Lidarr - Music
  • ✅ Readarr - Books
  • ✅ Whisparr v2 & v3 - Adult content
  • ❌ Bazarr - Not yet supported
Huntarr is actively developed, and support for additional applications may be added in future releases.
How do I configure search intervals and batch sizes?
In the web interface settings, you can configure:
  • Sleep Duration: Time between search cycles (default: 900 seconds)
  • Hunt Missing: Number of missing items to search per cycle
  • Hunt Upgrades: Number of upgrade searches per cycle
  • Minimum Download Queue Size: Pause searching when queue exceeds this number
Tip: Start with conservative values and adjust based on your indexer's rate limits and system performance.
What are the recommended settings for indexer protection?
To protect your indexers from rate limiting:
  • Set reasonable hourly API caps in settings
  • Use longer sleep durations (15+ minutes) between cycles
  • Limit batch sizes for missing items and upgrades
  • Enable "Skip Future Items" to avoid searching unreleased content
  • Enable "Skip Series/Movie/Artist Refresh" to reduce API calls
Remember: Huntarr uses consistent 120-second timeouts and identifies itself to all *arr applications to ensure reliable operation.

Troubleshooting

Huntarr won't start or the web interface isn't loading
Common solutions:
  1. Check if the container is running: docker ps | grep huntarr
  2. Check the logs: docker logs huntarr
  3. Verify port mapping: Ensure port 9705 isn't blocked by firewall
  4. Check volume permissions: Ensure the /config volume has correct permissions
If using Docker, try rebuilding the container: docker-compose down && docker-compose up -d --build
API connection errors or timeouts
If you're experiencing API connection issues:
  • Verify your API key is correct (copy from your *arr app settings)
  • Check the URL format (include http:// or https://)
  • Remove trailing slashes from URLs
  • Ensure your *arr applications are accessible from Huntarr's network
  • Check if your *arr apps are running and responsive
Network Issues: If running in Docker, ensure Huntarr can reach your *arr applications. Consider using Docker networking or host networking if needed.
Authentication problems or forgot password
If you're locked out of Huntarr:
  1. Stop the Huntarr container: docker stop huntarr
  2. Delete the credentials file: rm /your-path/huntarr/user/credentials.json
  3. Restart Huntarr: docker start huntarr
  4. Access the web interface to create a new admin account
Two-Factor Authentication: If locked out of 2FA, removing the credentials file will also reset your 2FA settings.
Logs not showing or missing state data
If logs aren't displaying or state data is missing:
  • Check permissions on /config/logs/ directory
  • Verify state files exist in /config/stateful/
  • Ensure the Docker volume mount has correct ownership
  • Check available disk space on the host system
Permission Fix: You may need to adjust ownership: sudo chown -R 1000:1000 /your-path/huntarr
Huntarr is not finding missing items
If Huntarr isn't finding missing content:
  • Ensure items are marked as "Monitored" in your *arr applications
  • Check that "Skip Future Items" is enabled to avoid unreleased content
  • Verify your quality profiles and cutoff settings
  • Check the download queue isn't exceeding your minimum threshold
  • Review the logs for any API errors or rate limiting
Debug Mode: Enable debug mode temporarily to see detailed API responses and understand what Huntarr is processing.
Pop-up windows are obscured or cut off
Some users experience issues where pop-up windows or dialogs appear behind other elements or are cut off at the bottom of the screen:
  • Try refreshing the page (F5 or Ctrl+R)
  • Clear your browser cache and cookies for the Huntarr site
  • Try using a different browser (Chrome, Firefox, Safari, Edge)
  • Check your browser zoom level - try resetting to 100%
  • Disable browser extensions temporarily to see if they're interfering
This is often a browser-specific rendering issue that can be resolved by clearing cache or trying a different browser.
Statistics showing negative numbers after update
If you see negative numbers in your statistics after updating Huntarr:
  • This is usually a temporary display issue that resolves itself
  • Wait for the next processing cycle to complete
  • Try refreshing the web interface
  • Check if the issue persists after a few hours of operation
  • If the problem continues, consider using the Emergency Reset in settings
Note: Statistics are recalculated during each cycle, so temporary negative values may appear during processing.
API limits are being ignored
If Huntarr seems to be ignoring your configured API limits:
  • Verify your hourly API caps are set correctly in settings
  • Check that you're not running multiple instances of Huntarr
  • Ensure your *arr applications aren't performing their own searches
  • Review the logs to see actual API call counts
  • Consider reducing batch sizes for missing items and upgrades
Remember: API limits are per hour, and the counter resets at the beginning of each hour.
Timers showing errors or not displaying
If countdown timers show "Error Loading" or don't display properly:
  • Check that Huntarr has proper permissions to write to the config directory
  • Verify the timer files exist in the stateful directory
  • Restart the Huntarr container: docker restart huntarr
  • Check the logs for any file permission errors
  • Ensure sufficient disk space is available
Common Cause: This often occurs when running on bare metal installations where Docker paths don't exist.
History shows the same movie/show multiple times
If you see duplicate entries in your history:
  • This can happen when Huntarr processes the same item multiple times
  • Check if you have multiple quality profiles that might trigger re-processing
  • Verify your cutoff settings aren't causing repeated upgrade attempts
  • Consider adjusting your state reset interval in settings
  • Review your indexer settings to avoid duplicate releases
Normal Behavior: Some duplication is normal when Huntarr finds better quality versions or when items are re-monitored.
Huntarr downloads unknown quality ignoring profiles
If Huntarr seems to ignore your quality profiles:
  • Verify your quality profiles are correctly configured in your *arr apps
  • Check that the cutoff quality is set appropriately
  • Ensure your indexers are providing accurate quality information
  • Review the logs to see what quality Huntarr thinks it's requesting
  • Consider updating your *arr applications to the latest versions
Important: Huntarr relies on your *arr applications' quality profiles - it doesn't override them.
Cannot save Apprise URL for notifications
If you're having trouble saving Apprise notification URLs:
  • Verify the Apprise URL format is correct for your service
  • Check that there are no special characters causing parsing issues
  • Try saving one URL at a time instead of multiple URLs
  • Ensure the notification service is accessible from your network
  • Test the URL manually using the Apprise documentation
Tip: Use the Apprise documentation to verify your URL format: Apprise Supported Services
Weird or excessive Docker logs
If you notice unusual or excessive logging in your Docker logs:
  • Check if debug mode is enabled and disable it if not needed
  • Review your log refresh interval settings
  • Ensure your *arr applications are responding properly
  • Check for network connectivity issues
  • Consider adjusting your sleep duration to reduce API calls
Performance Impact: Excessive logging can impact performance and fill up disk space quickly.
Low FPS or lag in the web interface
If the Huntarr web interface feels slow or laggy:
  • Try using a different browser or clearing browser cache
  • Check if your system is under heavy load
  • Reduce the log refresh interval in settings
  • Close other browser tabs or applications
  • Ensure your network connection is stable
  • Try accessing from a different device to isolate the issue
Optimization: Increasing the log refresh interval from 30 to 60 seconds can improve performance.
Critical security vulnerabilities in dependencies
If you receive notifications about security vulnerabilities:
  • Update to the latest version of Huntarr immediately
  • Check the GitHub releases page for security updates
  • Enable automatic updates if available in your environment
  • Monitor the project's security advisories
  • Consider using Watchtower for automatic Docker image updates
Security: Always keep Huntarr updated to the latest version to ensure you have the latest security patches.
Timezone mismatch in stateful management
If you notice timing issues or incorrect timestamps:
  • Verify your timezone is correctly set in the Docker environment
  • Check the TZ environment variable in your docker-compose.yml
  • Ensure your host system timezone is correct
  • Restart the container after timezone changes
  • Check if your *arr applications have matching timezones
Example: Set TZ=America/New_York in your Docker environment variables to match your local timezone.
State reset not happening automatically
If the automatic state reset isn't working as expected:
  • Check your state reset interval setting in the web interface
  • Verify the state files exist in /config/stateful/
  • Ensure Huntarr has write permissions to the config directory
  • Check the logs for any errors related to state management
  • Consider manually triggering an emergency reset if needed
Manual Reset: Use the Emergency Reset button in settings if automatic resets aren't working properly.

Features & Functionality

What does Huntarr actually do?
Huntarr is a specialized utility that:
  • Finds Missing Content: Identifies missing episodes, movies, albums, or books in your library
  • Quality Upgrades: Searches for better quality versions of existing content below your cutoff
  • Automated Searching: Continuously runs searches in manageable batches
  • Indexer Protection: Respects rate limits and prevents overloading your indexers
  • Queue Management: Pauses searching when download queues are full
Example: If you have 5,000 shows in Sonarr and 1,700 are missing episodes, Huntarr will systematically work through them over time to complete your collection.
How does Huntarr protect my indexers?
Huntarr includes several indexer protection features:
  • Hourly API Caps: Configurable limits prevent excessive API calls
  • Batch Processing: Searches limited numbers of items per cycle
  • Sleep Intervals: Configurable delays between search cycles
  • Universal Timeouts: Consistent 120-second timeouts prevent hanging requests
  • Queue Monitoring: Automatically pauses when download queues are full
Smart Design: Huntarr identifies itself to all *arr applications and uses consistent headers for reliable operation.
Can I run Huntarr alongside other automation tools?
Yes! Huntarr is designed to complement your existing media stack:
  • Works with *arr apps: Integrates seamlessly with Sonarr, Radarr, etc.
  • Pairs with Cleanuperr: Huntarr finds content, Cleanuperr keeps downloads clean
  • Respects existing settings: Uses your quality profiles and preferences
  • Non-intrusive: Doesn't modify your existing configurations
Perfect Pair: Huntarr + Cleanuperr creates a powerful, self-sufficient media automation stack.
What notifications does Huntarr support?
Huntarr supports notifications through Apprise, which includes:
  • Discord webhooks
  • Slack notifications
  • Email alerts
  • Telegram messages
  • Pushover notifications
  • And many more services supported by Apprise
Configure Apprise URLs in the settings to receive alerts when media is processed or when issues occur.

Performance & Optimization

How can I optimize Huntarr's performance?
To optimize Huntarr's performance:
  • Enable Skip Refresh: Reduces disk I/O and database load significantly
  • Adjust Batch Sizes: Start small and increase based on system capacity
  • Monitor Resource Usage: Check CPU and memory usage during operation
  • Optimize Sleep Duration: Balance between responsiveness and system load
  • Use SSD Storage: Faster storage improves database operations
Resource Impact: Larger batch sizes and shorter sleep intervals will increase system load and API usage.
What system resources does Huntarr require?
Huntarr has modest system requirements:
  • CPU: Low usage, occasional spikes during processing
  • Memory: Typically 100-500MB depending on library size
  • Storage: Minimal for application, logs, and state files
  • Network: API calls to *arr applications and indexers
Scaling: Resource usage scales with library size and configured batch sizes. Larger libraries may require more memory and processing time.
How do I monitor Huntarr's activity?
Monitor Huntarr through several methods:
  • Web Interface: Real-time dashboard with statistics and progress
  • Live Logs: Built-in log viewer shows current activity
  • Docker Logs: docker logs huntarr for container output
  • State Files: Track processed items in /config/stateful/
  • Notifications: Configure Apprise for activity alerts
Real-time Monitoring: The web interface provides live updates on hunt progress and API usage.

Security & Authentication

How do I secure my Huntarr installation?
Security best practices for Huntarr:
  • Enable Authentication: Create an admin account on first setup
  • Use 2FA: Enable two-factor authentication for additional security
  • Secure API Keys: Keep your *arr application API keys private
  • Network Security: Use firewalls and VPNs as appropriate
  • Regular Updates: Keep Huntarr updated to the latest version
Important: Never expose Huntarr directly to the internet without proper authentication and security measures.
How does two-factor authentication work?
Huntarr supports 2FA for enhanced security:
  1. Enable 2FA during initial account setup or in settings
  2. Scan the QR code with your authenticator app (Google Authenticator, Authy, etc.)
  3. Enter the verification code to complete setup
  4. Future logins will require your password + authenticator code
Recovery: If locked out of 2FA, delete the credentials file and restart Huntarr to reset authentication.
Where are credentials and sensitive data stored?
Huntarr stores sensitive data securely:
  • Credentials: /config/user/credentials.json
  • API Keys: Encrypted in configuration files
  • Settings: /config/settings/ directory
  • Logs: /config/logs/ (may contain API responses)
Backup Security: Ensure your config directory backups are stored securely as they contain API keys and authentication data.

Compatibility & Requirements

What platforms does Huntarr support?
Huntarr supports multiple platforms:
  • Docker: Linux, Windows, macOS (recommended)
  • Windows: Native installer for Windows 10/11
  • macOS: Native installer for Intel and Apple Silicon
  • Unraid: Available through Community Applications
  • Linux: Docker or from source
Cross-Platform: Docker ensures consistent behavior across all platforms and is the recommended deployment method.
What are the minimum system requirements?
Minimum requirements for Huntarr:
  • Docker: Docker 1.27 or newer
  • Python: 3.9+ (for source installation)
  • Memory: 512MB RAM minimum, 1GB+ recommended
  • Storage: 100MB for application, additional for logs/state
  • Network: Internet access for API calls to *arr apps and indexers
Scaling: Requirements increase with library size and number of configured applications.
Can I run Huntarr on a NAS or low-power device?
Yes! Huntarr works well on low-power devices:
  • Synology/QNAP NAS: Use Docker or Container Station
  • Raspberry Pi: ARM Docker images available
  • Unraid: Dedicated template in Community Applications
  • TrueNAS: Use Docker or jail deployment
Efficiency: Huntarr is designed to be lightweight and efficient, making it perfect for NAS and low-power deployments.
Does Huntarr work with reverse proxies?
Yes, Huntarr supports reverse proxy deployments:
  • Subpath Support: Works with paths like /huntarr/
  • Popular Proxies: Nginx, Apache, Traefik, Caddy
  • SSL/TLS: HTTPS termination at proxy level
  • Authentication: Can work with proxy-level auth
Configuration: Ensure your reverse proxy passes the correct headers and handles WebSocket connections for real-time features.