Podcasts in Audiobookshelf: add a show, auto-download episodes and keep only the latest

Audiobookshelf downloads each podcast episode to your server, and your apps play it from there. Only an admin can add a show, and auto-download and “how many episodes to keep” are set on each show separately.

Nothing plays straight from the podcast’s own website. If an episode isn’t on your server yet, it isn’t in your library.

How do I add a podcast to Audiobookshelf?

You need a library with the Podcasts media type first. In the web app, open Settings > Libraries, add a library, choose Podcasts as the media type and pick its folder (in Docker, usually /podcasts).

Then, signed in as an admin:

1. Open the podcast library and click Add in the left sidebar.
2. Type the show’s name, or paste its RSS feed URL (the link that lists its episodes), and click Submit.
3. Pick the show. Check the Folder it will be saved in. Audiobookshelf makes a folder for the show inside the library folder.
4. Tick Auto Download Episodes if the server should fetch new episodes on its own.
5. Click Submit.

The Add button and the Queue page only show up for admins. A regular user can listen to the shows but can’t add new ones, in the web app or in any other app.

Adding a show doesn’t download its old episodes. To get some of the back catalogue, open the show and click the search icon (Find Episodes). That reads the feed and lets you tick the episodes to download.

If you’re an admin and use SoundLeaf, you can also add shows from your iPhone. Podcasts in SoundLeaf has the steps.

How do I set up auto-download for a podcast?

There’s no global setting for all podcasts. You set auto-download, episodes per check and episodes to keep separately for each show.

1. Open the show and click the pencil icon to edit it.
2. Open the Schedule tab (admins only).
3. Tick Enable under Schedule Automatic Episode Downloads.
4. Set how often to check. New shows check every hour unless you change it.
5. Click Save.

Two numbers sit on the same tab:

Setting	What it does
Max # of new episodes to download per check	How many new episodes one check can download. New shows start at 3. 0 means no limit.
Max # of episodes to keep	After an auto-download, deletes the oldest episode once the show has more than this. 0 means keep everything.

How do I keep only the latest episodes?

Set Max # of episodes to keep on the show’s Schedule tab. Say you set it to 10. Each time a new episode is auto-downloaded and the show now has more than 10, Audiobookshelf deletes the oldest one, by publish date.

A few things people don’t expect:

• It removes one episode per new download. If a show already has 200 episodes and you set it to 10, each new episode adds one and removes one, so the show stays at 200. Delete the extra old episodes yourself once, and the limit holds from then on.
• It only runs after an auto-download. Episodes you download by hand don’t trigger it.
• The audio file is deleted along with the episode. Listening progress on that episode is removed, and it’s taken out of playlists.
• Episodes without a publish date aren’t counted and are never removed by this setting.

Why can’t Apple Podcasts or Overcast see my Audiobookshelf podcasts?

Your podcast library isn’t a feed that other podcast apps can subscribe to. It’s a set of files on your server that Audiobookshelf apps read through your account.

Audiobookshelf can publish a feed for a show if you want one. On the show’s page, an admin opens the menu and picks Open RSS Feed, chooses a feed name and clicks Open Feed. You get a feed URL like https://your-server/feed/<name> to copy.

Before you rely on it, know two things.

• Anyone with the link can listen. The feed doesn’t ask for a username or password.
• The link uses the address you opened the web app with. If you were on http://192.168.1.50:13378, the feed only works on your home network.

Some podcast apps don’t refresh feeds from your phone. They refresh them from their own servers on the internet. Overcast says on its information page for podcasters that it fetches feeds centrally. A server on the internet can’t reach an address that only works in your house or over Tailscale, so the show never loads. Audiobookshelf also warns that most podcast apps need the feed on HTTPS.

If you want the feed in another app, open the web app through your public HTTPS address first (see listening away from home), then open the RSS feed. The simpler route is an app that talks to Audiobookshelf directly, which plays the episodes the server already downloaded.

Podcast episodes not downloading in Audiobookshelf

Look at the server log first: Settings > Logs in the web app. Most of the problems below leave a clear line there.

The download queue is stuck on one episode

The symptom: a spinner says it’s downloading an episode, it never finishes, and new episodes pile up behind it. This is #4116, still open. A contributor says a fix in v2.25.1 worked for several people, but reports continue on newer versions, such as 2.32.1.

1. Restart Audiobookshelf to clear the stuck download.
2. The queue only lives in memory, so the episodes waiting in it are gone after the restart. Open the show, click Find Episodes and download the missing ones again.

The cross on the queued-episodes banner on a show’s page clears the waiting episodes, but not the one that’s stuck.

A separate bug made the scheduled episode check hang for good (#4098). The v2.25.1 release included a fix for it, and the issue was closed as fixed in June 2025.

”Failed to get podcast feed”

The server couldn’t load the show’s feed. Open the feed URL in a browser on the same network. If it loads there, check the server log for the error on Audiobookshelf’s own request. Your browser and the server can get different answers from the same address.

In Docker, one cause is DNS (how the server looks up a website’s address). One person in #3967 fixed it by setting DNS servers in the compose file, even though curl inside the container worked. It didn’t help everyone in that thread, but it’s quick to try:

services:
  audiobookshelf:
    # ... the rest of your settings
    dns:
      - 1.1.1.1
      - 9.9.9.9

Then run docker compose up -d. If you use your own DNS server at home, put its address first.

Episodes fail because of a redirect

Many podcasts don’t link to the audio file directly. The link goes through a tracking service first, which then redirects to the real file. Audiobookshelf checks every outside request with a filter that stops it from being tricked into calling devices on your own network. The filter is called the SSRF filter (SSRF is short for server-side request forgery).

That filter trips on some of these redirects, for example when a tracker sends an https:// link on to an http:// one. The episode is found but never downloads. This is #5230, open as of October 2026.

There are two settings for it. Both are environment variables (settings you add to the container’s environment: section).

• SSRF_REQUEST_FILTER_WHITELIST turns the filter off for the domains you list, separated by commas. Use the exact host name at the start of the feed or episode link, for example pdcn.co. A subdomain like www.pdcn.co needs its own entry. This is the safer choice.
• DISABLE_SSRF_REQUEST_FILTER=1 turns the filter off completely.

environment:
  - SSRF_REQUEST_FILTER_WHITELIST=pdcn.co,feeds.example.com

After adding either one, run docker compose up -d. A plain restart doesn’t pick up new environment variables. up -d recreates the container with them.

The trade-off: with the filter off, a feed or episode link can make your server send requests to addresses inside your home network. A feed you trust is unlikely to do that. Still, turning it off for a few domains is better than turning it off everywhere. You also need one of these if you host a podcast yourself on the same network, because the filter blocks local addresses.

Downloads time out on slow podcast hosts

Audiobookshelf waits up to 30 seconds for a feed or an episode download to answer before it gives up. PODCAST_DOWNLOAD_TIMEOUT (added in v2.18.0) raises that for feed checks and the main episode download, in milliseconds. One retry path still uses 30 seconds:

environment:
  - PODCAST_DOWNLOAD_TIMEOUT=120000   # two minutes

Then run docker compose up -d.

Auto-download turned itself off

When a show’s feed fails 24 checks in a row, Audiobookshelf turns off auto-download for that show. Fix the feed, then tick Enable on its Schedule tab again.

MAX_FAILED_EPISODE_CHECKS (added in v2.25.1) changes the number, and 0 means never turn it off. Add it under environment: and run docker compose up -d.

To hear about it when it happens, the server can send a notification when a feed check fails and when auto-download is turned off. Set that up under Settings > Notifications.

A DNS ad blocker blocks the episodes

Pi-hole, AdGuard Home and similar blockers often block podcast tracking domains. When the episode link goes through a blocked tracker, the download fails, even though the feed itself loads.

Check your blocker’s log for blocked lookups from the server’s address while a download runs. Allow that domain, or let the server skip the blocker.

EACCES: permission denied

EACCES means permission denied. If the log shows it with your podcast folder’s path, Audiobookshelf isn’t allowed to write there. When adding a show fails this way, the web app says “Invalid podcast path”.

The user Audiobookshelf runs as needs write access to the podcast library folder on the host. With Docker running as a non-root user, see running Audiobookshelf as a non-root user. If you can’t see the folder at all, see Audiobookshelf can’t see my audiobook folder.