PinePods 🌲

A forest of podcasts, rooted in the spirit of self-hosting.

---

What is PinePods?

PinePods is a complete, self-hosted podcast management system written in Rust.

You run one server, your whole household connects to it, and your subscriptions, history, queue, downloads, and settings follow you from device to device — because everything lives in your own database. Listen in the browser, on the desktop, on your phone, in the car, or even from the terminal.

• 🏠 Self-hosted & open source — your podcasts and listening data stay on your hardware (Postgres or MySQL/MariaDB).
• 👥 Multi-user — one instance serves your whole family, each with their own library, stats, and settings.
• 📱 Native apps everywhere — web, Linux, Windows, macOS, Android, and iOS, plus a CLI client.
• 🔀 Bring your own apps — a built-in gpodder-compatible sync server lets you keep using AntennaPod and friends alongside PinePods.
• 🌐 Speaks your language — translated into 36 languages by the community.

👉 Want the full story, deep configuration, and tutorials? Head to the documentation site.

Highlights

See the full feature catalog in the docs.

Screenshots 📷

A home dashboard that picks up where you left off — with dozens of built-in themes plus a custom theme creator

Browse your whole library and dig into any show

One unified feed of every new episode across your subscriptions

Rich episode pages with show notes, chapters, and transcripts

Listen your way — full-screen audio and native video playback

A persistent queue, smart playlists, library search, and detailed stats

Mobile apps for iOS & Android, with CarPlay and Android Auto

Try it out! ⚡

A public demo instance lives at try.pinepods.online — make an account and take a look before you self-host. It's for evaluation only; accounts there are wiped periodically, so run your own server for real use.

Quick Start 🚀

PinePods requires a database (PostgreSQL or MySQL/MariaDB) and a reachable Valkey or Redis server. The API connects to Valkey/Redis before it starts listening. Keep the valkey service below unless you configure an external server.

The fastest way to run PinePods is Docker Compose with PostgreSQL. Create a docker-compose.yml:

services:
  db:
    container_name: db
    image: postgres:18
    environment:
      POSTGRES_DB: pinepods_database
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: myS3curepass
      PGDATA: /var/lib/pgdata/pgdata
    volumes:
      - /home/user/pinepods/pgdata:/var/lib/pgdata
    restart: always

  valkey:
    image: valkey/valkey:8-alpine
    restart: always

  pinepods:
    image: madeofpendletonwool/pinepods:latest
    ports:
      - "8040:8040"
    environment:
      # Basic server info
      SEARCH_API_URL: 'https://search.pinepods.online/api/search'
      PEOPLE_API_URL: 'https://people.pinepods.online'
      HOSTNAME: 'http://localhost:8040'
      # Database
      DB_TYPE: postgresql
      DB_HOST: db
      DB_PORT: 5432
      DB_USER: postgres
      DB_PASSWORD: myS3curepass
      DB_NAME: pinepods_database
      # Valkey cache
      VALKEY_HOST: valkey
      VALKEY_PORT: 6379
      DEBUG_MODE: false
      # Run as your host user so downloads stay accessible (optional)
      PUID: ${UID:-911}
      PGID: ${GID:-911}
      # Local timezone (optional, used for logs)
      TZ: "America/New_York"
    volumes:
      - /home/user/pinepods/downloads:/opt/pinepods/downloads
      - /home/user/pinepods/backups:/opt/pinepods/backups
    restart: always
    depends_on:
      - db
      - valkey

For an external Valkey/Redis server, set VALKEY_HOST and VALKEY_PORT on the pinepods service to an address it can reach. Set VALKEY_PASSWORD if the server requires password authentication, and VALKEY_USERNAME if it uses a named user. Remove the local valkey service and its depends_on entry when using an external server.

If Valkey/Redis is unavailable at startup, the API cannot start. Nginx can return 502 for API requests, including /api/health, while the web page still loads. Check the Valkey/Redis service and its connection settings if you encounter this.

Then start it:

sudo docker compose up -d

Open http://localhost:8040 and you'll be prompted to create your first admin account. That's it — you're up.

ℹ️ On PostgreSQL 18 / upgrading from 17. New installs default to postgres:18 and need no special steps. Two things to know when moving an existing install to 18:

• Data isn't auto-migrated across major versions. postgres:18 won't start against a data directory created by 17 (FATAL: database files are incompatible with server). Your data is safe — run deployment/docker/upgrade-postgres.sh (takes a backup, then upgrades in place) or follow the Upgrading PostgreSQL guide. Back up first — the upgrade is one-way.
• The postgres:18 image moved its data dir and VOLUME. Bind-mounting to the old /var/lib/postgresql/data can fail on some Linux/overlay2 hosts with change mount propagation through procfd ... no such file or directory. The compose above avoids this by mounting at /var/lib/pgdata, outside the image's VOLUME; use that same pattern when you upgrade. See docker-library/postgres#1363.

Need more? Helm/Kubernetes, MySQL/MariaDB, admin bootstrap vars, the self-hosted search API, timezone tuning, PUID/PGID, and OIDC are all covered in the docs:

• 🐳 Full server install guide
• ⚓ Helm chart — helm repo add pinepods http://helm.pinepods.online
• 🔍 Self-hosting the search API
• 🔐 OIDC / SSO setup

Clients

Run the server, then connect any client by pointing it at your server URL and signing in. The web client is served by the server itself — the rest are optional native apps.

ARM devices — including 64-bit Raspberry Pis — are fully supported; the latest tag auto-pulls the right architecture. Client setup details live in the clients docs.

Ecosystem

PodPeople DB — A community database that supplements podcast person tags so you can follow hosts across every show they appear on, even when a feed doesn't publish host info. Use the hosted instance at podpeopledb.com or self-host your own. Repo · Why it exists.

Pinepods Firewood — A terminal-only client for enjoying your podcasts from the comfort of the command line. Check it out.

Helm chart — Deploy on Kubernetes with helm repo add pinepods http://helm.pinepods.online. See the install docs for values.

Docs & Community

• 📚 Documentation: pinepods.online
• 💬 Discord: join the chat
• 💬 Matrix: #pinepods:matrix.org
• 📝 Blog: pinepods.online/blog
• 🌍 Translate PinePods: contribute on Weblate — 36 languages and counting.
• 🐛 Issues & contributing: see CONTRIBUTING.md and the issue tracker.

Credits & Licensing

PinePods is an open-source podcast player developed by Gooseberry Development and licensed under the GNU General Public License v3.0 (GPL-3.0).

The mobile app includes code adapted from the excellent Anytime Podcast Player by Ben Hills.

Anytime Podcast Player — © 2020 Ben Hills and contributors, licensed under the BSD 3-Clause License. Affected files retain the original BSD license and attribution at the top; see LICENSE.ben_hills in the mobile/ directory. Huge thanks to Ben Hills for open-sourcing Anytime — it accelerated PinePods' mobile development enormously.

ARM container images are made possible by Runs-On.