{"id":12699,"library":"ytdl-core","title":"YouTube Video Downloader (ytdl-core)","description":"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.","status":"active","version":"4.11.5","language":"javascript","source_language":"en","source_url":"git://github.com/fent/node-ytdl-core","tags":["javascript","youtube","video","download","typescript"],"install":[{"cmd":"npm install ytdl-core","lang":"bash","label":"npm"},{"cmd":"yarn add ytdl-core","lang":"bash","label":"yarn"},{"cmd":"pnpm add ytdl-core","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Internal HTTP client for fetching video metadata and streams.","package":"miniget","optional":false}],"imports":[{"note":"For TypeScript, use `import ytdl from 'ytdl-core';` with `--esModuleInterop` or `import * as ytdl from 'ytdl-core';` with `--allowSyntheticDefaultImports`.","wrong":"const ytdl = require('ytdl-core'); // CommonJS is supported, but ESM is preferred for modern Node.js and TypeScript projects.","symbol":"ytdl","correct":"import ytdl from 'ytdl-core';"},{"note":"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.","wrong":"import { getInfo } from 'ytdl-core'; // getInfo is a method on the default export, not a named export.","symbol":"getInfo","correct":"import ytdl from 'ytdl-core';\nawait ytdl.getInfo(url);"},{"note":"Similar to getInfo, getBasicInfo is a method on the default `ytdl` export, providing lighter metadata without detailed format information.","wrong":"import { getBasicInfo } from 'ytdl-core'; // getBasicInfo is a method on the default export, not a named export.","symbol":"getBasicInfo","correct":"import ytdl from 'ytdl-core';\nawait ytdl.getBasicInfo(url);"}],"quickstart":{"code":"import * as fs from 'fs';\nimport ytdl from 'ytdl-core';\n\nconst videoUrl = 'http://www.youtube.com/watch?v=aqz-KE-bpKQ'; // Example video ID\nconst outputFileName = process.env.VIDEO_OUTPUT_PATH ?? 'video.mp4';\n\nconsole.log(`Downloading video from ${videoUrl} to ${outputFileName}...`);\n\nytdl(videoUrl, { quality: 'highestaudio' })\n  .pipe(fs.createWriteStream(outputFileName))\n  .on('finish', () => {\n    console.log('Download complete!');\n  })\n  .on('error', (err) => {\n    console.error('Error during download:', err.message);\n    // Optionally delete partially downloaded file on error\n    if (fs.existsSync(outputFileName)) {\n      fs.unlinkSync(outputFileName);\n    }\n  });\n\n// Example of fetching video information\n// ytdl.getInfo(videoUrl).then(info => {\n//   console.log('Title:', info.videoDetails.title);\n//   console.log('Formats:', info.formats.length);\n// }).catch(err => console.error('Error fetching info:', err.message));","lang":"typescript","description":"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`."},"warnings":[{"fix":"Regularly update `ytdl-core` to the latest version. If using a wrapper library, ensure it has updated its `ytdl-core` dependency.","message":"YouTube 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.","severity":"breaking","affected_versions":"<4.11.0"},{"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.","message":"The `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.","severity":"gotcha","affected_versions":">=4.0.0"},{"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.","message":"Higher 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.","severity":"gotcha","affected_versions":">=4.0.0"},{"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.","message":"The 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.","severity":"deprecated","affected_versions":">=4.11.5"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"YouTube has made changes to its video embedding or streaming API, or the video itself is geo-restricted/private/deleted.","error":"Error: Video is unavailable"},{"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.","cause":"Often linked to YouTube API changes that prevent `ytdl-core` from correctly parsing available formats, or potentially due to age-restriction/account requirements.","error":"Error: No video formats found"},{"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.","cause":"Typically caused by throttling from YouTube due to too many requests from a single IP, or outdated signature deciphering logic.","error":"TypeError: Cannot read properties of undefined (reading 'pipe') or stream hangs indefinitely"},{"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';`.","cause":"Incorrect TypeScript configuration or import syntax for a package that might not explicitly define default exports for CommonJS `require` when `esModuleInterop` is off.","error":"TS2307: Cannot find module 'ytdl-core' or its corresponding type declarations."}],"ecosystem":"npm"}