tubepull
v1.1.0
Published
Download YouTube video or audio at any available quality from Node.js or the command line. Bundled ffmpeg, no Python.
Maintainers
Readme
npx tubepull https://youtu.be/aqz-KE-bpKQFeatures
[!NOTE] tubepull is a downloader that bundles several tools into one package. It talks to YouTube through the maintained youtubei.js InnerTube client. When YouTube changes something, the fix usually arrives as a youtubei.js update followed by a tubepull patch release.
Install
npm i -g tubepull # command line
npm i tubepull # library| Requirement | Details |
| ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Node.js | 22.12 or newer |
| OS | Windows, macOS, Linux |
| ffmpeg | Downloaded automatically by ffmpeg-static during install. If that step was skipped, see Troubleshooting. |
Command line
tubepull # interactive wizard
tubepull <url> -q 1080p -o ./downloads # video
tubepull <url> -f mp3 # audio
tubepull <url> -f mp3 --cookies ./cookies.txt
tubepull <url> --list # available qualities
tubepull <playlist-url> -q 720p --concurrency 3
tubepull doctor # diagnosticsRun tubepull without arguments to choose a link, format and destination interactively. Add --yes to
skip prompts. Normal playlists support --playlist; YouTube Mix links download only the selected video.
All flags, trimming, JSON output and exit codes: CLI reference.
Library
Create an instance with the defaults; no cookie file is needed for this example.
import { TubePull } from 'tubepull';
const yt = await TubePull.create();
const info = await yt.getInfo('https://youtu.be/aqz-KE-bpKQ');
console.log(info.qualities.map((q) => q.label));
await yt.download(info, { quality: '1080p', outputDir: './downloads' });
await yt.download(info, { type: 'audio', audioFormat: 'mp3', outputDir: './downloads' });CommonJS: const { TubePull } = require('tubepull'). Errors expose a code and an actionable hint.
To override the default session, supply your own Netscape cookies.txt file:
import { TubePull } from 'tubepull';
const yt = await TubePull.create({ cookies: './cookies.txt' });
await yt.download('https://youtu.be/aqz-KE-bpKQ', { type: 'audio', audioFormat: 'mp3' });Or set YT_COOKIES to a raw Cookie header (name=value; name2=value2) or a cookie-file path:
import { TubePull } from 'tubepull';
const yt = await TubePull.create({ cookies: process.env.YT_COOKIES });
await yt.download('https://youtu.be/aqz-KE-bpKQ', { type: 'audio', audioFormat: 'mp3' });Streaming, progress events and advanced options: API reference and Runnable examples.
Quality and containers
| Output | Video codecs copied | Audio codecs copied | Otherwise |
| ------------- | ------------------- | ------------------- | ---------------------------------------------------- |
| mp4 (default) | H.264, AV1 | AAC | switches to mkv, or re-encodes with allowTranscode |
| webm | VP9, AV1 | Opus | switches to mkv, or re-encodes |
| mkv | anything | anything | — |
HDR streams are used only when you ask for them (hdr: true / --hdr), because SDR screens display HDR video washed
out. When converting audio, Opus counts as a better source than AAC of similar bitrate, because it is the more
efficient codec.
How it stays reliable
tubepull tries multiple playback clients, waits out required prerolls, and refreshes expired or refused stream URLs. Downloads resume from the last received byte when the replacement stream matches the original.
- API requests share a limit of 2 in flight, at least 300 ms apart.
- Valid extraction results are reused across inspection, downloads and retries.
- Rate limits pause requests for the instance; session renewals are capped at once a minute.
Running on a server (VPS, Vercel)
Use the same CLI or library calls on a VPS, and reuse one TubePull instance per process. The default session
requires no manual cookie export or environment-variable setup.
On serverless hosts, use a Node.js runtime and stream() to pipe audio without ffmpeg. Use cacheDir: false
or a writable cache directory. Merged video downloads need ffmpeg and writable temporary storage.
Sessions can expire and networks can be blocked. Run tubepull doctor if playback fails; custom cookies, proxies
and signed-out mode are covered in the API reference
and Troubleshooting.
Documentation
| Document | What's in it |
| --------------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
| API reference | TubePull options, methods, events, types, errors, custom engines |
| CLI reference | Modes, every flag, exit codes, environment variables |
| Troubleshooting | Bot checks, rate limits, 403s, ffmpeg, containers, access errors |
| Examples | ESM, CommonJS and TypeScript (playlist with concurrency) |
| Changelog | What changed in each release |
Legal
[!WARNING] Use tubepull only for content you own, public-domain or Creative Commons material, or content you have permission to download. Downloading other content may violate YouTube's Terms of Service and copyright law where you live. tubepull does not circumvent DRM and is not affiliated with, endorsed by, or sponsored by YouTube or Google.
tubepull is MIT licensed. The ffmpeg binaries that ffmpeg-static downloads are GPL-licensed builds, and
ffmpeg-static itself is GPL-3.0-or-later. It is installed as a separate (optional) dependency, and no ffmpeg binary
is shipped inside the tubepull package. To use your own LGPL or system build, set TUBEPULL_FFMPEG_PATH.
