System Settings

System Settings

These settings control basic functionality and appearance of your Huntarr.io instance.

Timezone

Set your timezone for accurate time display in logs, scheduling, and all time-related features throughout Huntarr.

This setting controls how timestamps are displayed in the following areas:

• Log timestamps: All log entries will show the correct local time
• Scheduling displays: Schedule times will be shown in your local timezone
• Stateful management: Reset times and state information will use your timezone
• Cycle tracking: Cycle start/end times will be in your local time

When running in Docker, Huntarr will automatically detect your timezone from the TZ environment variable if set. You can override this setting through the web interface at any time.

Supported timezones include:

• UTC (Coordinated Universal Time)
• North American timezones (Eastern, Central, Mountain, Pacific, Hawaii)
• Canadian timezones (Eastern and Pacific Canada)
• European timezones (UK, Central Europe, Germany, Netherlands, Italy, Spain)
• Asian timezones (Japan, China, India)
• Australian and Pacific timezones (Sydney, Perth, Auckland)

Docker Example: Set TZ=Pacific/Honolulu in your docker-compose.yml environment variables for Hawaii time.

Changes to this setting take effect immediately and will update all logging and display times throughout the application.

Check for Updates

When enabled, Huntarr will automatically check for new versions and notify you when updates are available.

We recommend keeping this enabled to ensure you're running the latest version with bug fixes and new features. Updates are not installed automatically; you'll just be notified when they're available.

Disabling this option means you'll need to manually check for updates, which could lead to missing important security fixes or helpful new features. Most users should leave this enabled unless running Huntarr in an air-gapped environment.

Debug Mode

Enables verbose logging for troubleshooting issues. This setting applies to all apps connected to Huntarr.

Only enable this when you're experiencing issues and need to troubleshoot or when requested by support. Debug mode generates more detailed logs that can help identify problems, but it can also increase disk usage and slightly reduce performance.

When troubleshooting, enable this setting, reproduce the issue you're experiencing, then check the logs for detailed information. After resolving the issue, remember to disable debug mode to restore optimal performance.

Display Resources

Controls whether the Resources section is shown on the home page.

The Resources section displays helpful links like documentation, GitHub repository, and community forums. You may want to hide this once you're familiar with Huntarr to optimize screen space.

New users should keep this enabled as it provides quick access to documentation and support resources. More experienced users might prefer to hide this section to focus on the core functionality of Huntarr.

Low Usage Mode

Reduces CPU and GPU usage by disabling animations and visual effects, making Huntarr more suitable for older devices or systems with limited resources.

When enabled, this setting will:

• Disable animations: Removes smooth transitions and loading animations
• Reduce visual effects: Simplifies the user interface to use fewer system resources
• Optimize rendering: Uses more efficient rendering techniques for slower devices
• Lower CPU usage: Reduces background processing for UI elements

This mode is particularly useful for:

• Older computers or single-board computers like Raspberry Pi
• Systems with limited RAM or processing power
• Remote access scenarios where bandwidth is limited
• Users who prefer a more responsive, simplified interface

The setting takes effect immediately and doesn't require a restart. You can toggle it on and off as needed depending on your current usage requirements.

Notifications

Configure how Huntarr sends notifications about media processing events. Huntarr uses the powerful Apprise library to support notifications to virtually any service including Discord, Telegram, Slack, email, webhooks, and dozens more.

Enable Notifications

Master toggle to enable or disable all notifications from Huntarr.

When enabled, Huntarr will send notifications based on your configured settings and Apprise URLs. When disabled, no notifications will be sent regardless of other settings.

This is useful for temporarily silencing notifications during maintenance or testing without having to remove your Apprise URL configurations.

Notification Level

Sets the minimum severity level for events that will trigger notifications.

• Info: All events including successful downloads, upgrades, and general status updates
• Success: Only successful operations like completed downloads and upgrades
• Warning: Warning-level events and above (includes errors)
• Error: Only critical errors and failures

Most users should use "Info" to get comprehensive notifications about Huntarr's activities. Use "Error" if you only want to be notified about problems.

Apprise URLs

Configure one or more notification destinations using Apprise URL format. Enter one URL per line.

Apprise supports an extensive list of notification services. Here are some popular examples:

• Discord: discord://webhook_id/webhook_token
• Telegram: tgram://bottoken/ChatID
• Slack: slack://TokenA/TokenB/TokenC/Channel
• Email (SMTP): mailto://user:pass@host:port/recipient
• Pushover: pover://user@token
• Webhooks: json://hostname/path

For complete documentation of supported services and their URL formats, visit the official Apprise documentation.

You can configure multiple notification destinations by adding multiple URLs, one per line. Huntarr will send notifications to all configured services.

Notify on Missing

Send notifications when Huntarr processes missing media and requests downloads from your *arr apps.

When enabled, you'll receive notifications like:

• "Found 5 missing episodes for Breaking Bad Season 2"
• "Requested download for The Dark Knight (2008) from Radarr"

This helps you stay informed about what content Huntarr is actively working to acquire for your media library.

Notify on Upgrade

Send notifications when Huntarr processes media upgrades and requests better quality versions from your *arr apps.

When enabled, you'll receive notifications like:

• "Found upgrade opportunity for The Matrix (1999) - 1080p → 4K UHD"
• "Requested quality upgrade for Game of Thrones S01E01 from Sonarr"

This keeps you informed when Huntarr finds opportunities to improve the quality of your existing media collection.

Include Instance

Include the configured instance name in notification messages when you have multiple instances of the same app type.

When enabled, notifications will include the instance name you configured, such as:

• "[Movies-4K] Found missing media..." (instead of just "[Radarr] Found missing media...")
• "[TV-Anime] Requested upgrade..." (instead of just "[Sonarr] Requested upgrade...")

This is especially useful when running multiple Sonarr or Radarr instances (e.g., separate instances for 4K content, anime, or different quality profiles).

Include App Name

Include the application name (Sonarr, Radarr, etc.) in notification messages.

When enabled, notifications will include the source app name, such as:

• "[Sonarr] Found 3 missing episodes..."
• "[Radarr] Requested download for..."

When disabled, notifications will be more generic:

• "Found 3 missing episodes..."
• "Requested download for..."

Most users should keep this enabled for clarity about which app triggered each notification.

Stateful Management

These settings control how Huntarr manages the state of processed media. Understanding these settings is crucial for proper operation of Huntarr's media processing capabilities.

🔥 EMERGENCY RESET 🔥

This button immediately resets all processed media state information.

Use this only in emergency situations where you need to force Huntarr to reprocess all media. This will clear all records of what media has been processed, allowing Huntarr to start fresh. This does not delete your media files or configuration settings.

Warning: After reset, Huntarr may reprocess media that was already processed before, potentially causing duplicate downloads.

Situations where an emergency reset might be necessary include:

• After changing your media organization strategy and wanting Huntarr to reevaluate all content
• When you suspect that Huntarr's processing data has become corrupted
• After a significant configuration change when you want Huntarr to start fresh

Initial State Created: Sun, May 18, 2025, 02:45 PM (today)
State Reset Date: Sun, May 25, 2025, 02:45 PM (in 7 days)

State Reset (Hours)

Determines how many hours before automatically resetting processed media state information (default: 168 hours, or 7 days).

This setting controls how long Huntarr remembers which media files it has already processed. After this time, Huntarr will "forget" what it has processed, allowing reprocessing of media.

Increasing this value means Huntarr will remember processed media for longer, reducing the chance of duplicate processing. Decreasing it allows more frequent reprocessing of media, which might be useful if you often make changes to your media library or configuration.

Common settings values and their effects:

• 168 hours (7 days): Default setting, suitable for most users
• 720 hours (30 days): Good for stable setups where you rarely add new content
• 72 hours (3 days): For more active libraries with frequent changes
• 24 hours (1 day): For very dynamic environments or testing setups

Reset clears all processed media IDs to allow reprocessing. This is especially useful when you've made changes to your naming conventions or organization structure and want Huntarr to reprocess content according to the new rules.

Security

These settings control access security and encryption options to protect your Huntarr installation.

Authentication Mode

Controls how users authenticate with Huntarr. There are three options available:

Login Mode

Standard login required for all connections. This is the most secure option and is recommended if your Huntarr instance is accessible from the internet. With this mode, anyone accessing Huntarr will need to provide valid credentials.

Local Bypass Mode

Only local network connections (192.168.x.x, 10.x.x.x) bypass login. This is convenient for home networks as it doesn't require login when accessing from your local network, but still requires login when accessing remotely.

This mode offers a good balance between security and convenience for typical home setups. You won't need to log in when accessing Huntarr from devices on your home network, but external access will still require authentication.

No Login Mode

Completely disable authentication when running behind your own reverse proxy. Only use this if your instance is behind a secure reverse proxy (like Nginx or Cloudflare) that handles authentication for you.

Warning: Using "No Login Mode" without proper security could allow unauthorized access to your media and system! Only use this mode if you have implemented alternative security measures.

Enable SSL Verify

Controls whether Huntarr verifies SSL certificates when connecting to other services.

Normally, this should be enabled for security. It ensures Huntarr only connects to services with valid SSL certificates, protecting against man-in-the-middle attacks and unauthorized access.

You might need to disable this if you're using self-signed certificates on your private network. For example, if you have self-signed certificates for Sonarr, Radarr, or other services, Huntarr might not be able to connect to them unless this is disabled.

Note: Only disable this on private, trusted networks. Disabling SSL verification on public networks or internet-facing installations could expose your system to security risks.

If you're experiencing connection issues with other services that use SSL, and you're using self-signed certificates or a private certificate authority, you may need to disable this option. However, a better approach would be to properly configure your certificates to be trusted by your system.

Advanced Settings

These settings are for advanced users who need to fine-tune Huntarr's performance and behavior. Adjust these settings only if you understand their impact on the system.

API Timeout

The number of seconds Huntarr will wait for API responses before timing out (default: 120 seconds).

If you notice Huntarr frequently reporting timeouts when connecting to Sonarr, Radarr, or other services, you might need to increase this value. This is especially useful on slower networks or when services are under heavy load.

However, setting this too high could cause Huntarr to appear unresponsive if a service is down, as it will wait longer before giving up on connections.

This setting is particularly important if:

• You have services running on slower hardware like a Raspberry Pi
• Your services are handling large libraries or running intensive tasks
• Your network has higher latency or occasional connectivity issues

Command Wait Delay

The delay in seconds between command status checks (default: 1 second).

This setting controls how frequently Huntarr checks if a command sent to another service (like Sonarr or Radarr) has completed. Lower values make Huntarr more responsive but might increase network traffic. Higher values reduce network traffic but might make Huntarr seem less responsive.

The default of 1 second works well for most users and shouldn't need changing. In high-performance environments with many services, increasing this value slightly (to 2-3 seconds) might reduce unnecessary network traffic without significantly impacting responsiveness.

CMD Wait Attempts

The maximum number of attempts to check command status (default: 600).

This setting, combined with Command Wait Delay, determines how long Huntarr will wait for a command to complete before giving up. With default settings (600 attempts × 1 second delay), Huntarr will wait up to 10 minutes.

If you're processing very large libraries or have slower systems, you might need to increase this value. If commands are typically quick on your system, you could decrease it to detect failed commands more quickly.

Calculation: Total wait time = Command Wait Delay × CMD Wait Attempts

• Default: 1 second × 600 attempts = 600 seconds (10 minutes)
• For slower systems: 1 second × 1200 attempts = 1200 seconds (20 minutes)
• For faster systems: 1 second × 300 attempts = 300 seconds (5 minutes)

Max DL Queue Size

If the current download queue for an app instance exceeds this value, downloads will be skipped until the queue reduces (default: -1, which means no limit).

This setting helps prevent overwhelming your download client with too many simultaneous downloads. If you notice performance issues when Huntarr triggers many downloads at once, you might want to set this to a reasonable value (like 5 or 10).

Setting this to -1 means there's no limit on how many downloads Huntarr will queue, which can be useful if you have a very powerful system and fast internet.

Consider your bandwidth and system resources when setting this value:

• -1 (No limit): For high-bandwidth connections and powerful systems
• 10-15: For good broadband connections and moderately powerful systems
• 5-10: For typical home broadband connections
• 1-5: For slower connections or systems with limited resources

Log Refresh Interval

How often Huntarr refreshes logs from apps, in seconds (default: 30 seconds).

This setting controls how frequently Huntarr updates the logs you see in the UI. Lower values (like 10-15 seconds) make logs update more frequently but might increase system load. Higher values (like 60 seconds) reduce system load but make logs less current.

The default of 30 seconds provides a good balance between timely updates and system efficiency. If you're actively troubleshooting an issue and need to see log updates more quickly, you might temporarily reduce this value. For regular operation, especially on less powerful hardware, keeping it at 30 seconds or higher is recommended.

When adjusting this setting, consider:

• 10-15 seconds: For active troubleshooting when you need near real-time log updates
• 30 seconds: Default, good balance for most users
• 60 seconds: For systems with limited resources or when logs aren't frequently needed

Base URL

Base URL path for reverse proxy configurations (e.g., '/huntarr'). Leave empty for root path deployment.

This setting is essential when running Huntarr behind a reverse proxy server like Nginx, Apache, or Cloudflare Tunnel where you want to host Huntarr at a subpath rather than the root domain.

Example configurations:

• Root path: Leave empty to access Huntarr at https://yourdomain.com/
• Subpath: Set to /huntarr to access at https://yourdomain.com/huntarr/
• Multiple services: Set to /media/huntarr for https://yourdomain.com/media/huntarr/

Reverse proxy configuration examples:

Nginx:

location /huntarr {
    proxy_pass http://huntarr:9705;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
}

Cloudflare Tunnel:

ingress:
  - hostname: yourdomain.com
    path: /huntarr
    service: http://huntarr:9705

Important notes:

• Always include the leading slash (e.g., /huntarr not huntarr)
• Do not include trailing slashes
• Requires container restart to take effect
• Ensure your reverse proxy is configured to forward requests to this path

Credit to scr4tchy for implementing this feature.