Installation

Docker

There are two basic steps to install iSponsorBlockTV using Docker. Step 1 involves creating a config.json file using the graphical configuation or command-line tools. Step 2 involves creating and running the service via docker compose or run. In both steps, you will need to enter the pathway to your iSponsorBlockTV data directory. Alternatively, you can install iSponsorBlock from pypi, releases or from source.

Step 1: Create a config file

Choose one of the following configurators to add devices and configure options.

Option 1: Using the new graphical configurator tool

You can use the graphical setup wizard (powered by textual). If you want to auto discover your device, you need to run the container with the --net=host flag. This only works on linux.

Run it with the following command:

docker run --rm -it \
-v /PATH_TO_YOUR_DATA_DIR:/app/data \
--net=host \ # Remove line on windows and macOS
-e TERM=$TERM -e COLORTERM=$COLORTERM \ #Remove if you get errors/graphical glitches
ghcr.io/dmunozv04/isponsorblocktv \
--setup

Option 2: Using the text-based cli configurator tool

This is a great option if you experience issues with the graphical configurator Docker users can run it with the following command:

docker run --rm -it \
-v /PATH_TO_YOUR_DATA_DIR:/app/data \
ghcr.io/dmunozv04/isponsorblocktv \
--setup-cli

Note, the CLI will ask you for a TV Link Code. You can find this on your Device's Youtube app, by going to Settings -> Link with TV code

Step 2: Install and run the iSponsorBlockTV Docker service

Option 1: Using docker-compose

services:
    iSponsorBlockTV:
        image: ghcr.io/dmunozv04/isponsorblocktv
        container_name: iSponsorBlockTV
        restart: unless-stopped
        network_mode: host
        volumes:
        - /PATH_TO_YOUR_DATA_DIR:/app/data #enter the same pathway as you used for your configurator in step 1

Similar to Step 1, create a config file

docker compose run iSponsorBlockTV --setup

After completing setup, use docker-compose up -d to start.

Option 2: Using docker run

Run the container with docker run: The container doesn't need the --net=host flag anymore, so you can run it like this:

docker run -d \
--name iSponsorBlockTV \
--restart=unless-stopped \
-v /PATH_TO_YOUR_DATA_DIR:/app/data \
ghcr.io/dmunozv04/isponsorblocktv

Option 3: Quadlet

Before setting up the container, you will need to generate configs. Follow the instructions in the earlier docker steps, optionally replacing docker with podman. Place the generated configs in /etc/containers/config/isponsorblocktv/

You can set up a quadlet service using the following config:

[Unit]
Description="Sponsorblock for networked youtube clients"
Wants=network-online.target
After=network-online.target

[Install]
WantedBy=multi-user.target default.target

[Service]
Restart=always
TimeoutStartSec=900

[Container]
Image=ghcr.io/dmunozv04/isponsorblocktv:latest
Volume=/etc/containers/config/isponsorblocktv:/app/data
#UserNS=auto # uncomment to run under random uid to increase security

Place that in a file at /etc/containers/systemd/isponsorblocktv.container, run systemctl daemon-reload, and you should now have a systemd service titled isponsorblocktv that you can start, stop, and enable/disable the same as any other systemd service.

From PyPI

You can install iSponsorBlockTV from PyPI using pipx or uv. This will manage dependencies and allow you to run the program without needing to install Python or any other dependencies manually.

Install with uv

You can install uv from uv's official documentation Once you have uv installed, you can install iSponsorBlockTV with the following command:

uv tool install isponsorblocktv

Install with pipx

You can install pipx from pipx's official documentation.

Once you have pipx installed, you can install iSponsorBlockTV with the following command:

pipx install isponsorblocktv

Setup

After installing, you can run the setup command to create a config file.

Option 1: Using the new graphical configurator tool:

You can use the graphical setup wizard (powered by textual).

isponsorblocktv --setup

Option 2: Using the text-based cli configurator tool:

This is a great option if you experience issues with the graphical configurator.

isponsorblocktv --setup-cli

Run iSponsorBlockTV and Service setup for uv/pipx installers

After installing iSponsorBlockTV, you can run it using the following command:

iSponsorBlockTV

You should create a service using systemd, or another service manager, to run iSponsorBlockTV in the background. There's an open issue to handle this automatically.

Debian 13 example (installed using pipx or uv):

1. Creating service file (isponsorblocktv.service)

sudo nano /etc/systemd/system/isponsorblocktv.service

2. Turning it into a service

[Unit]
Description=isponsorblocktv background service
# Start after basic system initialization and networking are available
After=network.target multi-user.target

[Service]
Type=simple
# Path to your shell script (check your path with: which iSponsorBlockTV)
ExecStart=/home/pi/.local/bin/iSponsorBlockTV
# Ensure the service restarts if it fails
Restart=on-failure
# Wait 10 second before attempting a restart
RestartSec=10
# Optional: specify a user to run the service as (defaults to root if none specified, my user is called pi)
User=pi
StandardOutput=journal

[Install]
# Enable the service to start automatically at boot
WantedBy=multi-user.target

After pasting, you want to press CTRL+O (not zero) to write out/save the file

Enter/Return to confirm write

and CTRL+X to exit nano/text editor

3. Start and enable the service

Reload daemon

systemctl daemon-reload

Start the service, this starts it for the first time

systemctl start isponsorblocktv.service

Enable the service, this makes it run on boot after networking is ready

systemctl enable isponsorblocktv.service

Check the service

systemctl status isponsorblocktv.service

If everything went well you should see something like:

pi@pi:/etc/systemd/system $ systemctl status isponsorblock.service
● isponsorblocktv.service - isponsorblocktv background service
     Loaded: loaded (/etc/systemd/system/isponsorblock.service; enabled; preset: enabled)
     Active: active (running) since Thu 2026-01-08 00:06:09 MST; 8h ago
 Invocation: a68e17cbb6da43318f07b23d54fa1775
   Main PID: 7266 (iSponsorBlockTV)
      Tasks: 3 (limit: 163)
        CPU: 53.884s
     CGroup: /system.slice/isponsorblock.service
             └─7266 /home/pi/.local/share/uv/tools/isponsorblocktv/bin/python /home/pi/.local/bin/iSponsorBlockTV

Jan 08 08:20:17 pi iSponsorBlockTV[7266]: 2026-01-08 08:20:17,000 - iSponsorBlockTV-ppmi1vccl8tsfbpl5j347h2oj5 - INFO ->
Jan 08 08:24:52 pi iSponsorBlockTV[7266]: 2026-01-08 08:24:52,629 - iSponsorBlockTV-ppmi1vccl8tsfbpl5j347h2oj5 - INFO ->

From Releases

You can download the latest release from the releases page. Locate the file that matches your system OS and architecture, and download it. The file will be named isponsorblocktv-<version>-<arch>-<os>-<suffix>.

After downloading, you can run the binary directly. Make sure to give it execute permissions if necessary. You will need to run the setup command to create a config file (see above for instructions). It's recommended to set up a service using systemd, or another service manager, to run iSponsorBlockTV in the background.

From source

Install

You need to install python version 3.9 or higher first, and to make it available in your PATH. After, clone the repo. Then you need to download the dependencies with pip: python3 -m pip install -r requirements.txt Or python -m pip install -r requirements.txt

Lastly, run main.py

Setup

run main.py --setup