Invidious: a Crystal front end for YouTube that asks for no official API
Invidious is an alternative front-end to YouTube
At a glance
- What is it?
- Twenty-four thousand stars of alternative front end, from a single-instance quick start to a Makefile build that keeps debug symbols on by default.
- Who is it for?
- Invidious is best understood as a piece of infrastructure with a user interface attached, not as a browser or a downloader. What it does well is refuse the official API, keep the interface usable with JavaScript turned off, and make hosting a public instance a documented operation rather than a folklore one.
- Can I use it commercially?
- Yes, with strict conditions. AGPL-3.0 is a network copyleft licence: if people use a modified version over a network, for example as a hosted service, you must offer them its source code under the same licence.
- Is it still maintained?
- Yes. The repository last received commits 1 day ago.
- What is it written in?
- Mainly Crystal, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 21, 2026, and from our analysis. They are not legal advice.
Star history
- iv-org/invidious26,108 ★ · +751
| Repository | 2026-10-12 | 2026-11-21 |
|---|---|---|
| iv-org/invidious | 25.4k | 26.1k |
751 Stars in the last 40 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
The technical feature that matters most is the absence of an API
The feature list has a user half and a technical half, and the technical half is short on purpose. It lists embedded video support, a developer API, and two negatives: it does not use official YouTube APIs, and it carries no Contributor License Agreement. Those two lines are the project.
Every feature above them is downstream of that choice. No ads and no tracking follow from not participating in the ad system. Subscriptions independent from Google follow from not being signed in to Google. Notifications for every subscribed channel follow from holding the subscription list yourself instead of asking an account for a feed. The readme is blunt about the cost, in its own liability section, which disclaims responsibility for how the tool is used and points at the applicable regulations rather than pretending the question does not exist.
The user feature list also includes audio-only mode with background play on mobile, support for YouTube comments, and a claim that no JavaScript is required. That last one is the most architecturally interesting item on the list. Rendering a video page, a preferences page and a subscriptions page without client-side scripting means the server does the work, which is why Crystal and a server-side approach make sense here.
Data portability is treated as a first-class feature rather than an afterthought. Subscriptions import from YouTube, NewPipe and FreeTube, and export to NewPipe and FreeTube. Watch history imports from YouTube and NewPipe. That set of names is a fairly precise description of who this is for: people who arrived from a mobile client, or who want to leave with their list intact.
Three ways to use it, and only one of them involves you running anything
The quick start is two lines and the second one is a link to external documentation. As a user, you pick a public instance from a maintained list and start watching. As a host, you follow the installation instructions on the documentation site. There is no third path offered, and the distinction matters because the two have completely different costs.
The readme does not try to hide where the real content lives. Documentation is at docs.invidious.io, its source is in a separate repository, and the documentation carries an applications page listing other projects and browser extensions that work with Invidious. The recommended extension is one that rewrites YouTube URLs to whichever instance you use and replaces embedded YouTube players on other sites, which is the practical answer to the problem that a front end cannot fix a link someone else already published.
Communication is spread across Matrix, Libera IRC, a Mastodon account and email. The presence of four channels rather than one is a reasonable signal about how much traffic a project of this size carries.
Contributing is documented in the ordinary GitHub way, with a fork, a feature branch, and a pull request, plus a translation workflow through Weblate that does not require an account but recommends one for regular contributors. The repository tree includes a locales directory and a translation status badge, which is the practical measure of how many people the interface actually reaches.
Reading the compose file as a description of the real dependencies
The repository's own compose file opens with a warning that it is for development, builds from the locally cloned source, and points anyone deploying to the compose file in the installation documentation. That warning is worth taking seriously, because the file it guards reveals the actual requirements: a Crystal web application, a PostgreSQL 14 service, and a schema applied on first boot.
The service definition waits for the database to report healthy before starting, and configures a healthcheck against the statistics endpoint rather than the front page:
healthcheck:
test: wget -nv --tries=1 --spider http://127.0.0.1:3000/api/v1/stats || exit 1
interval: 30s
timeout: 5s
retries: 2Two details in there are worth pausing on. The port binding is to the loopback interface only, which is the correct default for a compose file and also a reminder that putting this behind a reverse proxy is the expected production shape. And the configuration block is embedded as an environment variable pointing at a commented example file, with the hmac key left as a placeholder value that obviously needs replacing before anything faces the internet.
The database service is deliberately plain: an official PostgreSQL image, a named volume for the data directory, the SQL directory mounted for schema, and the initialization script mounted into the entrypoint directory. Readiness uses the standard client utility against the configured user and database name, and the application waits on that condition before it starts.
A Makefile that tells you what the binary needs
The build is small enough to describe in a Makefile, which is a good sign. There are two compilation switches, release and static, and two behaviour switches, one that produces an API-only build and one that skips the version check. Debug symbols are on by default and can be turned off with a single variable, which is the opposite of what most projects do and turns out to matter for running a public instance.
The library fetch and the build are two targets, and the build itself is a single Crystal invocation with progress and statistics output:
get-libs:
shards install --production
invidious: get-libs
crystal build src/invidious.cr $(FLAGS) --progress --stats --error-traceThere is also a verify target that compiles without generating a binary, which the file describes as useful for searching for errors. The help text at the bottom enumerates the targets for anyone who lands in the repository without knowing the conventions.
The practical consequence for an operator is that you can build a static binary with debug symbols and hand it to whatever supervisor you already run, without adopting the container at all. The container is a convenience, not a requirement, and the file structure supports that: a docker directory, a kubernetes directory, a systemd unit file and a nix directory all sit side by side at the top level.
What the recent releases say about running a public instance
The three most recent releases are v2.20261103.0 (2026-11-03), v2.20261022.0 (2026-10-22) and v2.20260804.1 (2026-08-05), and the version numbers encode the release date. For what changed in each, read CHANGELOG.md at the top of the repository, which sits next to CHANGELOG_legacy.md.
For an operator the build-time switches matter more than any single release. The Makefile can produce an API-only build with API_ONLY=1, skip the version check with SKIP_VERSION_CHECK=1, and keeps debug symbols on by default unless NO_DBG_SYMBOLS=1 is set, which keeps stack traces available when a public instance fails.
Reading the repository as evidence of where the project is heading
The tree is more informative than the readme about current priorities. There is a dependency manifest and lock file for Crystal packages, a spec directory for tests, a mocks directory, and separate docker and kubernetes deployment assets. Two entries stand out. There is an AI policy document, AI_POLICY.md, at the top level.
There is also a changelog and a legacy changelog side by side.
The scale is worth stating plainly. Twenty-four thousand six hundred stars, two thousand seven hundred and sixty-four forks, four hundred and ninety open issues, and a last push on 2026-11-02, with the latest release, v2.20261103.0, on 2026-11-03. The AGPL-3.0 license matters here in a specific way: an instance operator who modifies and serves the code over a network is distributing it under the same terms, which is exactly the outcome that license was chosen to produce.
None of this makes the project easy to run. It scrapes a site that changes without notice, so breakage is a scheduling question rather than an exception. The honest reading is that an instance operator is taking on a recurring maintenance commitment in exchange for a front end that does not track its users.
Editorial conclusion
Invidious is best understood as a piece of infrastructure with a user interface attached, not as a browser or a downloader. What it does well is refuse the official API, keep the interface usable with JavaScript turned off, and make hosting a public instance a documented operation rather than a folklore one. If you want to read one file to understand where the current work is, CHANGELOG.md is more informative than the readme. Start from the instances list as a user, and from the installation documentation rather than the repository's own compose file if you intend to run one.
Frequently asked questions
What does invidious do?
It serves an alternative web front end for YouTube. Pages are rendered on the server, so watching, browsing and managing subscriptions work without client-side scripting, and the project states that it does not use the official YouTube APIs. Subscriptions and watch history are held independently of a Google account.
Do I need to host Invidious myself to use it?
No. The quick start points you at a maintained list of public instances and that is the whole procedure. Hosting is a separate path described in the installation documentation, and it is the expensive one, since an operator inherits the job of reacting when YouTube changes its pages.
Does Invidious let you import subscriptions from other services?
Yes, and the list is specific: subscriptions import from YouTube, NewPipe and FreeTube, and export to NewPipe and FreeTube. Watch history imports from YouTube and NewPipe, and Invidious user data itself can be exported and imported.
What does an instance operator need to run Invidious?
A Crystal application and PostgreSQL. The repository's compose file, which its own header says is for development, configures both, waits for the database healthcheck before starting the application, and binds the port to loopback so a reverse proxy can sit in front.
Does the Makefile build Invidious with debug symbols?
Yes, by default. NO_DBG_SYMBOLS defaults to 0, so the build passes --debug; setting NO_DBG_SYMBOLS=1 passes --no-debug instead. Keeping symbols helps an operator investigate a crash after the fact.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/iv-org-invidious)Star history chart for your README
[](https://hysenlabs.com/projects/iv-org-invidious)Was this useful?