Hey there 👋
This project is currently on hold while I focus on my exams.
Development will resume soon
Thanks for your patience!
~ @krishnassh
A simple terminal YouTube client for searching and watching videos using yt-dlp and mpv.
- Overview
- Features
- Who is this Project for?
- Prerequisites
- Installation
- Usage
- Configuration
- Troubleshooting
- FAQ
- Roadmap
- Star History
- Contributing
GopherTube is a terminal-based YouTube client. It scrapes and parses the youtube website to search YouTube and uses mpv to play videos. The UI is built with Go and uses fzf, and is keyboard-driven.
Screenshots
searching for videos
Demo Video
Watch the demo video here
- Fast YouTube search (scrapes YouTube directly, no API key needed)
- Play videos with mpv
- Minimal terminal UI (fzf)
- Keyboard navigation (arrows, Enter, Tab, Esc)
- TOML config
- Download videos with quality selection (yt-dlp)
- Downloads menu: browse and play downloaded videos
- Thumbnail preview in downloads menu
- This Project is for everyone who enjoys Terminal apps
- For Everyone Who respects thier Privacy and Freedom
- Anyone who wants to watch videos while using as few system resources as possible — for example, if you have an older or low-spec machine that struggles to run YouTube in a full web browser, this project can help you cut down on resource usage.
- Go 1.21+
- mpv (media player)
- fzf (fuzzy finder)
- chafa (terminal image preview)
- yt-dlp (YouTube downloader)
Install dependencies:
# Ubuntu/Debian
sudo apt install mpv fzf chafa
pip install -U yt-dlp
# macOS
brew install mpv fzf chafa yt-dlp
# Arch Linux (Aur is having shasum issues install it from the script)
yay -S gophertube yt-dlp Quick Install (One-liner):
curl -sSL https://raw.githubusercontent.com/KrishnaSSH/GopherTube/main/install.sh | bash# Arch Linux (AUR)
yay -S gophertube
# macOS (Homebrew) - coming soon
# brew tap KrishnaSSH/tap
# brew install gophertubeManual Installation:
git clone https://github.com/KrishnaSSH/GopherTube.git
cd GopherTube
go build -o gophertube
./gophertube- Start the app:
./gophertube - Type a search and press Enter (or press Escape to exit)
- Use ↑/↓ to move, Enter to play, Tab to load more, Esc to go back to search
- Thumbnails and video info are shown in the preview
- mpv opens to play the selected video
| Key | Action |
|---|---|
| Enter | Search / Play video |
| ↑/↓ | Navigate video list |
| Tab | Load more videos |
| Esc | Go back / Quit |
Create ~/.config/gophertube/gophertube.toml:
search_limit = 30
quality = "1080p" # default: 1080p (options: 1080p, 720p, 480p, 360p, Audio)
downloads_path = "/home/$USER/Videos/GopherTube" # where to save downloads| Key | Type | Default | Description |
|---|---|---|---|
| search_limit | int | 30 | Max results to fetch per page/load more. |
| quality | string | "1080p" | Preferred quality or Audio for audio-only. |
| downloads_path | string | "$HOME/Videos/GopherTube" | Directory to save downloads. |
- fzf not found: install fzf (see Prerequisites) and ensure it’s in PATH.
- mpv not launching: verify mpv is installed and accessible from terminal.
- No thumbnails: ensure
chafais installed; some terminals may not support images. - yt-dlp errors: update yt-dlp to the latest version.
- Does this use the YouTube API? No, it scrapes the website. No API key required.
- Can I play audio only? Yes. Choose "Listen" or set quality to
Audio. - Where are files downloaded? See
downloads_pathin config.
- Configurable keybindings
- Optional inline player controls
- Windows support (best effort)
- CI and release artifacts for more platforms
If you find this project useful, consider supporting its development with crypto:
 |
bc1q78ymwmf33vr33ly8rpej7cqvr6cljjcdjf3g6p |
 |
ltc1qsfp4mdwwk3nppj278ayphqmkyf90xvysxp3des |
 |
0x6f786f482DDa360679791D90B7C8337655dC2199 |
PRs and issues welcome.
See CONTRIBUTING.md for guidelines.