How to Install Pinchflat on Proxmox Container Running on Ubuntu Server

If you want a clean way to archive YouTube channels, playlists, audio feeds, or selected videos inside your homelab, this guide walks through installing Pinchflat on a Proxmox container running Ubuntu Server. The setup uses Docker Compose inside an Ubuntu LXC container, with persistent storage for configuration and downloads, so you can later connect the downloaded media to Jellyfin, Plex, Kodi, or a normal file share.

Pinchflat is a self-hosted YouTube media manager built around yt-dlp project docs. It’s not meant to be a streaming app by itself. Its real strength is automation: you define sources such as channels or playlists, choose how media should be named and stored, and let Pinchflat periodically check for new content.

What This Setup Will Give You

By the end of this tutorial, you’ll have Pinchflat running in Docker inside a Proxmox LXC container, reachable from your LAN at:

http://YOUR-CONTAINER-IP:8945

The final layout will look like this:

This guide assumes you already have Proxmox VE installed and can create an Ubuntu LXC container. If you’re building a broader homelab media setup, the same storage and networking ideas also apply to related projects like Jellyfin transcoding clusters and other Proxmox-based self-hosted services.

Why Use Pinchflat Instead of a Basic YouTube Downloader?

A normal command-line downloader works when you need one video. Pinchflat is better when you want a managed, repeatable archive.

According to the Pinchflat official repo, the app is designed for downloading content from YouTube channels and playlists, automatically checking for new content, organizing files for media center apps, supporting audio downloads, handling Shorts and livestream rules, and integrating with tools such as SponsorBlock.

That makes it useful for homelab users who want:

• Channel archiving: Keep a local copy of selected channels you follow closely.
• Playlist downloads: Save educational playlists, conference talks, tutorials, or public domain content.
• Media server integration: Store files in a structure that Jellyfin, Plex, or Kodi can scan.
• Audio workflows: Download audio-only versions for podcast-style listening.
• Hands-off updates: Let Pinchflat check configured sources instead of manually running commands.

Proxmox LXC or VM: Which Should You Use?

You can run Pinchflat in either a Proxmox VM or a Proxmox LXC container. This tutorial uses LXC because Pinchflat is lightweight and doesn’t need GPU passthrough, heavy isolation, or a full virtual machine for most home setups.

Proxmox uses LXC for its Linux containers, and the Proxmox LXC documentation explains that the pct toolkit is the native management layer for these containers. Running Docker inside LXC works well for many homelab workloads, but it’s still a nested-container setup. If you want the most conservative production-style Docker host, use a VM instead.

Prerequisites Before Installing Pinchflat

Before you install Pinchflat on Proxmox, make sure you have:

• A Proxmox VE host with enough storage for video downloads
• An Ubuntu Server LXC container, preferably Ubuntu 24.04 LTS or 22.04 LTS
• Root or sudo access inside the container
• A static IP address or DHCP reservation for the container
• Enough disk space for your media library
• Docker and Docker Compose plugin installed inside the container

For a small test deployment, 1 CPU core, 1 GB RAM, and 8–16 GB root disk is enough. For real use, the root disk matters less than the media storage path. If you plan to archive large channels, attach a larger Proxmox mount point, NAS share, or dedicated dataset for downloads.

Create the Ubuntu LXC Container in Proxmox

In the Proxmox web UI, create a new container using an Ubuntu Server template. A practical starting configuration is:

The key option is nesting. Docker needs this in an LXC container. You can enable it from the Proxmox UI under the container’s Options or Features section. You can also check the container config from the Proxmox host:

pct config 120

Replace 120 with your actual container ID. You should see something like:

features: nesting=1

If it’s missing, shut down the container and enable nesting:

pct shutdown 120
pct set 120 -features nesting=1
pct start 120

If you’re already running multiple Docker services on Proxmox, keep an eye on network behavior and MTU values. Nested Docker networking can create subtle issues, especially when VLANs, VPNs, or overlay networks are involved. I covered a related troubleshooting pattern in this guide on Docker bridge MTU.

Prepare Ubuntu Server Inside the Container

Enter the container shell from the Proxmox UI or SSH into it:

ssh root@YOUR-CONTAINER-IP

Update the package index and upgrade existing packages:

apt update
apt upgrade -y

Install basic tools:

apt install -y ca-certificates curl gnupg nano htop

Set the timezone to match your location. For India, for example:

timedatectl set-timezone Asia/Kolkata
timedatectl

You should see your selected timezone in the output. Pinchflat can also receive the timezone through Docker Compose, but it’s still worth keeping the container itself correct.

Install Docker Engine on Ubuntu Server

Docker recommends installing Docker Engine from its official apt repository on Ubuntu. The Docker Ubuntu guide lists Ubuntu 24.04 LTS and 22.04 LTS as supported versions, along with the current repository-based installation method.

First, remove conflicting old packages if they exist:

for pkg in docker.io docker-doc docker-compose docker-compose-v2 podman-docker containerd runc; do
  apt remove -y $pkg 2>/dev/null || true
done

Add Docker’s official GPG key and apt source:

apt update
apt install -y ca-certificates curl

install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
chmod a+r /etc/apt/keyrings/docker.asc

tee /etc/apt/sources.list.d/docker.sources > /dev/null <<EOF
Types: deb
URIs: https://download.docker.com/linux/ubuntu
Suites: $(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}")
Components: stable
Architectures: $(dpkg --print-architecture)
Signed-By: /etc/apt/keyrings/docker.asc
EOF

apt update

Install Docker Engine and the Compose plugin:

apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

Verify Docker:

docker --version
docker compose version
docker run hello-world

If hello-world runs successfully, Docker is working inside the Proxmox LXC container.

Create Directories for Pinchflat

The official Pinchflat installation guide requires two writable host directories: one for config and one for downloaded media.

Create a clean directory structure:

mkdir -p /srv/apps/pinchflat/config
mkdir -p /srv/media/youtube
cd /srv/apps/pinchflat

Set ownership. If you’re running commands as root inside the LXC container, this is enough for the initial deployment:

chown -R root:root /srv/apps/pinchflat
chown -R root:root /srv/media/youtube
chmod -R 775 /srv/apps/pinchflat
chmod -R 775 /srv/media/youtube

If you later mount the downloads folder into Jellyfin, Plex, Samba, or NFS, you may need to align user IDs and group permissions. That’s usually where media-server permission problems start, not inside Pinchflat itself.

Create the Pinchflat Docker Compose File

Create the Compose file:

nano /srv/apps/pinchflat/docker-compose.yml

Paste this configuration:

services:
  pinchflat:
    image: ghcr.io/kieraneglin/pinchflat:latest
    container_name: pinchflat
    restart: unless-stopped
    environment:
      - TZ=Asia/Kolkata
    ports:
      - "8945:8945"
    volumes:
      - /srv/apps/pinchflat/config:/config
      - /srv/media/youtube:/downloads

Save the file, then pull and start the container:

cd /srv/apps/pinchflat
docker compose pull
docker compose up -d

Check that the container is running:

docker ps

You should see a container named pinchflat with port 8945 published.

View logs if needed:

docker logs -f pinchflat

Once the service is ready, open:

http://YOUR-CONTAINER-IP:8945

First-Time Pinchflat Configuration

After opening the Pinchflat web UI, spend a few minutes setting the defaults before adding a large channel. This prevents a messy library structure later.

1. Confirm the Download Path

Inside the container, Pinchflat sees the downloads folder as:

/downloads

On the Ubuntu LXC host, the same files live at:

/srv/media/youtube

If you plan to expose these files to Jellyfin or Plex, point your media server to the host-side path or mount the same storage into the media server container.

2. Choose a Naming Pattern

A good media-server-friendly structure keeps channels and videos predictable. For example:

/downloads/{{ source_custom_name }}/{{ title }} [{{ id }}].{{ ext }}

The exact template options depend on Pinchflat’s current naming system, so check the available fields in the UI before settling on a final pattern.

3. Start With One Test Source

Don’t add ten channels immediately. Add one small playlist or channel first, then confirm:

• The download starts correctly
• The files land in /srv/media/youtube
• The filenames are readable
• Your media server can scan the files
• Disk usage grows as expected

Once that test looks good, add larger sources gradually.

Optional: Add a Dedicated Media Mount Point

If your LXC root disk is small, don’t store downloads there. Add a separate Proxmox mount point for media storage.

From the Proxmox host, you can add a mount point like this:

pct set 120 -mp0 /mnt/pve/media-storage/youtube,mp=/srv/media/youtube

Replace:

• 120 with your container ID
• /mnt/pve/media-storage/youtube with the real host-side path
• /srv/media/youtube with the path used inside the LXC container

Restart the container after changing mount points:

pct restart 120

Then check inside the Ubuntu container:

df -h /srv/media/youtube
touch /srv/media/youtube/test-file
ls -l /srv/media/youtube
rm /srv/media/youtube/test-file

If the test file works, update your Compose file to keep using:

- /srv/media/youtube:/downloads

For larger homelab setups, this is cleaner than expanding the container root disk every time your archive grows.

Optional: Put Pinchflat Behind Caddy

For local-only access, http://CONTAINER-IP:8945 is fine. If you want a friendly internal hostname such as pinchflat.lan, you can place it behind Caddy, Nginx, Traefik, or another reverse proxy.

A simple Caddyfile entry looks like this:

pinchflat.lan {
    reverse_proxy 192.168.0.50:8945
}

Replace 192.168.0.50 with your Pinchflat container IP. If you use Caddy in Docker, make sure the Caddy container can reach the LXC IP over the network.

If you’re already using Caddy for homelab services, the same reverse-proxy pattern applies here. I used a similar approach in this write-up on Tailscale Funnel with Caddy, although I’d keep Pinchflat private unless you have a strong reason to expose it.

Managing Pinchflat After Installation

Once Pinchflat is running, the daily operations are simple. Keep these commands handy.

Check Container Status

cd /srv/apps/pinchflat
docker compose ps

View Logs

docker compose logs -f

Restart Pinchflat

docker compose restart

Stop Pinchflat

docker compose down

Update Pinchflat

cd /srv/apps/pinchflat
docker compose pull
docker compose up -d

Check Disk Usage

du -sh /srv/media/youtube
df -h /srv/media/youtube

Video archives grow quickly. If you configure Pinchflat to monitor many channels, disk monitoring isn’t optional. Add alerts or at least check usage regularly.

Backing Up Pinchflat

The most important backup target is the config directory:

/srv/apps/pinchflat/config

This contains the application state and database. The downloaded videos are usually much larger, so decide separately whether you want to back them up. In many setups, the media folder is treated as replaceable, while the config folder is treated as critical.

A simple local backup command looks like this:

mkdir -p /srv/backups/pinchflat

tar -czf /srv/backups/pinchflat/pinchflat-config-$(date +%F).tar.gz \
  -C /srv/apps/pinchflat config

To restore later, stop the container first:

cd /srv/apps/pinchflat
docker compose down

Then restore the config archive into /srv/apps/pinchflat and start the stack again.

If you care about supply-chain hygiene for self-hosted containers, also review image provenance, update cadence, and registry trust. I covered that broader topic in Docker Content Trust.

Common Pinchflat Problems and Fixes

Pinchflat Web UI Doesn’t Open

First check whether the container is running:

docker ps
docker logs pinchflat --tail=100

Then confirm the container is listening on port 8945:

ss -tulpn | grep 8945

If nothing is listening, restart the stack:

cd /srv/apps/pinchflat
docker compose up -d

Also confirm that you’re using the correct container IP:

ip addr

Permission Error on Config or Downloads

The official Pinchflat notes emphasize that the mounted host directories must be writable by the user running the container. Start by checking permissions:

ls -ld /srv/apps/pinchflat/config
ls -ld /srv/media/youtube

For a simple root-run Docker setup inside a private LXC container, reset permissions like this:

chown -R root:root /srv/apps/pinchflat/config
chown -R root:root /srv/media/youtube
chmod -R 775 /srv/apps/pinchflat/config
chmod -R 775 /srv/media/youtube

If Jellyfin, Plex, or Samba also needs access, use a shared group instead of opening permissions too broadly.

Docker Fails Inside the LXC Container

Check that nesting is enabled from the Proxmox host:

pct config 120 | grep features

You want to see:

features: nesting=1

If Docker still fails, confirm the Docker service status inside Ubuntu:

systemctl status docker

Then inspect recent logs:

journalctl -u docker --no-pager -n 100

Downloads Are Slow or Failing

Pinchflat relies on yt-dlp behavior underneath, so download problems can come from network issues, YouTube-side changes, rate limits, blocked formats, or source-specific restrictions.

Check the Pinchflat logs first:

docker logs pinchflat --tail=200

Then verify that the container has working DNS and internet access:

docker exec -it pinchflat sh
wget -qO- https://www.youtube.com/ | head

If DNS fails inside Docker but works on the LXC host, inspect Docker networking, DNS settings, and any Pi-hole or firewall rules you use on the LAN.

Network Share Config Causes Database Issues

Pinchflat’s installation notes warn that SQLite can behave badly with WAL mode on network shares. If you store the config directory on NFS, SMB, or another network filesystem, you may hit locking or corruption risks.

The safer pattern is:

• Keep /config on local LXC storage
• Put only /downloads on large external or network-backed storage
• Back up the config directory regularly

If you knowingly run config on a network share, review Pinchflat’s current documentation for the JOURNAL_MODE environment option before changing anything.

Recommended Production-Like Compose File

For a slightly cleaner long-term setup, use this Compose file with explicit logging limits and a health-oriented restart policy:

services:
  pinchflat:
    image: ghcr.io/kieraneglin/pinchflat:latest
    container_name: pinchflat
    restart: unless-stopped
    environment:
      - TZ=Asia/Kolkata
    ports:
      - "8945:8945"
    volumes:
      - /srv/apps/pinchflat/config:/config
      - /srv/media/youtube:/downloads
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"

This prevents Docker logs from growing forever. It doesn’t replace real monitoring, but it avoids one common homelab annoyance: a service quietly filling the root disk with logs.

Final Thoughts

Installing Pinchflat on a Proxmox container running Ubuntu Server is a practical way to add automated YouTube archiving to your homelab without dedicating a full VM. The core setup is straightforward: enable nesting on the LXC container, install Docker Engine, mount separate config and download directories, deploy Pinchflat with Docker Compose, and access the web UI on port 8945.

The two details that matter most are storage and permissions. Keep the config directory reliable, place downloads on storage that can grow, and make sure any media server you use can read the downloaded files. Once that foundation is right, Pinchflat becomes a clean, low-maintenance way to manage YouTube content alongside the rest of your self-hosted media stack.