Readarr Documentation
Readarr automates the process of monitoring and downloading books and audiobooks. It integrates with popular download clients and uses indexers to search for and download content automatically, making it easy to build and maintain an organized digital library.
Overview
What Readarr Does
Readarr provides automated content management for books and audiobooks by:
- Automatic Searching: Monitors for new books and searches configured indexers
- Quality Management: Downloads content based on your quality preferences (EPUB, PDF, MP3, etc.)
- Library Organization: Automatically organizes downloaded books in your media library
- Upgrade Management: Can upgrade existing books to better quality when available
- Download Client Integration: Works with popular download clients like qBittorrent, Deluge, etc.
How Huntarr Enhances Readarr
Huntarr adds intelligent automation on top of Readarr:
- Smart Search Timing: Prevents overwhelming indexers with too many requests
- Missing Book Detection: Identifies and prioritizes missing books and audiobooks
- Upgrade Intelligence: Finds better quality versions of existing books
- Rate Limiting: Respects API limits to prevent bans or throttling
- Multi-Instance Support: Manage multiple Readarr instances from one interface
Instance Configuration
Configure your Readarr instances to connect Huntarr with your Readarr installation(s).
Adding Your Readarr Instance
To connect your existing Readarr instance to Huntarr:
- Navigate to the Readarr section in Huntarr
- Click "Add Readarr Instance" if you don't have one configured
- Fill in your Readarr connection details
- Test the connection to ensure Huntarr can communicate with Readarr
Connection Settings
Configure these settings to connect Huntarr to your Readarr instance:
| Setting | Description | Example | Notes |
|---|---|---|---|
| Name | Friendly name for this Readarr instance | Default, Audiobooks, Comics | Useful when running multiple Readarr instances |
| URL | Base URL for your Readarr instance | http://10.0.0.10:8787 | Include protocol (http/https) and port |
| API Key | Readarr API key for authentication | d26g09e9514f7hf6c8d0b97f5e3c691 | Found in Readarr Settings > General > Security |
| Enabled | Whether Huntarr should process this instance | On/Off toggle | Disable to temporarily stop processing |
Search Settings
Configure how Huntarr searches for missing books and upgrades in your Readarr instance. These settings control Huntarr's behavior when processing your book library.
Missing Search Mode
Determines how Huntarr searches for missing books:
- Books: Searches for individual books. Standard mode for most libraries
- Authors: Searches at the author level for complete works
- Series: Searches for book series when available
Upgrade Mode
Controls how Huntarr handles quality upgrades:
- Books: Upgrades individual books when better quality becomes available
- Authors: Upgrades at the author level for consistent quality
- Series: Upgrades entire book series at once when better quality is found
Search Limits
Control how many items Huntarr processes per cycle to avoid overwhelming your indexers:
| Setting | Description | Recommended | Notes |
|---|---|---|---|
| Missing Search | Number of missing books to search per cycle | 2-3 | Set to 0 to disable missing searches |
| Upgrade Search | Number of books to upgrade per cycle | 1-2 | Set to 0 to disable upgrade searches |
| Sleep Duration | Time in seconds between processing cycles | 2400 (40 min) | Book indexers often have limited content |
| API Cap - Hourly | Maximum API requests per hour | 150 or less | Book indexers typically have lower limits |
Additional Options
Fine-tune Huntarr's behavior with these additional settings:
Monitored Only
When enabled, Huntarr will only search for books that are marked as "Monitored" in Readarr. This prevents searches for authors or books you've intentionally unmonitored.
Skip Future Releases
When enabled, Huntarr will skip books with future release dates. This prevents unnecessary searches for content that hasn't been published yet.
Book Types
Configure which types of books Huntarr should search for:
- Ebooks: Digital book formats (EPUB, PDF, MOBI, etc.)
- Audiobooks: Audio versions of books (MP3, M4A, etc.)
- Both: Search for both ebooks and audiobooks
Author Monitoring
When enabled, Huntarr will respect your author monitoring settings in Readarr, only searching for books from authors you're actively monitoring.
Swaparr Integration
Enable Swaparr monitoring for this Readarr instance to automatically clean up stalled downloads.
When to Enable Swaparr
- You frequently have stalled book or audiobook downloads
- Your download queue gets clogged with failed downloads
- You want hands-off automation for your digital library
- You use public trackers where availability varies
- You download large audiobook collections that sometimes fail
When to Be Cautious
- You use private book trackers with strict ratio requirements
- You prefer manual control over your book downloads
- You have very slow internet where downloads take a long time
- You're building ratio on specific book torrents
- You collect rare or out-of-print books that shouldn't be removed
Troubleshooting
Common Issues
Connection Failed
If Huntarr can't connect to your Readarr instance:
- Verify the URL is correct and includes the protocol (http/https)
- Check that the port number is correct (default: 8787)
- Ensure the API key is copied correctly from Readarr Settings > General > Security
- Confirm Readarr is running and accessible from Huntarr's network
- Check firewall settings if Huntarr and Readarr are on different machines
No Missing Books Found
If Huntarr reports no missing books but you know there are gaps:
- Ensure "Monitored Only" is configured correctly for your needs
- Check that authors and books are marked as "Monitored" in Readarr
- Verify "Skip Future Releases" isn't preventing searches for available content
- Review your book type settings (ebooks vs audiobooks)
Limited Book Availability
If Huntarr isn't finding books that should be available:
- Book indexers have much more limited content than movie/TV indexers
- Consider adding more book-specific indexers to Readarr
- Check if your indexers support the book formats you're seeking
- Verify your quality profiles match available content
Metadata and Search Issues
If Huntarr isn't finding the right books:
- Verify your metadata provider settings in Readarr (Goodreads, etc.)
- Check that book titles and author names are correctly matched
- Review ISBN settings for proper book identification
- Consider adjusting search criteria for international editions
Format and Quality Issues
If Huntarr isn't finding the right book formats:
- Verify your quality profiles support the formats you want (EPUB, PDF, MP3, etc.)
- Check that your indexers have the formats you're seeking
- Review cutoff settings to ensure upgrades are allowed
- Consider separate instances for ebooks vs audiobooks
Audiobook Specific Issues
If you're having trouble with audiobook searches:
- Ensure your indexers support audiobook formats
- Check that audiobook quality profiles are properly configured
- Verify narrator information is correctly matched
- Consider longer search intervals due to limited audiobook availability