yt-x

May 7, 2026 · View on GitHub

GitHub Issues or Pull Requests GitHub License GitHub file size in bytes GitHub Release GitHub commit activity

Browse YouTube from your terminal. Plus other sites yt-dlp supports.

yt-x-github-demo.webm

Full Demo

yt-x-full-github-demo.webm

Riced

Features

Interactive Menu: Text-based UI using fzf or rofi for seamless navigation.
YouTube-Specific Menus: Access your feed, trending videos, playlists, watch later, subscriptions feed, liked videos, clips.
Playback Support: Play videos and audio via mpv, vlc, or tplay.
Search and filter Functionality: Search for videos, channels and playlists directly.
Channel Exploration: Explore channels, including their videos, streams, podcasts, shorts, and playlists.
Saved Channels: Bookmark your favorite channels for quick access, with support for importing existing subscriptions.
Saved Videos: Save videos to watch later.
Mixes: Generate and explore YouTube song mixes.
Yt-x Shell: Run custom yt-dlp and mpv commands for downloading and viewing videos and playlists
Custom Playlists: Save playlists for easier access.
Download Management: Download videos, audio, and playlists using yt-dlp.
History & Recents: Track your recent videos and search history.
Configuration Management: Customize and manage configurations for yt-x, mpv and yt-dlp with ease.
Extensions: Extend yt-x with your own custom ui and preview logic allowing more precise coverage of other sites that yt-dlp supports
Custom Commands: Basically a simple way to achieve the same thing with extensions. A custom command is just a yt-dlp command that loads a playlist or playlist like json.
Multi language support: through lang extensions
Muli site support: though site extensions
themable: rice yt-x to your hearts content and make it yours through theme extensions and the config with nice defualts (tokyo night)
intuitive code architecture: an easy to understand to codebase with intuitive state management. yes even if its over 3.5k line lol
Miscellaneous Features:
- Shell completions for bash, zsh, and fish.
- Desktop entry generation for easy access.

📥 Installation

`On NixOS, you can install packages using two main methods:`

Imperative/Direct installation:

nix profile install github:Benexl/yt-x

Declarative/Config-based:

2.1 Add the following to your flake.nix:

inputs = {
  nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
  yt-x = {
    url = "github:Benexl/yt-x";
    inputs.nixpkgs.follows = "nixpkgs";
  };
  ...
}

2.2 Then, add Yt-x to your packages:

For system wide installation in configuration.nix

environment.systemPackages = with pkgs; [
  inputs.yt-x.packages."${system}".default
];

For user level installation in home.nix

home.packages = with pkgs; [
  inputs.yt-x.packages."${system}".default
];

Arch Linux

You can install yt-x from the Arch Linux AUR repository.

To install, use your preferred package manager paru or yay:

# for paru users
paru -S yt-x-git

# for yay users
yay -S yt-x-git

Cross-platform

# NOTE: ~/.local/bin should exist and be in path for this to work
curl -sL "https://raw.githubusercontent.com/Benexl/yt-x/refs/heads/master/yt-x" -o ~/.local/bin/yt-x && chmod +x ~/.local/bin/yt-x

To uninstall simply remove the file:

rm ~/.local/bin/yt-x

Dependencies

Required

jq - JSON parsing.
curl - Download preview images.
yt-dlp - Fetch YouTube data.
fzf - Main UI navigation.
mpv - Video and audio playback.
ffmpeg - Proper HLS stream downloading.
sh - Script interpreter (any posix compliant shell).
nerdfont - for the icons

Optional

gum - Enhanced UI (highly recommended).
rofi - Alternate UI.
tplay - Terminal-based ASCII video player (optional, for individual video playback).
terminal image viewer:
- chafa - Cross-terminal image rendering (recommended).
- icat - recommended for kitty terminal and ghostty
- imgcat
terminal with image rendering support:
- kitty - currently has the best image rendering capabilities (recommended)
- wezterm
- ghostty

Usage

# Launch the UI
yt-x

# Edit configuration
yt-x -e

# load an extension
# extensions are located at ~/.config/yt-x/extensions
# the extension name is the name of a file in the extensions folder
yt-x -x <extension-name>

# Specify player at runtime
yt-x --player <mpv/vlc/tplay>

# Set selector at runtime
yt-x -s <fzf/rofi>

# Specify Rofi theme path
yt-x --rofi-theme <path>

# Enable/disable preview
yt-x --preview / yt-x --no-preview

# Print desktop entry
yt-x -E

# Print shell completions
yt-x completions --bash
yt-x completions --zsh
yt-x completions --fish

# Update the script
yt-x --update

# Display help
yt-x --help

Tips

Enabling Imports of Subscriptions & Private Playlists

Set your preferred browser in the configuration file:

PREFERRED_BROWSER: firefox

To enable mpv to access private playlists and videos, add something like this to mpv.conf (you can also use the ui to edit mpv.conf):

ytdl-raw-options=cookies-from-browser=firefox

# --- bonus mpv tips ---

# define the quality for mpv to use
ytdl-format="bestvideo[vcodec^=avc1][height=1080]+bestaudio/best[vcodec^=avc1][height=1080]/bestvideo[vcodec^=avc1][height=720]+bestaudio/best[vcodec^=avc1][height=720]/best"

# defines where screenshots will be saved
screenshot-directory=~/Pictures/mpv_screenshots/

# enable hardware accelaration
hwdec=auto
vo=gpu

# for subs something like this
slang=en,eng,enUS,en-US
sub-auto=fuzzy
ytdl-raw-options=ignore-config=,sub-lang="en,eng,enUS,en-US",write-sub=,write-auto-sub=

To customise download options with yt-dlp you can add something like this to yt-dlp.conf (you can also use the ui to edit yt-dlp.conf)

-f bestvideo[vcodec^=avc1][height=1080]+bestaudio/best[vcodec^=avc1][height=1080]/bestvideo[vcodec^=avc1][height=720]+bestaudio/best[vcodec^=avc1][height=720]/best
--embed-chapters
--sponsorblock-mark all
--embed-metadata
--embed-thumbnail
--add-metadata
--embed-subs
--sub-lang en
--merge-output-format mkv

Tip

I also recommend setting up a po token. read more here https://github.com/yt-dlp/yt-dlp/wiki/PO-Token-Guide

Recommended plugin to help you with that https://github.com/Brainicism/bgutil-ytdlp-pot-provider

For additional enhancements, consider:

uosc for a modern mpv UI.
thumbfast for thumbnail timeline previews.

Fixing "cannot decrypt cookies" error synchronizing subscriptions

If you find this error while trying to synchronize your YouTube subscriptions ("Miscellaneous" > "Sync YouTube Subscriptions" option in yt-x):

Syncing subscriptions... WARNING: cannot decrypt v11 cookies: no key found WARNING: [youtube:tab] unable to extract yt initial data; please report this issue on https://github.com/yt-dlp/yt-dlp/issues?q= , filling out the appropriate issue template. Confirm you are on the latest version using yt-dlp -U WARNING: [youtube:tab] Incomplete yt initial data received. Retrying (1/3)...

You can fix it by setting the yt-dlp --cookies-from-browser option in your yt-x.conf file ("Edit Config." option in yt-x) to match your browser and profile. For example, if you use Brave's default profile with GNOME Keyring, configure this PREFERRED_BROWSER value in your yt-x.conf file:

PREFERRED_BROWSER: brave+gnomekeyring:Default

To find the correct PREFERRED_BROWSER value for your browser and profile, use the yt-dlp --cookies-from-browser option in terminal. In the previous example, with Brave and GNOME Keyring, the following command should correctly extract your Brave browsers cookies:

yt-dlp \
  --cookies-from-browser "brave+gnomekeyring:Default" \
  --skip-download \
  --flat-playlist \
  "https://www.youtube.com/feed/channels" \

In your tests, replace brave+gnomekeyring:Default with your browser and profile. For more details, refer to the yt-dlp documentation.

Note

This is not an issue with yt-x itself, but rather with yt-dlp's ability to access browser cookies.

Custom Playlists

Define custom playlists by editing ~/.config/yt-x/custom_playlists.json (or use the UI):

[
  {
    "name": "<playlist name>",
    "playlistUrl": "https://www.youtube.com/playlist?list=<playlist-id>",
    "playlistWatchUrl": "https://www.youtube.com/watch?list=<playlist-id>"
  }
]

Theming

To change the default colorscheme, set YT_X_FZF_OPTS env var and give it custom fzf opts.

eg. (.bashrc)

#yt-x
export YT_X_FZF_OPTS=$FZF_DEFAULT_OPTS'
--color=fg:#e0def4,fg+:#e0def4,bg:#232136,bg+:#44415a
--color=hl:#3e8fb0,hl+:#9ccfd8,info:#f6c177,marker:#3e8fb0
--color=prompt:#eb6f92,spinner:#c4a7e7,pointer:#c4a7e7,header:#3e8fb0
--color=border:#44415a,label:#ea9a97,query:#f6c177
--border="rounded" --border-label="" --preview-window="border-rounded" --prompt="> "
--marker=">" --pointer="◆" --separator="─" --scrollbar="│"'

Extended search

While searching, you can prefix your query with a :command to filter your search request: :<command> your_query. Only one command can be used per query.

List of commands

Command	Description
`:live`	Show only live streams
`:today`	Videos uploaded today
`:week`	Videos uploaded this week
`:month`	Videos uploaded this month
`:year`	Videos uploaded this year
`:short`	Short videos (< 4 minutes)
`:long`	Long videos (> 4 minutes)
`:playlist`	Show playlists only
`:movie`	Movies
`:hd`	HD videos
`:4k`	4K videos
`:hdr`	HDR videos
`:subtitles`	Videos with subtitles/CC
`:360`	360° videos
`:vr`	VR180 videos
`:3d`	3D videos
`:local`	Videos filtered by location

Sorting Options

Command	Description
`:views`	Sort results by view count
`:rating`	Sort results by rating
`:newest`	Sort results by upload date