youtube-local: a YouTube front end that runs on your own machine

The privacy argument, and its assumption

youtube-local is a browser-based client written in Python for watching YouTube anonymously and without the lag of the slow page used by YouTube. The primary feature is that all requests are routed through Tor, except for the video file at googlevideo.com.

That exception is the crux, and the README is explicit about the reasoning behind it. The assumption is that Google will not put the effort into incorporating the video file requests into their tracking, since it is not worth pursuing the incredibly small number of users who care about privacy. Video routing through Tor is also provided as an option for people who want to close that gap.

The comparison the README draws is with HookTube, which it marks as defunct, and with Invidious. The difference it emphasises is trust: with those projects you have to trust a third party to respect your privacy, whereas here the server runs on your own machine.

The cost is stated just as plainly. Tor has high latency, so this will not be as fast network-wise as regular YouTube. However, using Tor is optional, and when not routing through Tor, video pages may load faster than they do with YouTube's page depending on your browser.

So the tool has two distinct modes rather than one. Run it locally without Tor and you get a faster, simpler front end. Run it with Tor and you get anonymity at the price of latency.

No API keys, and the request model

The API is not used, so no keys or anything are needed, and the project makes the same requests as the YouTube web page itself.

That single sentence explains both the appeal and the fragility. Because it scrapes the same endpoints a browser uses, there is no developer API to register for, no quota to manage and no key to leak, and the pages it renders are the pages YouTube actually serves. The cost is that the project depends on undocumented behaviour that Google can change at any time, and a change to the web page can break the client until the project adapts.

The Python implementation uses Flask for the web layer, with gevent for concurrency, and the repository holds the application code in a youtube package with the server entry point at the root and the configuration in a settings module.

There is a hacker's file at the root describing the project internals, a tests directory with a pytest configuration, a release generation script, and the requirements kept in four variants: the main locked file, a bare file, a development file and one for Python 3.7.

The locked requirements file is worth a mention, because it is generated with hashes by the modern Python package tooling, with the header comment recording the exact command that produced it. That is a supply chain practice worth copying: the lock file is reproducible and its provenance is written into the file itself.

Pages, playlists and the two themes

The feature list starts with the standard YouTube pages: search, channels and playlists, and adds anonymity from Google's tracking by routing through Tor.

Local playlists are the feature that goes furthest from the original site, and the README explains why with two specific problems. Playlists on YouTube are datamined, and videos frequently get deleted by YouTube and lost from the playlist, which makes it very difficult to find a reupload because the title of the deleted video is not displayed.

So the local playlist keeps your own copy of the entries, which means a video that vanishes from YouTube does not vanish from your list.

Around that there are three themes, light, gray and dark, subtitles, the ability to download videos or their audio, no ads, the ability to view comments, and no requirement for JavaScript in the browser. There is a theater and non-theater mode, a video transcript, custom video speeds, and support for all the available video qualities from 144p through 2160p.

The no JavaScript requirement is unusual for a modern web front end and is the direct consequence of the server-side design: the server renders the page, so the browser receives finished HTML rather than a client application that assembles it.

One optional integration is called out by name: sponsored segments can be skipped using the SponsorBlock API.

Subscriptions that do not depend on YouTube

Subscriptions that are independent from YouTube are a separate feature list within the README, and the details explain how the feature actually works.

Subscriptions can be imported from YouTube. They work by checking channels individually, and they can be set to check channels automatically. For efficiency of requests, the frequency of checking is based on how quickly a channel posts videos, which is a sensible way to spend as few requests as possible on channels that are quiet.

Channels can be muted, which the README calls a way to soft unsubscribe. Muted channels are not checked automatically and not checked with the check all button, and videos from them are hidden. That is a meaningfully different model from YouTube's own subscription list, where unsubscribing is a single state and a channel that posts often will always cost you requests.

Subscriptions can also be tagged, which serves two purposes: organising them, and checking specific tags.

The set of planned features for this area shows where the project is heading and, by implication, what it does not do yet. There is no way to mark what has been watched, no filtering of videos by keywords in the title or description, no deletion of old entries and thumbnails, and no way to put videos from subscriptions or local playlists into the related videos.

The wider planned list also includes the ability to delete playlists, auto-saving of local playlist videos, importing a YouTube playlist into a local playlist, rearranging items of a local playlist, a featured channels page, channel comments, and support for more video sites such as Vimeo, Dailymotion and LBRY.

Speed, comments and the settings that control them

The README describes the performance work in terms of what it removes rather than what it adds.

A fast page means no distracting or slow layout rearrangement, and no lazy loading of comments, so they are ready instantly. The lazy loading is the point, because on the real site the comment list is fetched after the page is interactive, and that fetch is both slow and a tracking vector.

Comments and related videos are controlled by a setting with three states: shown by default with a click to hide, hidden by default with a click to show, and never shown. Giving the reader that choice rather than a single default is the kind of detail that separates a tool built by someone who uses it daily from one that guesses.

The remaining performance related features are custom video speeds, the transcript, and the quality range from 144p to 2160p. The planned list records that qualities other than 360p and 720p are produced by muxing video and audio, and that corrected m4a downloads are still outstanding, which is a hint that the download path is the least polished part of the project.

The checklist also shows what has already landed, including information about the video such as geographic regions and the region of the Tor exit node, an indication of whether comments are disabled, a count of the comments, and an automatic Tor circuit change when blocked, which is the failure mode Tor users know well.

Installing and running it

On Windows the instruction is to download the zip under the releases page and unzip it anywhere you choose. The run script is a batch file, and to start it with the system you right click it and create a shortcut, then move that shortcut into the Startup folder, which you open with the Windows key and R and the shell startup command.

On Linux and macOS you download the tarball, extract it, and run four commands in the directory.

python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
python server.py

The README notes you may need python3 and pip3 instead, depending on your distribution, and explains how to get pip if it is missing, including the detail that on Debian the package is python3-pip rather than python-pip.

Two community packages are listed as alternatives: an Arch User Repository package and a COPR package for the RPM based distributions, both maintained by the same person.

Once running, you reach YouTube URLs by prefixing them with the local address, so a watch URL becomes a local one, and the README describes using a browser addon such as Redirector to do that automatically, giving the include pattern that matches YouTube, youtu.be and the no-cookie domain, and the redirect pattern that sends them to the local server.

There is a Mac specific note as well. If you installed Python from the python.org installer you need to have run the install certificates command in the applications directory, otherwise you get a certificate verification error about not being able to get the local issuer certificate.

Dependencies, versions and what to check

The dependency list is short and tells you what the application actually needs.

The web framework is Flask, gevent provides the concurrency, Brotli handles the compressed responses that YouTube's pages use, PySocks and urllib3 cover the proxying that Tor routing requires, defusedxml parses the XML in the responses, cachetools provides the caching, and stem is the Tor controller library.

The Python floor is 3.7, and the separate requirements file for that version exists because the newer packages have moved on.

On releases, the tags are v2.8.15 from 2026-08-23, v2.8.14 from 2026-08-21 and v2.8.13 from 2026-06-14, and the last push was on 2026-10-14. The licence is the AGPL version 3, which for a tool that runs on your own machine is a reasonable choice and has one implication worth stating: if you modify it and serve it to others, you owe them the source.

Three checks before you rely on it. That the videos you watch are reachable from your Tor exit node, because the routing model depends on what the exit can see. That the current release works with the YouTube pages of the day, since the project scrapes undocumented endpoints and will break when they change. And that you are comfortable with the download feature being a rough edge, since the planned list still carries corrected m4a downloads as outstanding work.

Editorial conclusion

youtube-local suits someone who watches YouTube through Tor already, or who simply wants a page that loads without the layout rearrangement and ad scripts of the site, and who is willing to run a small local server. It is the wrong choice if you want zero setup, since it needs Python, a dependency tree and a Tor connection, and the wrong choice if you need the features of the real site that the README lists as unimplemented, such as channel comments, playlist editing or support for other video sites. Verify first that the videos you watch are available in your region, since the routing model depends on what the exit node can reach, and check the release notes before upgrading, since the project depends on the undocumented behaviour of the YouTube web pages.

Frequently asked questions

Official sources

1. Issues
2. License: AGPL-3.0
3. README
4. Releases
5. user234683/youtube-local on GitHub