n8n-nodes-yt-dlp

A self-hosted n8n Community Node that turns one authorized HTTP(S) media URL into one binary.data Artifact per final file. Version 0.2.0 carries its own pinned yt-dlp, FFmpeg, FFprobe, Deno, and challenge assets; it does not use tools from PATH or download tools at runtime.

Use this node only for content you own or are authorized to download. Extractor behavior can change outside this project, and neither the examples nor the release can guarantee that any particular site is supported.

Support boundary

The v0.2.0 support statement has two deliberately separate parts:

| Boundary | v0.2.0 statement | | --- | --- | | Uyumluluk Hedefi (compatibility target) | n8n >=2.0.0 <3.0.0 | | Doğrulanmış Destek (exact verified support) | Official n8n Docker Linux x64 images for n8n 2.0.0, 2.27.4, and 2.30.7 | | Binary storage | Queue mode with database binary storage | | Worker concurrency | 1 until a lower-concurrency disposable capacity lane passes |

The compatibility target is an intention, not certification of every n8n 2.x patch. Versions after the 2026-07-17 release-candidate cut, including 2.30.8 and later, and intermediate versions not listed above are unverified for node 0.2.0.

Only official n8n Docker Linux x64 is supported. n8n Cloud, n8n 1.x or 3.x, Linux arm64, Windows, macOS, bare-metal npm installs, alternative container bases, and other Linux x64 environments are unsupported. Incidental success does not expand the support boundary.

Install, update, and rollback

Before installation, configure queue mode to use database binary storage on main and every worker. Do not use queue-mode filesystem storage with v0.2.0.

To install:

1. Open Settings → Community Nodes in n8n.
2. Install n8n-nodes-yt-dlp at exact version 0.2.0 and acknowledge n8n's Community Node warning.
3. Wait until the package appears on main and every online worker.
4. Run the authorized first-Artifact workflow below on each worker before enabling production workflows.

The main package installs this exact three-package chain:

[email protected]
└── [email protected]
    └── [email protected]

The main package uses an exact normal dependency on the Platform Selector; the selector uses an exact optional dependency on the Linux x64 Platform Package. This layout is required because the n8n Community Packages installer removes direct optional dependencies, ignores lifecycle scripts, and disables npm bin links. No custom n8n image, container modification, manual yt-dlp/FFmpeg/Deno installation, permission-repair script, PATH fallback, or runtime download is part of the contract.

For queue mode, package files are local to each n8n process even though installed-package metadata is stored in the database. Online workers receive install/update events. Set N8N_REINSTALL_MISSING_PACKAGES=true on workers so a restarted or newly added worker can recover the database-recorded exact version, but treat that setting only as recovery: prove readiness with a real node execution before the worker accepts production jobs.

Update only to a release whose main, selector, and Platform Package are published at the same exact version. Use Community Nodes to update the main package, wait for propagation, verify the exact three-package chain on every worker, and rerun the first-Artifact check.

For an operator rollback, disable affected workflows, remove the bad main package through Community Nodes, install the previous known-good exact main version, wait for every worker to converge, and run the readiness workflow before re-enabling traffic. Do not edit worker node_modules, replace bundled tools, or use npm directly inside containers. Release maintainers must not unpublish: move or remove the main package's latest/next tags first, then the selector and Platform Package tags, deprecate all three bad versions, and publish a new lockstep patch.

First Artifact

Create a workflow with Manual Trigger → yt-dlp. Use a media URL that you own or are explicitly authorized to download:

| Field | First run | | --- | --- | | Source URL | Your authorized absolute https:// media URL | | Arguments | leave empty | | Request Timeout (Minutes) | 30 | | Maximum Artifact Count | 20 | | Maximum Artifact Size (MiB) | 128 | | Maximum Total Artifact Size (MiB) | 256 |

Run the workflow. A successful direct-media request produces one output item with the file under binary.data; a playlist may produce several items. Every input item is a separate İndirme İsteği (Download Request), while a playlist URL remains one request. Inputs are processed sequentially.

The repository release gate uses only project-generated synthetic media served by its disposable, network-local fixture origin. That fixture URL is intentionally not a public example. Replace it with your own authorized source; do not copy a third-party media URL into documentation or tests.

After the empty-Arguments run, safe format selection can be expressed without repeating the URL:

-f "bv*+ba/b" --merge-output-format mp4

Audio extraction is another supported example:

-x --audio-format mp3 --audio-quality 0

These examples demonstrate argument handling, not support for a particular extractor or site.

Source URL

Source URL is separate from Arguments. It must be an absolute http: or https: URL, contain no userinfo such as user:password@host, contain no control characters or surrounding whitespace, and be at most 16 KiB in UTF-8. Search prefixes, bare searches, local/data/stream URLs, batch input, and local info JSON are rejected before yt-dlp starts.

Arguments Grammar

Arguments is the option line that would follow the yt-dlp executable, without the executable or Source URL. The dependency-free grammar supports:

• space or tab token separation;
• single and double quotes;
• documented backslash escapes;
• adjacent quoted and unquoted fragment joining;
• empty quoted tokens; and
• --option=value, --option value, and the four explicit short aliases below.

Outside quotes, backslash may escape only a space, tab, single quote, double quote, or another backslash. Inside double quotes, only \" and \\ are escapes. Inside single quotes, backslash is literal. Dollar signs and backticks are rejected even inside quotes.

It performs no environment, command, tilde, brace, or glob expansion. Comments, shell operators, multiline input, positional tokens, a -- terminator, short-option clusters, and attached short values are rejected. The limits are 16 KiB for the complete field, 256 tokens, and 8 KiB for one token.

V1 Argument Allowlist

The exact v1 allowlist is:

| Purpose | Accepted options | | --- | --- | | Format | -f, --format, -S, --format-sort, --format-sort-force, --merge-output-format | | Playlist | -I, --playlist-items, --yes-playlist, --no-playlist | | Subtitles | --write-subs, --write-auto-subs, --sub-langs, --sub-format, --convert-subs, --embed-subs | | Thumbnails | --write-thumbnail, --convert-thumbnails, --embed-thumbnail | | Audio | -x, --extract-audio, --audio-format, --audio-quality | | Video/post-processing | --remux-video, --recode-video, --embed-metadata, --embed-chapters, --no-embed-chapters |

The exact value and relationship rules are:

• --format accepts one non-empty yt-dlp format expression that does not begin with -. --format-sort accepts a comma-separated list of sort fields, each beginning with a letter and optionally prefixed by + or -, with yt-dlp : or ~ value suffixes; its value is limited to 1,024 characters. --format-sort-force requires --format-sort.
• --merge-output-format accepts one or a /-separated preference list of avi, flv, mkv, mov, mp4, webm.
• --playlist-items accepts comma-separated positive indexes, closed start-end ranges, or [start]:end[:step] slices. Its value is limited to 512 characters and its calculable cardinality may not exceed 20. Without it, the node adds --playlist-items 1:5. --yes-playlist and --no-playlist conflict.
• --sub-langs, --sub-format, --convert-subs, and --embed-subs require --write-subs or --write-auto-subs. Subtitle formats are ass, best, lrc, srt, or vtt; conversion excludes best. --sub-langs is a non-empty expression of at most 512 characters and rejects whitespace, path/shell metacharacters, and a leading -.
• --convert-thumbnails and --embed-thumbnail require --write-thumbnail. Thumbnail conversion accepts /-separated values or source>target rules using only jpg, png, and webp.
• --audio-format and --audio-quality require --extract-audio. Audio formats are aac, alac, best, flac, m4a, mp3, opus, vorbis, and wav. Quality is a decimal from 0 through 10 or a positive decimal bitrate ending in k or K.
• --remux-video and --recode-video conflict. Each accepts /-separated values or source>target rules using aac, aiff, alac, avi, flac, flv, gif, m4a, mka, mkv, mov, mp3, mp4, ogg, opus, vorbis, wav, or webm.
• --embed-chapters and --no-embed-chapters conflict.

Aliases are canonicalized, and every canonical option may appear only once. Unknown, duplicated, conflicting, value-invalid, and dependency-incomplete options fail before process start. Boolean options reject an attached value.

Authentication

Create an optional YT-DLP Authentication credential and attach it to the node. It can contain:

• Netscape cookie-file content;
• site username and password;
• video password; and
• authenticated proxy URL.

Cookie content is written to an owner-only 0600 file inside the request workspace. Other values are serialized to a one-use Secret Config sent through stdin. Secrets are excluded from workflow JSON, argv, inherited environment, Result items, and logs, and temporary cookie material is removed on every catchable outcome.

Arbitrary headers or tokens, browser-cookie import, user-provided cookie/netrc/config paths, command-based credentials, OAuth/browser login, OTP/2FA, and client-certificate paths are not supported.

Result contract

A successful Atomik İndirme İsteği publishes an Artifact Item only after yt-dlp has completed and the complete final file set has been validated. Each physical file becomes a separate item in deterministic basename order:

{
  "json": {
    "status": "success",
    "artifactIndex": 1,
    "artifactCount": 1,
    "fileName": "authorized-media.mp4",
    "mimeType": "video/mp4",
    "sizeBytes": 1048576
  },
  "binary": {
    "data": "<n8n binary metadata>"
  },
  "pairedItem": {
    "item": 0
  }
}

MIME type comes from a fixed extension table. An unknown extension uses application/octet-stream; the node does not sniff content. Source URL, Arguments, credentials, process output, and worker paths are never copied into the Result.

With Continue On Fail disabled, a request error stops execution with an item-linked n8n error. With it enabled, only a typed request error becomes one binary-free Failure Item and later inputs continue:

{
  "json": {
    "status": "error",
    "errorCode": "INVALID_ARGUMENTS",
    "errorMessage": "The Arguments value is invalid."
  },
  "pairedItem": {
    "item": 0
  }
}

The stable request error codes are INVALID_SOURCE_URL, INVALID_ARGUMENTS, YTDLP_FAILED, REQUEST_TIMEOUT, PROCESS_OUTPUT_LIMIT, RESOURCE_LIMIT, INVALID_ARTIFACT_SET, and BINARY_TRANSFER_FAILED. Cancellation, execution-wide limits, toolchain/invariant failures, cleanup failures, and unknown exceptions always stop the execution, even with Continue On Fail. Cancellation terminates the managed yt-dlp/FFmpeg/Deno process group and waits for process and stream closure before cleanup.

Cancellation example

Use only an owned or explicitly authorized endpoint that responds slowly enough to cancel safely:

1. Create Manual Trigger → yt-dlp, set Source URL to that authorized slow media URL, leave Arguments empty, and enable Continue On Fail if you also want to verify its cancellation boundary.
2. Start the manual execution.
3. While the request is running in the n8n execution view, use Stop.
4. The execution stops globally. No Artifact Item or Failure Item is returned, later input items do not run, and Continue On Fail is not applied. The node terminates the process group before removing the owned workspace.

Output atomicity is not storage transactionality. If transfer of a later Artifact fails, the request publishes no Artifact Items (or one BINARY_TRANSFER_FAILED Failure Item with Continue On Fail), but an earlier backend write may remain unreferenced until n8n execution hard-delete and pruning. The node does not call an internal deletion API.

Resource Envelope

| Limit | Default | Hard cap | | --- | ---: | ---: | | Inputs per execution | — | 20 | | Execution duration | — | 2 hours | | Request timeout | 30 minutes | 60 minutes | | Artifacts per request | 20 | 50 | | One Artifact | 128 MiB | 256 MiB | | All final Artifacts | 256 MiB | 512 MiB | | Playlist entries | first 5 | 20 explicitly selected | | FFmpeg threads | 1 | 1 | | yt-dlp fragment concurrency | 1 | 1 |

Workspace usage is checked at least once per second and is capped at twice the configured final total plus 64 MiB. Binary transfer is sequential. Configurable limits may be lowered or raised only up to the immutable hard caps. These limits bound one execution; they are not deployment sizing or capacity guarantees. See the operator runbook.

Security boundary

The node validates the Source URL structure but is not an application-layer SSRF firewall. Extractors may follow redirects and resolve DNS, manifests, media URLs, or FFmpeg inputs that the node cannot safely pre-classify. Operators who accept untrusted URLs are responsible for container/host egress controls, DNS policy, proxy allowlists, private/link-local/metadata endpoint blocking, and network monitoring.

V0.2.0 deliberately does not expose:

• arbitrary yt-dlp CLI, output paths, configs, plugins, self-update, user-selectable runtimes, external commands, local files, debug/print/simulation, or resource-control options;
• broader authentication, header, certificate, OAuth, or browser-login surfaces;
• system tool fallback or container mutation;
• S3 binary storage, queue-mode filesystem storage, or transactional backend rollback;
• n8n AI Agent tool use (the normal-node adapter drops binary data);
• a sandbox against the worker UID or root;
• node-owned metrics/telemetry or immediate cleanup after SIGKILL/OOM/host failure; or
• a supported-site, redistribution-rights, or extractor-availability guarantee.

License and Corresponding Source

Project-authored TypeScript, JavaScript, tests, documentation, and build orchestration are MIT. Third-party components keep their own licenses; the binary Platform Package uses SEE LICENSE IN LICENSES.md and must not be described as wholly MIT or wholly GPL. Review the component license map, third-party notices, and verbatim packages/linux-x64/LICENSES/ inventory.

The Toolchain Lock freezes upstream tags/commits, asset names, SHA-256 values, licenses, runtime-image identities, and source-bundle identities. The issue-18 disposable capacity record measured these exact packed bytes:

| Package tarball | SHA-256 | | --- | --- | | [email protected] | f32fd4b76ac05569be0cde8c52016f3ef31859378b4144530f41c3227ce960c2 | | [email protected] | b525d359da35fcf77091e84603c221aa2bc34e87c814511644fa974852ad701e | | [email protected] | d6f7bc87f15942a8b45bcc7cc4c04b95073e56468def1d5408754f902c94629e |

Those are local release-gate tarball digests, not proof that registry bytes have been published. Registry metadata, provenance, and tarball digests must be read back and matched before promotion.

The immutable FFmpeg Corresponding Source Bundle is n8n-nodes-yt-dlp-ffmpeg-source-0.2.0.tar.xz, SHA-256 3dcd8963e229e3b34fb9d0d969377e59e25a01146fd128282ad599200034e882. The complete immutable source list and digests for yt-dlp, Deno, EJS, FFmpeg, and the Linux runtime are in CORRESPONDING_SOURCE.md.

After extracting the FFmpeg bundle, follow its toolchain/README.md and run:

./toolchain/rebuild.sh /absolute/output/directory

The rebuild consumes the bundled exact sources and uses network-isolated Docker build phases. The Linux runtime is reproduced separately from pinned images with:

./toolchain/linux-x64/build-runtime.sh /absolute/output/directory

Run the repository gates with:

npm run verify:ffmpeg-compliance
npm run verify:ffmpeg-release

Publication remains blocked while the Toolchain Lock records the combined runtime Corresponding Source gate as pending, or until the immutable source assets, clean isolated rebuild evidence, and maintainer license review all pass. A mutable upstream link or source-on-request is not a substitute for a versioned source asset.

Operations and troubleshooting

For queue, worker, container, temp, Postgres, Redis, binary storage, capacity, stale cleanup, and targeted recreation procedures, use the operator runbook.