🟡 Intermediate ⚙️ Type: YouTube Front-End / Web App 💸 Free & Open Source (AGPL-3.0) ⭐ 20,400+ GitHub Stars
What is Invidious?
Invidious is an open-source, privacy-respecting alternative front-end for YouTube. It allows you to watch videos, subscribe to channels, and build playlists without ever needing a Google account or being subjected to Google’s tracking algorithms.
Instead of your browser connecting directly to YouTube and loading heavy, ad-ridden tracking scripts, your computer connects to your Invidious server. Invidious then acts as a middleman proxy—fetching the video streams and data from YouTube and serving them to you on a clean, lightweight web interface. It actively bypasses YouTube’s official APIs to protect your digital footprint.
Recently, to combat YouTube’s aggressive blocking of third-party clients, the project introduced Invidious Companion and trusted session generators to seamlessly retrieve video streams without getting your server’s IP address banned.
Who is it for?
- Privacy Advocates who want to watch YouTube content without feeding data into Google’s corporate profiling machine.
- Self-Hosters and Homelabbers looking to spin up their own private, ad-free media portals for their household on a Raspberry Pi or personal server.
- Parents who want to provide their children access to educational YouTube videos without exposing them to targeted advertising or the addictive recommendation algorithm.
- Developers who need a clean, fully documented REST API to pull YouTube video data without dealing with official API quotas or restrictions.
What makes it special?
- Total Privacy — It strips out all Google tracking. Your search queries, watch history, and subscriptions are stored locally on your own PostgreSQL database, not in the cloud.
- 100% Ad-Free with SponsorBlock — Not only does it block official pre-roll ads, but it also natively integrates the community-driven SponsorBlock API to automatically skip in-video sponsor reads.
- Account-Free Subscriptions — You can build a massive library of subscribed channels, create custom playlists, and receive notifications without ever signing into a Google account.
- Audio-Only Mode — Perfect for mobile browsers or listening to podcasts. You can stream just the audio track, saving massive amounts of bandwidth and allowing background play on phones.
- Data Portability — Easily import or export your watch history and subscriptions to and from YouTube, NewPipe, or FreeTube.
Requirements before you start
While you can install Invidious manually using the Crystal programming language, the Docker method is highly recommended to easily manage the database and companion scripts.
- A Linux/Windows/Mac Environment — A server, old laptop, or VPS running a modern OS.
- Docker & Docker Compose — Essential for spinning up the web app, database, and stream helper simultaneously.
- Terminal Access — Basic familiarity with command-line interfaces.
- A Text Editor — To configure your server environment settings.
Step-by-step installation
Step 1 — Install Docker and Docker Compose
If you haven’t already, ensure Docker is installed on your system. You can verify this by opening your terminal and running:
docker --version
docker compose versionStep 2 — Clone the Invidious Repository
Download the official codebase which includes the necessary Docker configuration files:
git clone https://github.com/iv-org/invidious.git
cd invidiousStep 3 — Generate Trusted Session Tokens
To prevent YouTube from blocking your server’s video playback, you must generate a po_token and visitor_data string. Run this Docker command to automatically spin up a headless browser and fetch your tokens:
docker run quay.io/invidious/youtube-trusted-session-generatorThe terminal will output a block of text. Look for the lines stating visitor_data: and po_token: and copy those specific long strings of letters and numbers.
Step 4 — Configure the Environment
Open the docker-compose.yml file in your preferred text editor (like nano). Scroll down to the invidious service environment variables and paste the tokens you just generated:
environment:
- INVIDIOUS_CONFIG=...
- visitor_data=YOUR_COPIED_VISITOR_DATA
- po_token=YOUR_COPIED_PO_TOKENSave and exit the file.
Step 5 — Start the Server
Run the entire stack in detached mode. This will build the PostgreSQL database, the stream companion, and the main Invidious web interface:
docker compose up -dWait a minute or two for the database to initialize. Once ready, open your web browser and navigate to http://localhost:3000 (or your server’s IP address on port 3000). Welcome to your private, ad-free YouTube experience!
Common errors and fixes
| Error | What it means | How to fix it |
|---|---|---|
Nil assertion failed (NilAssertionError) when playing a video | YouTube is blocking your server’s IP from fetching the video stream, or the video is heavily age-restricted. | Ensure you successfully completed Step 3 and updated your docker-compose.yml with valid visitor_data and po_token variables. You may need to regenerate the tokens if they expire. |
Bind for 0.0.0.0:3000 failed: port is already allocated | Another application on your computer is already using port 3000. | Open docker-compose.yml and change the port mapping from "3000:3000" to something else, like "8080:3000", then run docker compose up -d again. |
FATAL: role "kemal" does not exist | The database container failed to initialize the default schemas before the web app tried to connect. | Run docker compose down -v to wipe the broken database volume, then run docker compose up -d to allow it to initialize cleanly from scratch. |
Free vs Paid comparison
| Feature | Invidious (Self-Hosted) | YouTube Premium |
|---|---|---|
| Cost | $0 Forever | $13.99+ per month |
| Ad Blocking | ✅ Yes (Including SponsorBlock) | ⚠️ Only blocks official pre-roll ads |
| Background Audio Playback | ✅ Yes (Built into the web player) | ✅ Yes (Via the official app) |
| Privacy & Tracking | ✅ Zero Google tracking or algorithms | ❌ Fully tracked to build ad profiles |
| 4K / High Bitrate Support | ⚠️ Limited (Often caps at 720p/1080p proxy) | ✅ Full 4K HDR Support |
Bottom line: If you are technically savvy and prioritize privacy and ad-free viewing over absolute 4K picture quality, self-hosting Invidious is an incredibly rewarding project. If you just want maximum convenience, 4K streaming on your smart TV, and zero maintenance, stick to YouTube Premium.
Alternatives — 3 similar tools
1. Piped
Often considered the main competitor to Invidious. Piped is another open-source web frontend for YouTube. It is generally recognized as being slightly more modern in its UI and more resilient against YouTube’s IP blocking, making it a great alternative if your Invidious instance struggles with video buffering.
2. FreeTube
Instead of a web application you run on a server, FreeTube is a privacy-focused desktop application you install directly on Windows, Mac, or Linux. It stores all your subscriptions locally on your computer and leverages a mix of Invidious APIs and local scraping to fetch videos.
3. NewPipe
The definitive open-source YouTube client for Android devices. It does not use the YouTube API or require Google Play Services. It provides background play, video downloading, and ad-blocking directly on your phone.
🚀 Want more free AI tools like this?
We find, test, and write setup guides for the best free and open-source AI tools — so you don’t have to dig through GitHub yourself.Browse Free AI Tools at globalaiforce.com/shop →
📸 Follow us for daily AI tool tips and tutorials: instagram.com/globalaiforce