npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

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.

Readme


npx tubepull https://youtu.be/aqz-KE-bpKQ

Features

[!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                          # diagnostics

Run 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.