unshackle/docs/getting-started/installation.md

Installation

unshackle is a modular archival tool for movies, TV, and music. It ships as a single Python package named unshackle that installs one console command, also called unshackle. This page covers installing that command, the Python version it needs, and the external command-line tools it expects to find on your PATH.

!!! note "What you get" Installing the package registers a single entry point, the unshackle command. It covers everything: downloading, key-vault management, device provisioning, the REST server, and the helper utilities.

Requirements at a glance

Requirement	Recommended version	Needed for
Python	3.11 to 3.14	Running unshackle itself
uv	≥ 0.5	Installing and running unshackle
FFmpeg	≥ 6.0	Media processing and analysis
MKVToolNix	≥ 80	MKV muxing and metadata editing
shaka-packager	2.6.1, or ≥ 3.10.0	DRM decryption
Bento4	≥ 1.6.0-639	Alternate DRM decryption (mp4decrypt)
dovi_tool	≥ 2.1	Dolby Vision handling
SubtitleEdit	≥ 5.0	Subtitle conversion (optional)

The sections below tell you about each of these, and how to make sure that your setup is complete.

Python versions

unshackle requires Python 3.11 or newer, up to and including 3.14 (requires-python = ">=3.11,<3.15"). Anything older than 3.11 or 3.15 and later is unsupported, and the installer refuses to assemble the environment.

You do not usually need to install a matching Python interpreter by hand, since uv can download and manage one for you. If you work inside an existing virtual environment, make sure that it is on a supported version.

Installing with uv

The recommended way to install unshackle is as a uv tool. This creates an isolated environment for the package and puts the unshackle command on your PATH without touching your system Python.

uv tool install git+https://github.com/unshackle-dl/unshackle.git

Once it finishes, the unshackle command is available globally:

unshackle --help

!!! tip "Upgrading and removing" Because you installed it from a git URL, re-run the same uv tool install command (uv will update in place) to get a newer version, and use uv tool uninstall unshackle to remove it.

Running from a clone

If you would rather work from a checkout of the repository (for example to try an in-development branch or to keep your own local services alongside unshackle), use uv run inside the clone. This keeps the project's virtual environment active for the duration of the command, so you do not have to activate it yourself.

git clone https://github.com/unshackle-dl/unshackle.git
cd unshackle
uv run unshackle --help

Every command shown elsewhere in these docs works the same way from a clone. Prefix it with uv run:

uv run unshackle env check

!!! note "Developer note" Contributors will also want the development and test dependency groups. The project defines dev (linters, type checkers) and test (pytest and friends) groups in pyproject.toml. Install them with uv sync --group dev --group test inside the clone. End users can ignore these entirely.

External tools on your PATH

unshackle shells out to a number of external command-line programs for media processing and DRM work. It looks for each one first in the binaries/ folder inside the installed package, and then falls back to your system PATH, so installing these tools system-wide (or dropping them into that folder) both work.

Required tools

These must be present for core downloading, decryption, and muxing to work:

Tool	Binary looked up	Why it is needed
FFmpeg	ffmpeg	Media processing: remuxing, conversion, track handling
FFprobe	ffprobe	Media analysis: inspecting tracks and container details
MKVToolNix	mkvmerge	Muxing downloaded tracks into a final MKV
mkvpropedit	mkvpropedit	Editing MKV metadata after muxing
shaka-packager	shaka-packager / packager	Decrypting DRM-protected content (the default decryptor)

!!! warning "shaka-packager is the default decryptor" unshackle decrypts with shaka-packager unless you explicitly configure a different decryptor. If it is missing, protected downloads will fail at the decryption step. See the configuration reference for the decryption config key if you want to switch to mp4decrypt.

!!! danger "Do not use shaka-packager 3.0 through 3.9.x" These versions stop with a segmentation fault on a single-track MP4 whose internal track_id is 2 or more. A track that unshackle downloads from a DASH or HLS manifest usually has such a track_id.

Recommended and optional tools

These extend unshackle's capabilities. Install the ones relevant to what you download. For example, dovi_tool only matters if you download Dolby Vision video.

Tool	Binary looked up	Why it is needed
Bento4 (mp4decrypt)	mp4decrypt	Alternative DRM decryptor to shaka-packager
MP4Box (GPAC)	MP4Box	Muxing DTS:X Profile 2 (DTS-UHD) audio
dovi_tool	dovi_tool	Dolby Vision metadata handling
HDR10Plus_tool	hdr10plus_tool	HDR10+ metadata handling
SubtitleEdit	seconv, SubtitleEdit	Subtitle conversion (the SeConv CLI from 5.x)
CCExtractor	ccextractor	Extracting closed captions
FFplay	ffplay	Simple preview player
MPV	mpv	Advanced preview player (used by util crop/util range previews)
HolaProxy	hola-proxy	Hola proxy provider support
Caddy	caddy	Optional reverse proxy for unshackle serve --caddy
Docker	docker	Gluetun VPN proxy support
Git	git	Fetching and updating remote service repositories

!!! info "MP4Box is only used for DTS:X Profile 2" Titles with DTS:X Profile 2 (DTS-UHD) audio mux to MP4; everything else muxes to MKV with mkvmerge. Install with apt install gpac.

!!! tip "SubtitleEdit specifics" unshackle looks for seconv first, the batch CLI shipped with SubtitleEdit 5.x, before falling back to a SubtitleEdit (4.x) binary. The 5.0 GUI has no batch mode, so the SeConv CLI is what you want for automated subtitle conversion.

Verifying your installation

After installation, make sure that the command works and that unshackle can see the tools it depends on.

Make sure the command is available

unshackle --help

This prints the list of available commands (dl, env, kv, serve, wvd, prd, search, util, cfg, import). If your shell reports that unshackle is not found, the uv tool bin directory is probably not on your PATH. Operate uv tool update-shell and open a new terminal.

Examine the external dependencies

The env check subcommand inspects your environment and reports which tools it found:

unshackle env check

=== "Output"

It prints a table grouped by category (Core, DRM, HDR, Subtitle, Player,
Network) with a status column: a green check for tools that resolved and a
red cross for those it could not find, plus a summary line such as
`All required tools installed ✓` or `Missing required: <names>`.

=== "From a clone"

```shell
uv run unshackle env check
```

If a required tool shows as missing, install it and put it on your PATH (or in the package's binaries/ folder), then re-run the check.

Inspect environment paths

To see where unshackle will read its configuration from and where it stores downloads, caches, cookies, and devices, use:

unshackle env info

If no configuration file exists yet, this command lists the locations unshackle searches for one, so you know where to make it. See the configuration guide for the details of that file.

Next steps

• Set up your configuration file (unshackle.yaml).
• Start downloading titles when env check finds every required tool.