yt-stash is a cross-platform (Linux, macOS, Windows) command-line downloader for single videos, several videos and whole playlists, including members-only and private videos. It is a thin, heavily tested workflow layer on top of yt-dlp, the best-maintained YouTube extraction library, so it keeps working when YouTube changes.

Features

• Every quality: detects all resolutions (144p … 8K, high frame rate, HDR) and lets you choose once for a whole batch. Defaults to 1080p, or the highest available.
• Videos and playlists: one or many links, a text file of links, or every video of a playlist.
• Parallel downloads: several videos at once, plus parallel fragments per video.
• Members-only, private and age-restricted videos through your browser's signed-in session, a cookies.txt file, or cookies pasted for one run (never saved).
• Audio only (m4a, mp3, opus) and subtitles (save or embed, any language, auto-generated too).
• Resume and skip: interrupted downloads continue; files you already have are skipped; transient errors and rate limits are retried automatically.
• Interactive or scriptable: arrow-key menus with an explanation under every entry, or --yes plus flags for cron and CI, with documented exit codes.
• English and Turkish interface.

Quickstart

# 1. Install (details for every system: docs/installation.md)
pipx install yt-stash

# 2. Open the interactive menu
yt-stash

# 3. Or download straight away
yt-stash video URL                    # asks for quality and folder
yt-stash video URL -q 720 -o ~/Videos                            # no questions
yt-stash video URL1 URL2 URL3 -j 3                               # three at once
yt-stash playlist "https://www.youtube.com/playlist?list=PL..."  # a whole playlist
yt-stash video URL -a mp3                                        # audio only
yt-stash video URL --subs en,tr --embed-subs                     # with subtitles
yt-stash video URL --cookies-from-browser firefox                # members-only video

$ yt-stash
yt-stash 1.0.0  Download YouTube videos and playlists

▶ What do you want to do? (↑↓ to move, Enter to choose)
 ❯ Download videos
   Download a playlist
   Download links from a text file
   Show available qualities

   Sign-in (off)
   Language (English)
   Check setup
   Command-line options
   Quit
  Description: Paste one or more video links.

Installation

yt-stash needs Python 3.10+; install ffmpeg and deno too for full quality.

Check it: yt-stash --version. If downloads suddenly fail, update first: pipx upgrade yt-stash.

Documentation

Quick reference: yt-stash --help, yt-stash video --help, yt-stash playlist --help.

Exit codes: 0 everything downloaded or already present · 1 at least one video failed · 2 invalid usage · 130 interrupted with Ctrl+C.

Getting help

• Question or idea? Open a Discussion.
• Found a bug? Open an issue; the form asks for the details that make it fixable.
• Security problem? Please don't open an issue; follow the security policy.

yt-stash is maintained by one volunteer in their spare time. Replies may take a few days; thank you for your patience.

Contributing

Contributions of every size are welcome: bug reports, documentation fixes, translations and code. Read CONTRIBUTING.md first; issues labelled good first issue are a good place to start. By taking part you agree to the Code of Conduct.

git clone https://github.com/ilkerkeklik01/yt-stash.git && cd yt-stash
python -m venv .venv && source .venv/bin/activate     # Windows: .venv\Scripts\activate
pip install -e ".[dev]"
pytest && ruff check . && ruff format --check .

Legal

yt-stash is released under the MIT License. It is an independent project, not affiliated with or endorsed by YouTube or Google. Only download content you have the right to download, and respect YouTube's Terms of Service and the creators' rights. You are responsible for how you use this tool.

yt-stash does not remove DRM, bypass paywalls or circumvent access controls of its own; it drives yt-dlp, and sign-in works only through cookies you already have. It collects no data and has no telemetry: the only thing it stores is the language you choose, in a local settings file. Everything that goes over the network is done by yt-dlp, to YouTube and its video servers.

yt-stash builds on yt-dlp (Unlicense), rich (MIT), questionary (MIT) and prompt_toolkit (BSD-3-Clause). Thank you to their authors.