How to Self-Host Podgrab with Docker Compose

What Is Podgrab?

Podgrab is a self-hosted podcast manager that automatically downloads new episodes from your subscriptions. It runs as a lightweight Go binary with a built-in web player, podcast discovery via the iTunes API, and OPML import/export. Point it at your podcast feeds, and it handles the rest — checking for new episodes on a configurable schedule and downloading them to local storage.

Quick Verdict

For podcast archiving and local playback, Podgrab is the simplest self-hosted option. It’s a single container with no database dependencies, uses ~30 MB of RAM, and does exactly one thing well. If you need podcast support alongside audiobooks, Audiobookshelf is the more capable choice — but Podgrab’s simplicity is hard to beat for a dedicated podcast downloader.

Use Cases

• Offline listening. Download episodes to your server and play from any device on your network — no streaming data used.
• Podcast archiving. Keep permanent copies of episodes before they disappear from feeds (many podcasts remove old episodes).
• Feed consolidation. OPML import lets you migrate from any podcast app and manage all subscriptions in one place.
• Background downloading. Set it and forget it — Podgrab checks feeds every N minutes and stores new episodes automatically.

Prerequisites

• A Linux server (Ubuntu 22.04+ recommended)
• Docker and Docker Compose installed (guide)
• 1 GB of free disk space for the application (episodes will need more)
• 512 MB of RAM (minimum)

Docker Compose Configuration

Create a docker-compose.yml file:

services:
  podgrab:
    image: akhilrex/podgrab:1.0.0
    container_name: podgrab
    environment:
      - CHECK_FREQUENCY=240   # Check for new episodes every 4 hours (in minutes)
    volumes:
      - podgrab-config:/config    # SQLite database and settings
      - podgrab-assets:/assets    # Downloaded podcast episodes
    ports:
      - "8080:8080"               # Web UI and player
    restart: unless-stopped

volumes:
  podgrab-config:     # Application data (~10 MB)
  podgrab-assets:     # Podcast episodes (scales with subscriptions)

If you want episodes stored at a specific path on the host (recommended for large libraries):

    volumes:
      - podgrab-config:/config
      - /srv/podcasts:/assets     # Store episodes on a specific disk/mount

Start the stack:

docker compose up -d

Initial Setup

1. Open http://your-server:8080 in a browser.
2. The web UI loads immediately — no account creation or setup wizard required.
3. Add your first podcast by searching (iTunes API) or pasting a feed URL.
4. Podgrab begins downloading available episodes immediately.

Configuration

Check Frequency

The CHECK_FREQUENCY environment variable controls how often Podgrab polls feeds for new episodes (in minutes):

Value	Behavior
30	Every 30 minutes (aggressive, default)
120	Every 2 hours
240	Every 4 hours (recommended for most users)
1440	Once per day

Lower values catch new episodes faster but generate more network traffic. For most listeners, checking every 4 hours is sufficient — podcast feeds rarely update more frequently.

OPML Import

To migrate from another podcast app:

1. Export your subscriptions as OPML from your current app (Apple Podcasts, Pocket Casts, Overcast, etc.).
2. In Podgrab’s web UI, click the import button and upload the .opml file.
3. Podgrab subscribes to all feeds and begins downloading episodes.

Tags and Organization

Podgrab supports tagging podcasts into groups. Use tags to organize by topic (tech, news, comedy) or priority (must-listen, background). Tags appear as filterable categories in the web UI.

Reverse Proxy

If placing Podgrab behind a reverse proxy, enable WebSocket support — it’s required for the “Add to playlist” feature.

Nginx Proxy Manager or Caddy configuration:

# Caddy
podgrab.example.com {
    reverse_proxy localhost:8080
}

For Nginx, add WebSocket headers:

location / {
    proxy_pass http://localhost:8080;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
}

[Full reverse proxy guide: Reverse Proxy Setup]

Backup

Back up these volumes:

Volume	Contents	Priority
/config	SQLite database, subscriptions, settings	Critical (small, ~10 MB)
/assets	Downloaded episodes	Optional (can re-download)

The /config volume contains your subscription list and download history. Back this up. The /assets volume contains the actual audio files — re-downloadable from feeds, but backing up preserves episodes that may be removed from their original feeds.

[Backup Strategy guide: Backup Strategy]

Troubleshooting

Episodes Not Downloading

Symptom: Podgrab shows new episodes in the feed but doesn’t download them. Fix: Check the CHECK_FREQUENCY value — if set too high, episodes wait until the next check cycle. Also verify disk space on the assets volume. Podgrab fails silently when storage is full.

Web UI Not Loading Behind Reverse Proxy

Symptom: The main page loads but podcasts won’t play, or the “Add” button doesn’t work. Fix: Enable WebSocket support in your reverse proxy configuration. Podgrab uses WebSockets for real-time UI updates and playlist management.

OPML Import Fails

Symptom: Import completes but no podcasts appear. Fix: Verify the OPML file is valid XML. Some podcast apps export broken OPML with unclosed tags or invalid characters. Open the file in a text editor and check for XML errors before importing.

High Disk Usage

Symptom: The /assets volume grows faster than expected. Fix: Podgrab downloads all available episodes when you subscribe to a feed — not just new ones. For podcasts with years of back catalog, this adds up quickly. Delete old episodes through the web UI or set up a cron job to remove files older than N days from the assets directory.

Resource Requirements

Resource	Value
RAM (idle)	~20–30 MB
RAM (active download)	~50–80 MB
CPU	Very low
Disk (application)	~30 MB
Disk (data)	~50–150 MB per hour of audio (bitrate-dependent)

Podgrab is one of the lightest self-hosted applications available. It runs comfortably on a Raspberry Pi or as a side container on any existing Docker host.

Verdict

For podcast downloading and local playback, Podgrab is the leanest option available. It uses 30 MB of RAM, requires zero configuration beyond a single environment variable, and handles the core workflow — subscribe, auto-download, play — without complexity.

If you also manage audiobooks or want a more polished player with chapter support and progress tracking, Audiobookshelf handles both audiobooks and podcasts in one application. For podcast-only use with minimal resource overhead, Podgrab does exactly what you need.

Note that Podgrab’s last code update was September 2022. The project is stable and functional, but don’t expect new features. If that’s a concern, Audiobookshelf receives regular updates and has a larger community.

Frequently Asked Questions

Does Podgrab support streaming without downloading?

Yes — the built-in web player can stream episodes directly from their original source URL. But Podgrab’s primary purpose is downloading for local/offline access.

Can multiple users share a Podgrab instance?

Podgrab is a single-user application. There are no user accounts or per-user subscriptions. Everyone shares the same podcast library.

Does Podgrab support video podcasts?

No. Podgrab downloads and plays audio files only. For video podcast management, look at media server solutions like Jellyfin.

Related

• How to Self-Host Audiobookshelf
• Self-Hosted Alternatives to Audible
• Audiobookshelf vs Booksonic
• Best Self-Hosted Music Streaming
• Self-Hosted Alternatives to Spotify
• Self-Hosted Podcast Apps
• Docker Compose Basics
• Reverse Proxy Setup
• Backup Strategy