Skip to content

Installation

After installation take a look at the Post-install steps.

Note: Any PaaS or SaaS provider/software (Heroku, YunoHost, Repli...) are unsupported. Use them at your own risk. They WILL cause problems with Invidious and might even suspend your account for "abuse" since Invidious is heavy, bandwidth intensive and technically a proxy (and most providers don't like them). If you use one and want to report an issue, please mention which one you use.

Hardware requirements

Running Invidious requires at least 20GB disk space, 512MB of free RAM (so ~2G installed on the system), as long as it is restarted regularly, as recommended in the post-install configuration. Public instances should ideally have at least 60G disk space, 4GB of RAM, 2vCPU, a 200 mbps link and 20TB of traffic (no data cap/unlimited traffic is preferred).

Compiling Invidious requires at least 2.5GB of free RAM (We recommend to have at least 4GB installed). If you have less (e.g on a cheap VPS) you can setup a SWAP file or partition, so the combined amount is >= 4GB.

You need at least 1GB of RAM for the machine that will run the tool youtube-trusted-session-generator in the 1st step. Doesn't need to be the same machine as the one running Invidious, just a machine running on the same public IP address.

Docker

The Invidious docker image is only available on Quay because, unlike Docker Hub, Quay is Free and Open Source Software. This is reflected in the docker-compose.yml file used in this walk-through.

Ensure Docker Engine and Docker Compose are installed before beginning.

Docker-compose method (production)

This method uses the pre-built Docker image from quay

Note: Currently the repository has to be cloned, this is because the init-invidious-db.sh file and the config/sql directory have to be mounted to the postgres container (See the volumes section in the docker-compose file below). This "problem" will be solved in the future.

Make sure to run the newer Docker Compose V2: https://docs.docker.com/compose/install/linux/. It should already be installed if you can successfully run the command docker compose (with a space between the two words).

About po_token and visitor_data identities

po_token known as Proof of Origin Token. This is an attestation token generated by a complex anti robot verification system created by Google named BotGuard/DroidGuard. It is used to confirm that the request is coming from a genuine device.

These identity tokens (po_token and visitor_data) generated in this tutorial will make your entire Invidious session more easily traceable by YouTube because it is tied to a unique identifier.

There is currently no official automatic tool to periodically change these tokens. This is working in progress but, for the time being, this is the solution the Invidious team is offering.

If you want to be less traceable, you can always script the process by changing the identities every X hour.

  1. Generate po_token and visitor_data identities for passing all verification checks on YouTube side:

    docker run quay.io/invidious/youtube-trusted-session-generator
    
    You have to run this command on the same public IP address as the one blocked by YouTube. Not necessarily the same machine, just the same public IP address.
    You will need to copy these two parameters in the third step.
    Subsequent usage of this same token will work on the same IP range or even the same ASN. The point is to generate this token on a blocked IP as "unblocked" IP addresses seems to not generate a token valid for passing the checks on a blocked IP.

  2. Execute these commands:

    git clone https://github.com/iv-org/invidious.git
    cd invidious
    

  3. Edit the docker-compose.yml with this content:

    version: "3"
    services:
    
      invidious:
        image: quay.io/invidious/invidious:latest
        # image: quay.io/invidious/invidious:latest-arm64 # ARM64/AArch64 devices
        restart: unless-stopped
        ports:
          - "127.0.0.1:3000:3000"
        environment:
          # Please read the following file for a comprehensive list of all available
          # configuration options and their associated syntax:
          # https://github.com/iv-org/invidious/blob/master/config/config.example.yml
          INVIDIOUS_CONFIG: |
            db:
              dbname: invidious
              user: kemal
              password: kemal
              host: invidious-db
              port: 5432
            check_tables: true
            signature_server: inv_sig_helper:12999
            visitor_data: CHANGE_ME
            po_token: CHANGE_ME
            # external_port:
            # domain:
            # https_only: false
            # statistics_enabled: false
            hmac_key: "CHANGE_ME!!"
        healthcheck:
          test: wget -nv --tries=1 --spider http://127.0.0.1:3000/api/v1/trending || exit 1
          interval: 30s
          timeout: 5s
          retries: 2
        logging:
          options:
            max-size: "1G"
            max-file: "4"
        depends_on:
          - invidious-db
    
      inv_sig_helper:
        image: quay.io/invidious/inv-sig-helper:latest
        init: true
        command: ["--tcp", "0.0.0.0:12999"]
        environment:
          - RUST_LOG=info
        restart: unless-stopped
        cap_drop:
          - ALL
        read_only: true
        security_opt:
          - no-new-privileges:true
    
      invidious-db:
        image: docker.io/library/postgres:14
        restart: unless-stopped
        volumes:
          - postgresdata:/var/lib/postgresql/data
          - ./config/sql:/config/sql
          - ./docker/init-invidious-db.sh:/docker-entrypoint-initdb.d/init-invidious-db.sh
        environment:
          POSTGRES_DB: invidious
          POSTGRES_USER: kemal
          POSTGRES_PASSWORD: kemal
        healthcheck:
          test: ["CMD-SHELL", "pg_isready -U $$POSTGRES_USER -d $$POSTGRES_DB"]
    
    volumes:
      postgresdata:
    

    Note: This compose is made for a true "production" setup, where Invidious is behind a reverse proxy. If you prefer to directly access Invidious, replace 127.0.0.1:3000:3000 with 3000:3000 under the ports: section.

  4. Run the docker composition:

docker compose up -d

Docker-compose method (development)

This method builds a Docker image from source

git clone https://github.com/iv-org/invidious.git
cd invidious
docker-compose up

Manual Installation

Linux

Generate po_token and visitor_data identities

Follow these instructions here on the official tool youtube-trusted-session-generator

These two parameters will be required for passing all verification checks on YouTube side and you will have to configure them in Invidious.

You have to run this command on the same public IP address as the one blocked by YouTube. Not necessarily the same machine, just the same public IP address.
You will need to copy these two parameters in the config.yaml file.
Subsequent usage of this same token will work on the same IP range or even the same ASN. The point is to generate this token on a blocked IP as "unblocked" IP addresses seems to not generate a token valid for passing the checks on a blocked IP.

About po_token and visitor_data identities

po_token known as Proof of Origin Token. This is an attestation token generated by a complex anti robot verification system created by Google named BotGuard/DroidGuard. It is used to confirm that the request is coming from a genuine device.

These identity tokens (po_token and visitor_data) generated in this tutorial will make your entire Invidious session more easily traceable by YouTube because it is tied to a unique identifier.

There is currently no official automatic tool to periodically change these tokens. This is working in progress but, for the time being, this is the solution the Invidious team is offering.

If you want to be less traceable, you can always script the process by changing the identities every X hour.

Run inv_sig_helper in background

Follow these instructions here on the official tool inv_sig_helper and run it in the background with systemd for example.

inv_sig_helper handle the "deciphering" of the video stream fetched from YouTube servers. As it is running untrusted code from Google themselves, make sure to isolate it by for example running it inside a LXC or locked down through systemd.

The following systemd service file can be used to run inv_sig_helper with systemd: https://github.com/iv-org/inv_sig_helper/blob/master/inv_sig_helper.service

Install Crystal

Follow the instructions for your distribution here: https://crystal-lang.org/install/

Note: Invidious currently supports the following Crystal versions: 1.10.x / 1.11.x / 1.12.x. \ Versions 1.9.x and older are incompatible because we use features only present in the newer versions. \ Versions 1.13.x should be compatible, however we did not test it.

Install the dependencies

Arch Linux

sudo pacman -S base-devel librsvg postgresql ttf-opensans

Debian/Ubuntu

sudo apt install libssl-dev libxml2-dev libyaml-dev libgmp-dev libreadline-dev postgresql librsvg2-bin libsqlite3-dev zlib1g-dev libpcre3-dev libevent-dev fonts-open-sans

RHEL based and RHEL-like systems (RHEL, Fedora, AlmaLinux, RockyLinux...)

sudo dnf install -y openssl-devel libevent-devel libxml2-devel libyaml-devel gmp-devel readline-devel postgresql librsvg2-devel sqlite-devel zlib-devel gcc  open-sans-fonts

Add an Invidious user and clone the repository

useradd -m invidious
su - invidious
git clone https://github.com/iv-org/invidious
exit

Set up PostgreSQL

systemctl enable --now postgresql
sudo -i -u postgres
psql -c "CREATE USER kemal WITH PASSWORD 'kemal';" # Change 'kemal' here to a stronger password, and update `password` in config/config.yml
createdb -O kemal invidious
exit

Set up Invidious

su - invidious
cd invidious
make

# Configure config/config.yml as you like
cp config/config.example.yml config/config.yml 

# edit config.yaml to include po_token and visitor_data previously generated

edit config/config.yaml

# Deploy the database
./invidious --migrate

exit

Systemd service

cp /home/invidious/invidious/invidious.service /etc/systemd/system/invidious.service
systemctl enable --now invidious.service

MacOS

Generate po_token and visitor_data identities

Follow these instructions here on the official tool youtube-trusted-session-generator

These two parameters will be required for passing all verification checks on YouTube side and you will have to configure them in Invidious.

You have to run this command on the same public IP address as the one blocked by YouTube. Not necessarily the same machine, just the same public IP address.
You will need to copy these two parameters in the config.yaml file.
Subsequent usage of this same token will work on the same IP range or even the same ASN. The point is to generate this token on a blocked IP as "unblocked" IP addresses seems to not generate a token valid for passing the checks on a blocked IP.

About po_token and visitor_data identities

po_token known as Proof of Origin Token. This is an attestation token generated by a complex anti robot verification system created by Google named BotGuard/DroidGuard. It is used to confirm that the request is coming from a genuine device.

These identity tokens (po_token and visitor_data) generated in this tutorial will make your entire Invidious session more easily traceable by YouTube because it is tied to a unique identifier.

There is currently no official automatic tool to periodically change these tokens. This is working in progress but, for the time being, this is the solution the Invidious team is offering.

If you want to be less traceable, you can always script the process by changing the identities every X hour.

Run inv_sig_helper in background

Follow these instructions here on the official tool inv_sig_helper

inv_sig_helper handle the "deciphering" of the video stream fetched from YouTube servers. As it is running untrusted code from Google themselves, make sure to isolate it by for example running it inside Docker or a VM.

Call for action: An example here is welcome, if you want to contribute to one.

Install the dependencies

brew update
brew install crystal postgresql imagemagick librsvg

Clone the Invidious repository

git clone https://github.com/iv-org/invidious
cd invidious

Set up PostgreSQL

brew services start postgresql
createdb
psql -c "CREATE ROLE kemal WITH LOGIN PASSWORD 'kemal';" # Change 'kemal' here to a stronger password, and update `password` in config/config.yml
createdb -O kemal invidious
psql invidious kemal < config/sql/channels.sql
psql invidious kemal < config/sql/videos.sql
psql invidious kemal < config/sql/channel_videos.sql
psql invidious kemal < config/sql/users.sql
psql invidious kemal < config/sql/session_ids.sql
psql invidious kemal < config/sql/nonces.sql
psql invidious kemal < config/sql/annotations.sql
psql invidious kemal < config/sql/playlists.sql
psql invidious kemal < config/sql/playlist_videos.sql

Set up Invidious

make

# Configure config/config.yml as you like
cp config/config.example.yml config/config.yml

# edit config.yaml to include po_token and visitor_data previously generated

edit config/config.yaml

Windows

Crystal, the programming language used by Invidious, doesn't officially support Windows yet but you can still install Invidious:

Post-install configuration:

Detailed configuration available in the configuration guide.

You must set a random generated value for the parameter hmac_key:! On Linux you can generate it using the command pwgen 20 1.

Because of various issues, Invidious must be restarted often, at least once a day, ideally every hour.

If you use a reverse proxy, you must configure Invidious to properly serve request through it:

https_only: true : if you are serving your instance via https, set it to true

domain: domain.ext: if you are serving your instance via a domain name, set it here

external_port: 443: if you are serving your instance via https, set it to 443

use_pubsub_feeds: true: if you are serving your instance on the internet, allow for faster notification of new videos (detailed explanation).

use_innertube_for_captions: true: if you are serving a public instance or you are hosting Invidious in a datacenter, allow to unblock captions (detailed explanation).

Update Invidious

Updating a Docker install

docker-compose pull
docker-compose up -d
docker image prune -f

Update a manual install

su - invidious
cd invidious
git pull
make
exit
systemctl restart invidious.service

Usage:

./invidious

Logrotate configuration

echo "/home/invidious/invidious/invidious.log {
rotate 4
weekly
notifempty
missingok
compress
minsize 1048576
}" | tee /etc/logrotate.d/invidious.logrotate
chmod 0644 /etc/logrotate.d/invidious.logrotate