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).
Huntarr supports multiple Readarr instances. Each instance has its own connection (URL, API key), and its own per-instance settings: missing/upgrade mode, upgrade selection method, tags, search limits, and Swaparr. You can enable or disable each instance independently.
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 Details
These settings match the Connection Details section in the instance editor:
| Setting | Description |
|---|---|
| Status | Shows connection status and Readarr version. Displayed at the top of the section. |
| Enable Status | Enable or disable this instance. When disabled, Huntarr will not process this instance. |
| Name | A friendly name to identify this instance (e.g. Main Readarr, Audiobooks). Useful when running multiple Readarr instances. |
| URL | The full URL including port (e.g. http://localhost:8787). Include protocol (http/https) and port. |
| API Key | Found in Settings > General in your *arr application (Readarr: Settings > General > Security). |
| Instance Identifier | Stable identifier for this instance (assigned automatically; cannot be changed). Used internally so Huntarr can track state per instance. |
Search Settings (Per Instance)
These settings match the Search Settings section in the instance editor. Each Readarr instance has its own values.
Search counts
- Missing Search Count — Number of missing items to search for in each cycle. Set to 0 to disable missing searches.
- Upgrade Search Count — Number of items to upgrade in each cycle. Set to 0 to disable upgrade searches.
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
Upgrade Selection Method
You can choose how Huntarr selects which authors to consider for upgrades:
- Cutoff unmet (default): Uses Readarr's Wanted → Cutoff Unmet list. Only books that don't meet your quality/custom-format cutoff are eligible. Same behavior as before.
- Tags (Upgradinatorr-style): Huntarr finds authors that DON'T have your specified tag (e.g.
upgradinatorr), searches their books for upgrades, then ADDS the tag to the author after processing to mark them as complete. This matches Upgradinatorr's behavior: the tag tracks which authors have already been processed, not which ones to search. The tag is automatically created in Readarr if it doesn't exist.
In both cases, Huntarr triggers BookSearch for the selected books; Readarr still decides what to grab based on your quality profile and custom format scores. When using Tags, the Upgrade Tag field sets the tag name on authors in Readarr (e.g. upgradinatorr); Huntarr finds authors without this tag, runs upgrade searches on their books, then adds the tag when done.
Cutoff unmet mode uses Readarr's Wanted → Cutoff Unmet list every cycle; Tags (Upgradinatorr) mode finds authors without your chosen tag, runs upgrade searches on their books, then adds that tag to the author so they are not searched again. Configure your quality profile and Upgrade Until Custom Format Score in Readarr so it knows what counts as an upgrade when Huntarr triggers the search.
Cutoff Unmet vs Tags: Which Should I Use?
Understanding the difference between these two modes will help you choose the right approach for your library:
| Feature | Cutoff Unmet (Huntarr Standard) | Tags (Upgradinatorr-style) |
|---|---|---|
| How It Works | Queries Readarr's Wanted → Cutoff Unmet list every cycle |
Searches books by authors WITHOUT the tag, then ADDS tag to author after processing |
| Re-processing | Same books appear in every cycle until they meet cutoff | Once tagged, author's books are NEVER searched again (unless you manually remove tag) |
| Best For | Dynamic quality targets - continuously searching until perfect quality is found | One-time library upgrade - systematically process entire library once |
| Indexer Impact | Higher - searches same books repeatedly if upgrades not found | Lower - each author's books searched once, then marked complete |
| Progress Tracking | Based on cutoff status - books drop off list when upgraded | Visual tags in Readarr UI - see which authors have been processed |
| Use Case Example | "Keep searching until every book reaches my quality target" | "I just set up TRaSH guides - process my entire 500 author library once" |
| Stops When | Books meet quality cutoff or custom format score threshold | Tag is applied to author (regardless of whether upgrades were found) |
Cutoff Unmet: You have 300 books below cutoff from 100 authors. Huntarr searches 5 books per cycle, finds upgrades for 3. Next cycle, those 3 are gone (met cutoff), but the other 2 appear again along with 3 new ones from the remaining 295. This continues until all 300 meet cutoff or no more upgrades exist.
Tags: You have 500 authors with no
upgradinatorr tag. Huntarr searches 5 books per cycle (from different authors), tags those authors after processing (whether upgrades found or not). Next cycle searches books from 5 different authors. Eventually all 500 authors have been processed once and tagged - done forever.
Custom Format Scores & Quality Upgrades
- Readarr → Settings → Profiles → Quality Profile → Upgrade Until Custom Format Score
- Set Upgrade Until Custom Format Score to at least
10000
Why Custom Format Scores Matter
Huntarr does not decide what to upgrade—Readarr does. When Huntarr triggers a search for upgrades, Readarr evaluates the search results using your configured quality profile and custom format scores to determine whether a release is an upgrade worth grabbing.
Key Points:
- Quality Cutoff: The minimum quality level you're willing to accept (e.g., EPUB, AZW3, PDF)
- Custom Formats: Additional scoring criteria beyond basic quality (e.g., preferred release groups, edition preferences, retail vs. scan)
- Upgrade Until Custom Format Score: The score threshold at which Readarr stops considering upgrades. Setting this to 10000 (or higher) ensures Readarr will continue upgrading as long as better-scoring releases are found
How It Works:
- Huntarr identifies books eligible for upgrade (based on your chosen upgrade selection method)
- Huntarr triggers a BookSearch command in Readarr
- Readarr searches indexers and scores each result using your quality profile + custom formats
- Readarr automatically grabs releases that score higher than your current file (up to your "Upgrade Until" threshold)
- Without proper custom format scoring configured, Readarr may not grab upgrades even when better releases are available
Stateful Management
These settings match the Stateful Management section in the instance editor. Huntarr can track which items it has already processed so it doesn’t re-search them every cycle.
| Setting | Description |
|---|---|
| State Management | Enabled: track processed items to avoid redundant searches. Disabled: do not track; every cycle may consider the same items again. |
| Reset Interval (Hours) | How long to wait before re-searching a previously processed item (default: 72 hours / 3 days). After this time, items become eligible again. |
| Reset Processed State Now | Button that clears the history of processed items for this instance. Use if you want Huntarr to re-consider everything from scratch. |
When state management is enabled, the UI shows Active - Tracked Items: N and Next Reset (when the next reset cycle runs).
Additional Settings
These match the Additional Settings section. Book indexers often have limited content and stricter rate limits; do not overwhelm them.
| Setting | Description | Recommended |
|---|---|---|
| Sleep Duration (Minutes) | Time in minutes between processing cycles for this instance. | 40 or more; longer intervals reduce indexer load. |
| API Cap - Hourly | Maximum API requests per hour for this instance. | 10–20 recommended, max 400. 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.
Advanced Settings
These match the Advanced Settings section: API Timeout (seconds), Command Wait Delay (seconds), Command Wait Attempts, Max Download Queue Size, and Swaparr Monitoring (when Swaparr is enabled in Huntarr Settings).
Custom Tags
These match the Custom Tags section. Huntarr can add tags in Readarr to mark processed items.
- Tag missing items / Missing Items Tag — Tag (e.g.
huntarr-missing) added when items are found by a missing search. Max 25 characters. - Tag upgrade items / Upgrade Items Tag — Used only in cutoff unmet mode. In Tags (Upgradinatorr) mode this option is hidden; Huntarr uses the Upgrade Tag (e.g.
upgradinatorr) on authors to mark processed content instead.
Readarr does not have "Tag shows missing" (Sonarr-only).
Exempt Tags
Items with any of these tags are skipped for missing and upgrade searches. If you remove the tag in Readarr, Huntarr will process the item again. The tag upgradinatorr cannot be added as an exempt tag. See #676.
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