Home

Welcome to the Pinchfork wiki. Pinchfork is an actively maintained PostgreSQL fork of Pinchflat, a self-hosted YouTube media manager built on yt-dlp.

The FAQ is a great place to start if you're new. For installation, see Installation.

A note on naming: Throughout this wiki, Pinchfork refers to this fork and Pinchflat refers to the upstream project. A few low-level identifiers (the database container name, DB user, and DATABASE_URL segments) keep the pinchflat name because they are inherited from the upstream-derived image — renaming them breaks existing deployments. These are called out where they appear.

⚠️ Playlist support is currently inconsistent. Playlists may fail to download media, fail to fetch metadata, or behave unpredictably depending on the deployment. Channel URLs are recommended. Playlist support is being actively investigated.

⚠️ ARM hardware (Raspberry Pi) is unsupported. Pinchfork runs on Pi hardware but there are known architecture-specific bugs with yt-dlp source type detection and YouTube authentication. Use on Pi at your own risk. Issues specific to ARM are low priority and may not be fixed.

---

Getting started

• Installation — Docker Compose setup with Postgres, environment variables, updating
• FAQ — common questions about indexing, downloading, filtering, and media center setup
• YouTube Cookies — using cookies for private playlists and members-only content
• Username and Password — enabling HTTP basic authentication

Fork-specific features

• Fork Changes — full list of what differs from upstream Pinchflat
• Roadmap — planned features and known bugs
• SABR Bypass and PO Tokens — working around SABR-corrupted downloads and enabling PO Token support
• Local Temp Staging — staging downloads on a local disk when /downloads is a network mount
• Configuration Differences from Upstream — migrating from Pinchflat, env vars added/removed, new fields

Advanced

• Custom yt-dlp options — per-source and per-profile yt-dlp config files
• Custom lifecycle scripts — running scripts on download events
• yt-dlp plugins — the baked-in bgutil plugin and adding others

Other

• Generating a YouTube API key — speeding up Fast Indexing with an API key
• Podcast RSS Feeds — bringing downloaded content into a podcast app
• Prometheus and Grafana — enabling application metrics
• Automatically Delete Media — retention periods per source