Caution
The head repo for Pinchflat (fork) has been pulled for unknown reasons. Unless development comes this way or I find the time to learn and update it, this project will remain stale. Sorry, I am not a dev and am still learning code.
I am not responsible for any security vulnerabilities or bugs that may crop up.
Feel free to fork this project as I want to see this evolve.
Important
Pinchflat vs. Tubeless.
Review the options below and carefully choose your own adventure.
This is a community-maintained fork of kieraneglin/pinchflat. The original project is not actively maintained; this fork exists to continue development and apply community contributions. See Migrating from kieraneglin/pinchflat. PRs welcome — see CONTRIBUTING.md. Discord Server created!
logo by @hernandito
- Your next YouTube media manager
Pinchflat is a self-hosted app for downloading YouTube content built using yt-dlp. It's designed to be lightweight, self-contained, and easy to use. You set up rules for how to download content from YouTube channels or playlists, and it'll do the rest, periodically checking for new content. It's perfect for people who want to download content for use with a media center app (Plex, Jellyfin, Kodi) or for those who want to archive media!
While you can download individual videos, Pinchflat is best suited for downloading content from channels or playlists. It's also not meant for consuming content in-app - Pinchflat downloads content to disk, where you can then watch it with a media center app or VLC.
If it doesn't work for your use case, please make a feature request! You can also check out these great alternatives: Tube Archivist, ytdl-sub, and TubeSync
- Self-contained - just one Docker container with no external dependencies
- Powerful naming system so content is stored where and how you want it
- Easy-to-use web interface with presets to get you started right away
- First-class support for media center apps like Plex, Jellyfin, and Kodi (docs)
- Supports serving RSS feeds to your favourite podcast app (docs)
- Automatically downloads new content from channels and playlists
- Uses a novel approach to download new content more quickly than other apps
- Supports downloading audio content
- Custom rules for handling YouTube Shorts and livestreams
- Apprise support for notifications
- Allows automatically redownloading new media after a set period
- This can help improve the download quality of new content or improve SponsorBlock tags
- Optionally automatically delete old content (docs)
- Advanced options like setting cutoff dates and filtering by title (docs)
- Reliable hands-off operation
- Can pass cookies to YouTube to download your private playlists (docs)
- Sponsorblock integration
- [Advanced] control how
yt-dlpupdates from Settings - track stable or nightly, pin an exact version, or temporarily ride nightly and auto-return to stable once the fix lands there - [Advanced] allows custom
yt-dlpoptions (docs) - [Advanced] supports running custom scripts after downloading/deleting media (alpha - docs)
Simply search for Pinchflat in the Community Apps store!
- Currently unavailable.
Important
See the note below about storing config on a network file share. It's preferred to store the config on a local disk if at all possible.
Docker Compose file:
services:
pinchflat:
image: ghcr.io/communitymaintained/pinchflat:latest
environment:
# Set the timezone to your local timezone
- TZ=America/New_York
ports:
- '8945:8945'
volumes:
- /host/path/to/config:/config
- /host/path/to/downloads:/downloads- Create two directories on your host machine: one for storing config and one for storing downloaded media. Make sure they're both writable by the user running the Docker container.
- Prepare the Docker image in one of the two ways below:
- From GHCR:
docker pull ghcr.io/communitymaintained/pinchflat:latest- NOTE: also available on Docker Hub at
communitymaintained/pinchflat:latest
- NOTE: also available on Docker Hub at
- Building locally:
docker build . --file docker/selfhosted.Dockerfile -t ghcr.io/communitymaintained/pinchflat:latest
- From GHCR:
- Run the container:
# Be sure to replace /host/path/to/config and /host/path/to/downloads below with
# the paths to the directories you created in step 1
# Be sure to replace America/New_York with your local timezone
docker run \
-e TZ=America/New_York \
-p 8945:8945 \
-v /host/path/to/config:/config \
-v /host/path/to/downloads:/downloads \
ghcr.io/communitymaintained/pinchflat:latestThe Podman setup is similar to Docker, but changes a few flags to run under a User Namespace instead of root. To run Pinchflat under Podman and use the current user's UID/GID for file access, run this:
podman run \
--security-opt label=disable \
--userns=keep-id --user=$UID \
-e TZ=America/Los_Angeles \
-p 8945:8945 \
-v /host/path/to/config:/config:rw \
-v /host/path/to/downloads/:/downloads:rw \
ghcr.io/communitymaintained/pinchflat:latest
Using this setup, consider creating a new pinchflat user and giving that user ownership of the config and download directory. See Podman --userns docs.
You must ensure the host directories you've mounted are writable by the user running the Docker container. If you get a permission error, follow the steps it suggests. See upstream #106 for more.
Important
It's not recommended to run the container as root. Doing so can create permission issues if other apps need to work with the downloaded media.
As pointed out in upstream #137, SQLite doesn't like being run in WAL mode on network shares. If you're running Pinchflat on a network share, you can disable WAL mode by setting the JOURNAL_MODE environment variable to delete. This will make Pinchflat run in rollback journal mode, which is less performant but should work on network shares.
Caution
Changing this setting from WAL to delete on an existing Pinchflat instance could, conceivably, result in data loss. Only change this setting if you know what you're doing, why this is important, and are okay with possible data loss or DB corruption. Backup your database first!
If you change this setting and it works well for you, please open an issue or leave a comment on upstream #137! Doubly so if it does not work well.
| Name | Required? | Default | Notes |
|---|---|---|---|
TZ |
No | UTC |
Must follow IANA TZ format |
LOG_LEVEL |
No | debug |
Can be set to info, warning, & error, but debug is strongly recommended |
UMASK |
No | 022 |
Unraid users may want to set this to 000 |
BASIC_AUTH_USERNAME |
No | See authentication docs | |
BASIC_AUTH_PASSWORD |
No | See authentication docs | |
EXPOSE_FEED_ENDPOINTS |
No | false |
See RSS feed docs |
ENABLE_IPV6 |
No | false |
Setting to any non-blank value will enable IPv6 |
JOURNAL_MODE |
No | wal |
Set to delete if your config directory is stored on a network share (not recommended) |
TZ_DATA_PATH |
No | <EXTRAS_PATH>/elixir_tz_data |
The container path where the timezone database is stored |
BASE_ROUTE_PATH |
No | / |
The base path for route generation. Useful when running behind certain reverse proxies - prefixes must be stripped. |
YT_DLP_WORKER_CONCURRENCY |
No | 2 |
The number of concurrent workers that use yt-dlp per queue. Set to 1 if you're getting IP limited, otherwise don't touch it |
ENABLE_PROMETHEUS |
No | false |
Setting to any non-blank value will enable Prometheus. See docs |
Pinchflat makes heavy use of websockets for real-time updates. If you're running Pinchflat behind a reverse proxy, then you'll need to make sure it's configured to support websockets.
To configure Pinchflat behind Caddy, set the BASE_ROUTE_PATH environment variable to /pinchflat/ then add a stanza like this to the Caddyfile:
home.example.com:443 {
redir /pinchflat /pinchflat/
handle_path /pinchflat/* {
reverse_proxy localhost:8945
}
}The data format is identical — no database changes are needed. Just update the image reference in your Docker run command or compose file:
ghcr.io/kieraneglin/pinchflat:latest → ghcr.io/communitymaintained/pinchflat:latest
Also available on Docker Hub as communitymaintained/pinchflat:latest.
Stop the old container, update the image reference, and start it again. Your /config and /downloads volumes carry over unchanged.
You can switch back to upstream (Kieran's image) at any time by simply pointing the image to ghcr.io/kieraneglin/pinchflat:latest. If you wish to make a 100% clean return, run the one-off command below first. It removes all traces of this from the Pinchflat's database.
docker compose run --rm pinchflat bin/pinchflat eval "Pinchflat.Release.prep_for_upstream()"The command drops the fork-only DB columns, removes their migration records so the ledger matches upstream too, and exits. Next, just switch the image reference to upstream next and start the container. If you start this fork again instead, it re-adds its columns automatically and keeps working (it self-heals rather than breaking).
This step is optional — return works without it. It exists only for users who want an identical schema. The dropped columns (e.g. the yt-dlp update policy and unavailable-media status) are removed along with their data.
This software is in active development, and anything can break at any time. I make no guarantees about the stability of this software, forward-compatibility of updates, or integrity (both related to and independent of Pinchflat).
This project is intended only for downloading and managing content you have the legal right to access and copy (e.g., your own uploads, public‑domain works, or content licensed for download). You are responsible for complying with copyright law, platform terms of service, and any applicable regulations.
Not legal advice. This repository provides software only. It is not affiliated with YouTube, Plex, Jellyfin, or any other platform. The authors and contributors do not endorse or encourage unauthorized copying, circumvention of access controls, or other unlawful use.
If you plan to use this project publicly, make sure your usage and documentation do not promote or facilitate infringement or bypass of technical protection measures.
See LICENSE file