c6c8030907
* Add complete Spanish translation (README.es.md) * Restructure English README for clarity and conciseness * Filter out YouTube Shorts from channel video listings (sort=4) * Add fallback for video count using playlist metadata when API returns zero * Add get_playlist_metadata() to fetch metadata without full video list * Add is_short() utility to detect YouTube Shorts by duration, badges, and type * Export is_short from yt_data_extract for use across modules
yt-local
A local YouTube client that runs on your machine. No ads, no JavaScript, with Tor support.
Features • Installation • Usage • Tor • Development
What is it?
yt-local is a local web server that acts as a proxy between your browser and YouTube. Pages load fast, without ads or tracking. Requests can optionally go through Tor.
It doesn't use the YouTube API. It makes the same requests the normal website would, minus all the rest.
Features
- Anonymous browsing with optional Tor
- No ads or JavaScript required
- Three themes: light, gray, dark
- Local playlists (videos aren't lost when YouTube removes them)
- Subscription system independent from YouTube
- Subtitle support
- SponsorBlock segments skipped automatically
- Qualities from 144p to 2160p with HLS support
- Video download (disabled by default)
- Comments load instantly, no lazy-loading
Installation
Linux / macOS
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
python server.py
Windows
Download the zip from Releases and run run.bat.
With Make
make install # Dependencies
make dev # Server
make test # Tests
make help # All commands
Usage
The server starts at http://localhost:9010/
To watch a video, prefix the YouTube URL:
http://localhost:9010/https://www.youtube.com/watch?v=VIDEO_ID
Redirector
You can use a browser extension like Redirector to redirect YouTube automatically:
| Field | Value |
|---|---|
| Pattern | `^(https?://(?:[a-zA-Z0-9_-]*.)?(?:youtube.com |
| Redirect to | http://localhost:9010/$1 |
| Mode | Regular expression |
Enable "Iframes" in advanced options so embedded videos work too.
Portable mode
Create an empty settings.txt file in the main directory. All settings and data will be stored there instead of ~/.yt-local.
Tor
Quick option: Tor Browser
Open Tor Browser and leave it running. In yt-local settings set "Route Tor" to "On, except video".
Standalone Tor
Debian/Ubuntu:
sudo apt install tor
sudo systemctl start tor
Change the Tor port to 9050 in settings.
Windows:
Create a shortcut with: tor.exe SOCKSPort 9150 ControlPort 9151
Video routing through Tor
Set "Route Tor" to "On, including video". It's slower and consumes Tor bandwidth — consider donating to Tor nodes.
Import subscriptions
- Go to Google Takeout
- Select only "subscriptions" and download the CSV
- In yt-local, import the file from the subscriptions manager
Supported formats: Google Takeout CSV, NewPipe JSON, OPML, and old Google Takeout JSON.
Development
yt-local/
├── server.py # Entry point, WSGI server
├── settings.py # Configuration management
├── youtube/
│ ├── util.py # Utility functions, Tor routing
│ ├── watch.py # Video page
│ ├── channel.py # Channel pages
│ ├── search.py # Search
│ ├── subscriptions.py # Subscriptions (SQLite)
│ ├── local_playlist.py # Local playlists
│ ├── yt_data_extract/ # YouTube JSON parser
│ └── ...
├── tests/ # Tests with pytest
└── docs/HACKING.md # Development guide
Useful commands
make test # Run tests
make lint # Check style
make i18n-extract # Extract strings
make i18n-init LANG_CODE=fr # New language
make i18n-compile # Compile translations
Python 3.8+ required. Code follows PEP 8. Commit messages should be descriptive.
Compatibility Notes
- Python 3.8+: Minimum required version
- HLS: Experimental streaming support for multi-audio videos
- Channels with limitations: Some channels return few videos per response. This is YouTube behavior, not yt-local. The project uses YouTube's internal API (innertube), not the public YouTube API.
License
GNU AGPLv3 or later. See LICENSE.
Similar projects
- invidious Similar to this project, but also allows it to be hosted as a server to serve many users
- Yotter Similar to this project and to invidious. Also supports Twitter
- FreeTube (Similar to this project, but is an electron app outside the browser)
- youtube-local first project on which yt-local is based
- NewPipe (app for android)
- mps-youtube (terminal-only program)
- youtube-viewer
- smtube
- Minitube, github here
- toogles (only embeds videos, doesn't use mp4)
- YTLibre only extract video
- youtube-dl, which this project was based off