PinePods :evergreen_tree:

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.

• :house: Self-hosted & open source — your podcasts and listening data stay on

your hardware (Postgres or MySQL/MariaDB).

• :bustsinsilhouette: Multi-user — one instance serves your whole family, each

with their own library, stats, and settings.

• :iphone: Native apps everywhere — web, Linux, Windows, macOS, Android, and iOS,

plus a CLI client.

• :twistedrightwardsarrows: Bring your own apps — a built-in gpodder-compatible

sync server lets you keep using AntennaPod and friends alongside PinePods.

• :globewithmeridians: Speaks your language — translated into 36 languages by

the community.

:point_right: Want the full story, deep configuration, and tutorials? Head to the

documentation site.

Highlights

| | | |---|---| | :headphones: Listen | Audio and video podcasts, variable speed, chapters, transcripts, downloads, a persistent queue panel, serial auto-play, and per-podcast auto-download. | | :cardindexdividers: Organize | Subscriptions, smart playlists, manual playlists, saved episodes, favorites & favorite categories, full history, and local file-system podcasts. | | :mag: Discover | Search across Podcast Index, iTunes, and YouTube, search inside your own library for episodes, follow podcast hosts via PodPeople DB, and generate shareable episode links. | | :twistedrightwardsarrows: Sync & apps | Built-in gpodder server (AntennaPod, etc.), OIDC / SSO, MFA / TOTP, web + desktop + mobile clients with CarPlay and Android Auto, plus the Firewood CLI. | | :art: Make it yours | Multiple built-in themes plus a custom theme creator, detailed listening stats, OPML import/export, push notifications (ntfy / webhook), and 36 languages. |

See the full feature catalog in the docs.

Screenshots :camera:

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! :zap:

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 :rocket:

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:
      POSTGRESDB: pinepodsdatabase
      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       SEARCHAPIURL: 'https://search.pinepods.online/api/search'       PEOPLEAPIURL: 'https://people.pinepods.online'       HOSTNAME: 'http://localhost:8040'       # Database       DB_TYPE: postgresql       DB_HOST: db       DB_PORT: 5432       DB_USER: postgres       DB_PASSWORD: myS3curepass       DBNAME: pinepodsdatabase       # 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

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.

:information_source: 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:

• :whale: Full server install guide
• :anchor: Helm chart — helm repo add pinepods http://helm.pinepods.online
• :mag: Self-hosting the search API
• :closedlockwithkey: 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.

| Platform | How to get it | Notes | |---|---|---| | :globewithmeridians: Web | Built in — browse to your server's port | No install needed | | :penguin: Linux | Flathub, AUR (paru -S pinepods), or AppImage / .deb / .rpm on Releases | Flatpak recommended | | :window: Windows | .exe (installer) or .msi (portable) on Releases | | | :apple: macOS | .dmg (installer) or portable build on Releases | | | :iphone: iOS | App Store | CarPlay supported | | :robot: Android | Google Play, IzzyOnDroid, or Obtainium | Android Auto supported | | :computer: Terminal | Pinepods Firewood (CLI) | |

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

• :books: Documentation: pinepods.online
• :speechballoon: Discord: join the chat
• :speechballoon: Matrix: #pinepods:matrix.org
• :memo: Blog: pinepods.online/blog
• :earth_africa: Translate PinePods: contribute on

Weblate — 36 languages and counting.

• :bug: 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.