ytdl-core

library4.11.5jsnpmunverified

ytdl-core is a pure JavaScript library designed for downloading YouTube videos directly within Node.js environments, offering a streaming interface for efficient processing. Its current stable version is 4.11.5, with releases typically occurring as needed to address breaking changes from YouTube's API or to introduce minor features and bug fixes. The project shows an active maintenance cycle, frequently releasing patches (e.g., 4.11.2 to 4.11.5 in a few months) to adapt to YouTube's evolving infrastructure, particularly around video parsing and signature deciphering. A key differentiator is its focus on a lean, Node.js-friendly streaming API, allowing developers to pipe video streams directly to file systems or other processing utilities without intermediate storage. It ships with TypeScript types, facilitating its use in modern TypeScript projects.

http-networking

npm install ytdl-core

github ↗package ↗

INSTALL

IMPORT

SIG · YTDL-CORE

ytdl-core

http-networkingjavascriptv4.11.5

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

ytdl

✓ import ytdl from 'ytdl-core';

✗ const ytdl = require('ytdl-core'); // CommonJS is supported, but ESM is preferred for modern Node.js and TypeScript projects.

For TypeScript, use `import ytdl from 'ytdl-core';` with `--esModuleInterop` or `import * as ytdl from 'ytdl-core';` with `--allowSyntheticDefaultImports`.

getInfo

✓ import ytdl from 'ytdl-core'; await ytdl.getInfo(url);

✗ import { getInfo } from 'ytdl-core'; // getInfo is a method on the default export, not a named export.

getInfo is an asynchronous function available as a method on the default `ytdl` export. It returns a Promise with detailed video metadata and format information.

getBasicInfo

✓ import ytdl from 'ytdl-core'; await ytdl.getBasicInfo(url);

✗ import { getBasicInfo } from 'ytdl-core'; // getBasicInfo is a method on the default export, not a named export.

Similar to getInfo, getBasicInfo is a method on the default `ytdl` export, providing lighter metadata without detailed format information.

This quickstart demonstrates how to download a YouTube video using `ytdl-core` and pipe it directly to a file. It also shows a commented-out example of how to retrieve video metadata using `getInfo`.

import * as fs from 'fs'; import ytdl from 'ytdl-core'; const videoUrl = 'http://www.youtube.com/watch?v=aqz-KE-bpKQ'; // Example video ID const outputFileName = process.env.VIDEO_OUTPUT_PATH ?? 'video.mp4'; console.log(`Downloading video from ${videoUrl} to ${outputFileName}...`); ytdl(videoUrl, { quality: 'highestaudio' }) .pipe(fs.createWriteStream(outputFileName)) .on('finish', () => { console.log('Download complete!'); }) .on('error', (err) => { console.error('Error during download:', err.message); // Optionally delete partially downloaded file on error if (fs.existsSync(outputFileName)) { fs.unlinkSync(outputFileName); } }); // Example of fetching video information // ytdl.getInfo(videoUrl).then(info => { // console.log('Title:', info.videoDetails.title); // console.log('Formats:', info.formats.length); // }).catch(err => console.error('Error fetching info:', err.message));

Debug

Known issues

breakingYouTube frequently updates its website and API, which can lead to `ytdl-core` breaking or requiring updates to continue functioning. Developers should ensure they are using the latest version.

fix

Regularly update `ytdl-core` to the latest version. If using a wrapper library, ensure it has updated its `ytdl-core` dependency.

affects: <4.11.0

gotchaThe `begin` option for starting a video download at a specific timestamp is known to be unreliable for non-live videos, as documented in issues #129 and #219.

fix

For precise segment downloads, consider manually seeking or processing the full download with a tool like FFmpeg, or using the `range` option if applicable.

affects: >=4.0.0

gotchaHigher quality video formats (1080p and above) are often delivered without an accompanying audio track. Downloading such formats requires separate audio and video streams to be downloaded and then merged, typically with an external tool like FFmpeg.

fix

Utilize `ytdl.getInfo()` to get available formats, select separate audio-only and video-only streams, download them, and then use a library (e.g., `fluent-ffmpeg`) to merge them. See the `example/ffmpeg.js` in the official repository.

affects: >=4.0.0

deprecatedThe primary maintainer has paused active development on `fent/node-ytdl-core` since July 14, 2023, with support now community-driven and PRs not currently merged. Users are encouraged to explore forks like `@distube/ytdl-core` for ongoing updates.

fix

For active development and guaranteed fixes, consider migrating to a actively maintained fork like `@distube/ytdl-core` if you encounter persistent issues or require new features.

affects: >=4.11.5

Errors

Common errors & fixes

Error: Video is unavailable

YouTube has made changes to its video embedding or streaming API, or the video itself is geo-restricted/private/deleted.

fix

Ensure `ytdl-core` is the latest version. Check if the video is genuinely available and not restricted. For geo-restricted or private videos you have access to, consider using proxy or cookie options.

Error: No video formats found

Often linked to YouTube API changes that prevent `ytdl-core` from correctly parsing available formats, or potentially due to age-restriction/account requirements.

fix

Update `ytdl-core` to the latest version to get the newest parsing fixes. If the problem persists, check for existing issues on the GitHub repository or create a new one, providing the video URL.

TypeError: Cannot read properties of undefined (reading 'pipe') or stream hangs indefinitely

Typically caused by throttling from YouTube due to too many requests from a single IP, or outdated signature deciphering logic.

fix

Ensure `ytdl-core` is updated. Implement IPv6 rotation via the `IPv6Block` option or use a proxy to circumvent throttling. Adjust `dlChunkSize` if large files are being throttled.

TS2307: Cannot find module 'ytdl-core' or its corresponding type declarations.

Incorrect TypeScript configuration or import syntax for a package that might not explicitly define default exports for CommonJS `require` when `esModuleInterop` is off.

fix

In `tsconfig.json`, set `"esModuleInterop": true` or `"allowSyntheticDefaultImports": true`. Then use `import ytdl from 'ytdl-core';`. Alternatively, use `import * as ytdl from 'ytdl-core';`.

Upgrade

Version history

4.11.5latest on npm

Audit

Dependencies

minigetrequiredInternal HTTP client for fetching video metadata and streams.

Agent activity

36 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/fent/node-ytdl-core ↗

packagehttps://www.npmjs.com/package/ytdl-core ↗