Sign inDemoInstall

Package Overview
File Explorer

Install Socket

Detect and block malicious and high-risk dependencies


Package govidious implements a wrapper over the Invidious REST API v1, which is described in these documents: For each of the endpoints listed in those links, this module provides an API function which: Takes as many input arguments as needed depending on the endpoint. For example, the "/api/v1/stat" endpoint is represented by the "Stat()" API function which takes no arguments, while the "/api/v1/search" endpoint is represented by the "Search()" API function which takes many arguments (search query, date, duration, ...). Returns a structure that matches the JSON response associated to each endpoint. In order to use this package first create a new "InvidiousV1" instance using the "New()" function: ...then, simply call, on that object, the desired API function(s): For example, to get the URL of the most watched video featuring "kittens playing golf", you would do this: Notice that both URLs ("youtubeUrl" and "invidiousUrl") can be used on a web browser to actually watch the video. The main difference is that: Using "youtubeUrl" establishes a direct connection with YouTube servers. Using "invidiousUrl" might or might not establish a direct connection with YouTube servers, depending on how the Invidious server is configured. If you don't want to leave any trace of YouTube servers, make sure you use "InvidiousUrl" on an Invidious server configured to proxy video files. Another thing you can do with this URL ("youtubeUrl" or "invidiousUrl") is to use the "mpv" player to start watching the video directly, without needing a web browser. Under the hood, "mpv" uses "youtube-dl" (another program) to parse the web page, find the URL of the video file (which might change depending on the options you call "mpv" with, such as the desired quality) and download it. Well... the good news is that you don't need "mpv" nor "youtube-dl" to do all of this as the Invidious API can also be used to find out the URL of the video file once you have the "videoId". First, you obtain all the associated data of the desired video: ...then you inspect the returned structure to find the URL of the video with the desired quality level: There are many other things you can do with this package, such as listing all the videos from a given channel, retrieving the subtitles associated to a video, etc... Check the documentation of each function (and the name of the fields of the structures they return) for more details.

Version published




This is a Go module (ie. "library") that provides a wrapper over the Invidious REST API v1.


It lets you access the Invidious API directly from Go to search for videos, get their URL, etc... like this:

import ""           // <--- Tell Go you are going to use this module
g := govidious.New(INVIDIOUS_SERVER, nil)        // <--- Specify the URL of an Invidious server
queryResults, _ := g.Search("Rick Asley")        // <--- Query the Invidious server

for _, videoEntry := range queryResults.Videos { // <--- Process the results

If you don't know what an "Invidious server" is, jump to the latest section of this README, called "About Invidious". Then come back and keep reading from here.


For a more detailed package/API description, check the module embedded documentation, which you can obtain in two ways:

  1. You can print it to stdout by running this command:

    $ go doc -all
  2. ...Or you can serve it in HTML form in "http://localhost:6060" by running this other command:

    $ godoc

There is also a "example_test.go" file that shows how some of the APIs are meant to be used.


This is GPLv3 software. Check file "LICENSE" inside this same folder.


If you want to contribute to this repository, please make sure you run all the tests before sending your patch, like this:

$ go test -server <URL of Indivious server>

...where <URL of Indivious server> is the IP/URL of an Indivious server that has been configured to expose the REST API.

Note that, depending on several items that will be discussed next, not all tests are required to end successfully. The rule is that the same number of tests must end successfully before and after applying your patch.

Things you have to be aware of:

  • Problems with public servers:
    • Not all public servers are configured to expose the REST API.
    • Public servers configured to expose the REST API might not expose all the expected APIs (for example, the "Stats" endpoint is usually disabled)
    • Public servers tend to be rate limited, thus running the whole test suit at once might fail. In that case, try running each individual test function by adding the -run <function_name> option.
  • Because of all the previous items, it is recommended to use your own (private) Invidious server instead of a public one (see section "Running your own Invidious instance" at the end of this README to find out how to do it).
  • The YouTube HTML code (which Invidious parses) changes very frequently. This means any of the Invidious REST endpoints might break for a few days (until Invidious developers fix it) at any point in time.
  • When one API fails, add the -verbose option to better understand what the problem might be.

About Invidious

What is Invidious?

"Invidious", in case you don't already know, is an alternative front-end to YouTube. In other words: you can watch YouTube videos by either going directly to "" or to any of the existing "Invidious" instances deployed all over the world (see here)

Invidious is an open source project (hosted here), so you can (and, in fact, are encouraged) to run it on your own server.

Why would I want to access an Invidious server instead of the original YouTube server?

Several reasons:

  1. Avoid the (direct) Google tracking that takes place every time you visit a YouTube page.

    Note: On the most simple configuration, Invidious simply removes the Javascript tracking and gives you a direct link to the (YouTube) hosted video, thus Google will still be able to know which videos are being served to your IP. However, it is also true that Invidious can be configured to proxy the videos itself, so that you never interact with Google/YouTube servers, which is great... but remember this needs to be explicitely configured.

  2. No need to sign in to watch age restricted videos.

  3. Depending on where the Invidious instance is located, you will also be able to watch geo-restricted videos.

  4. Invidious servers can be configured to expose a public REST API, which is something that requires an account in the case of YouTube servers. This makes it possible to create tools that communicate with the Invidious server to "navigate" the YouTube database (search for videos, check their comments, etc...)

You can see what others think about Invidious here:

Running your own Invidious instance

Why is it "better" to run my own instance instead of using a public one? Several reasons:

  1. Avoid centralization. The more instances there are, the harder they are to censor.

  2. Privacy. Maybe you don't (and, in fact, you shouldn't!) trust public instances (they might, for example, log your queries).

This doesn't mean it is "bad" to use public instances. It only means that it is "better" to run your own.

Note, however, that the IP that your instance uses might become "blocked" by YouTube if it is abused (for example, if you publish the IP of your instance and many people start using it).

In order to run your own instance follow these instructions

From all the alternatives described in the previous link, using docker is the easiest one:

git clone
cd invidious
docker-compose up  

...and the instance will be ready on http://localhost:3000 (for either direclty accessing it from your webbrowser or using it as the REST API URL)

Notice that before running "docker-compose up" you might want to edit file "docker-compose.yml", in particular section "INVIDIOUS_CONFIG" where you can add/change any of the configuration parameters described here.


Last updated on 12 Apr 2023

Did you know?

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.


Related posts

SocketSocket SOC 2 Logo


  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap

Stay in touch

Get open source security insights delivered straight into your inbox.

  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc