Skip to content

Local Temp Staging

Jump to bottom
o51r15 edited this page Jun 18, 2026 · 1 revision

When your /downloads directory is a network mount (SMB/CIFS, NFS), yt-dlp performs all intermediate work — fragment downloads, stream merging, post-processing (thumbnail embedding, metadata, subtitle muxing) — directly over the network. On many setups, the repeated read/write/rename activity over a network mount corrupts the in-progress file, producing:

Postprocessing: Error opening input files: Invalid data found when processing input

Setting LOCALTEMP=true moves all intermediate yt-dlp work to a local disk. Only the finished, fully-processed file is moved to the downloads directory at the very end — a single atomic operation rather than continuous network I/O throughout the download.

Setup

Add LOCALTEMP=true to your environment and mount a local directory at /downloads-staging:

services:
  pinchfork:
    environment:
      - LOCALTEMP=true
    volumes:
      - /path/to/local/staging:/downloads-staging   # must be a LOCAL disk
      - /path/to/network/downloads:/downloads

The staging directory must be:

  • On a real local disk — not the network mount, not another network path
  • Large enough for the biggest in-flight download plus its intermediates (unmerged streams can be 2–3x the final file size during processing)

To disable, remove LOCALTEMP=true. The /downloads-staging volume mount is harmless if left in place.

Per-item isolation

Each download is staged in its own subdirectory under /downloads-staging, keyed on the video's unique ID. This means:

  • Multiple concurrent downloads never interfere with each other
  • A failed or abandoned download's staging files are cleaned up automatically — before the next retry, on failure, and after success
  • Stale intermediates from a previous crash do not accumulate or interfere with later runs

How it works

yt-dlp ignores --paths when --output is an absolute path. To make staging work correctly, Pinchfork rewrites the download options when LOCALTEMP=true is set:

  • --paths home:<staging base dir> — tells yt-dlp where to write the finished file initially
  • --paths temp:<staging base dir>/<video-id> — per-item temp directory for fragments and intermediates
  • The output template is rewritten to be relative rather than absolute

With LOCALTEMP unset, download options are completely unchanged — this feature has no effect on standard local-disk setups.

Clone this wiki locally