yt-dlp TUI

中文文档

A terminal user interface for yt-dlp built with Textual. It provides format inspection, playlist item selection, download progress, persistent history, resumable interrupted downloads, and independently managed yt-dlp and FFmpeg binaries.

This project is not affiliated with yt-dlp. Please use it only for content you are permitted to download.

Screenshots

Start a download

Inspect a playlist

Track downloads

Configure the download engine

Features

• Inspect video and playlist URLs before downloading.
• Select playlist items before queueing them, while single videos still use format selection.
• Choose from available yt-dlp format IDs.
• Automatically add the best available audio stream to video-only formats and merge with FFmpeg.
• Show active downloads with a text progress bar, speed, ETA, and live yt-dlp output.
• Persist completed, failed, and interrupted tasks in per-user JSON history.
• Resume interrupted tasks with yt-dlp's --continue support.
• Open a completed file, reveal it in the system file manager, or copy its path.
• Install and update yt-dlp independently from the TUI application.
• Install FFmpeg from GitHub on Windows.
• Use an optional HTTP(S) proxy for engine installation, update checks, metadata extraction, and downloads.

Requirements

• Python 3.11 or newer
• uv for development or local installation
• Windows is the primary supported platform at present. FFmpeg auto-install currently targets Windows x64.

Installation

Run with uvx (recommended)

Run the latest published version without installing it permanently:

uvx yt-dlp-tui

From PyPI

pip install yt-dlp-tui
yt-dlp-tui

From source

git clone https://github.com/z4none/yt-dlp-tui.git
cd yt-dlp-tui
uv sync --all-groups
uv run yt-dlp-tui

Quick start

1. Open Settings from the sidebar.
2. Set the default download directory and, if needed, an HTTP(S) proxy.
3. Install yt-dlp from GitHub. The app checks the selected stable or nightly channel in the background and offers an update when one is available.
4. Install FFmpeg from GitHub to merge separate video and audio streams automatically.
5. Open Start, paste a URL, inspect formats, select one, and begin downloading.

Notes on downloads

• A video-only format requires FFmpeg to merge it with audio. The app automatically selects FORMAT_ID+bestaudio/best when appropriate.
• The Downloading page includes raw yt-dlp output. Task logs are also written to the application's per-user data directory.
• Interrupted downloads are marked as failed after restart, but can be resumed from Completed.

Development

uv sync --all-groups
uv run ruff check .
uv run pytest -q
uv run yt-dlp-tui

Build and publish

uv build
uv publish --publish-url https://upload.pypi.org/legacy/

Use a PyPI API token through UV_PUBLISH_TOKEN; never commit publishing credentials.

License

Distributed under the MIT License.