The Configuration File¶
Almost everything about how unshackle behaves is controlled by a single YAML file named unshackle.yaml: where it saves downloads, which CDM it uses, your credentials, proxies, filename templates, and more. This page covers where that file lives, how unshackle finds it, the shape of its contents, the directory layout unshackle builds around it, and how to edit values from the command line.
Where the exhaustive key list lives
This page is an overview. For the complete, key-by-key breakdown of every setting, its type, and its default, see the Configuration Reference.
The config filename¶
The main configuration file is always named unshackle.yaml. It is a plain YAML file. You can open and edit it in any text editor, or manage individual values with the unshackle cfg command.
If you have never created one, that is fine: unshackle runs entirely on built-in defaults when no config file exists. The file only needs to contain the keys you want to change from their defaults.
Where the config file lives¶
When unshackle starts, it searches a fixed list of locations and uses the first one that exists. In order of priority:
| # | Location | Typical path |
|---|---|---|
| 1 | The unshackle package folder | .../site-packages/unshackle/unshackle.yaml |
| 2 | The parent of the package folder | .../site-packages/unshackle.yaml |
| 3 | Your OS user-config directory | see the table below |
The third location, your per-user config directory, is the recommended place for most installations, because it lives outside the package and survives reinstalls and upgrades. Its exact path depends on your operating system:
Not sure which file is being used?
Run unshackle env info. It prints the path the config was loaded from (or tells you none was found), along with every directory unshackle is currently using.
The config is read exactly once, when unshackle starts. If you edit the file, the change takes effect on the next command you run.
Top-level structure¶
unshackle.yaml is a flat map of top-level keys. Each key configures one area of the program. You only include the keys you want to change; everything else falls back to its default.
Here is a small, realistic example that sets a download location, a release tag, a default CDM, and one service's credentials:
# Where finished downloads are written
directories:
downloads: ~/Videos/unshackle
# Release group tag appended to filenames
tag: MYGRP
# Default Widevine/PlayReady device to use, with per-service overrides
cdm:
default: my_device_l3
EXAMPLE: my_device_l1
# Per-service login details (service tag -> "username:password")
credentials:
EXAMPLE: my_email@example.com:hunter2
# Default HTTP headers merged into every request
headers:
Accept-Language: en-US,en;q=0.9
The top-level keys group loosely into these areas:
| Area | Example keys |
|---|---|
| Downloading & DRM | dl, cdm, remote_cdm, decryption |
| Networking | network, headers |
| Credentials & cookies | credentials, firefox_cookies |
| Tracks & muxing | subtitle, audio, muxing, language_tags |
| Key vaults | key_vaults, vault_timeout |
| Proxies & remote | proxy_providers, remote_services, serve, services |
| Naming & tagging | tag, output_template, chapter_fallback_name |
| External API keys | tmdb_api_key, simkl_client_id, ipinfo_api_key |
| Behavior & logging | update_checks, redact_paths, debug, unicode_filenames |
| Paths | directories, filenames |
For the full list with types and defaults, see the Configuration Reference.
Unknown keys are silently ignored
unshackle does not validate your config against a schema. If you misspell a key, it is simply skipped and the default is used. You will not get an error. Double-check key names (and their nesting) if a setting does not seem to apply.
Setting download defaults (dl:)¶
If you always pass the same dl flags (a language, a resolution, a codec), put them under a
dl: key once and unshackle applies them to every download. Any flag from
Downloading works here; the key is the flag's long name with dashes
turned into underscores (--best-available → best_available).
dl:
lang: [en] # -l en
quality: [1080] # -q 1080
vcodec: [H265] # -v H265
sub_format: srt # convert subtitles to SRT
downloads: 2 # two tracks at once
You can still override any of these on the command line for a one-off; an explicit flag
always beats the config default. You can also scope defaults to a single service by nesting a
dl: block under it:
dl:
lang: [en] # default for everything
services:
EXAMPLE:
dl:
lang: [en, ja] # Example downloads English + Japanese
A few keys are named after the flag's internal name
Most keys are obvious, but set these exact ones: range (-r), list (--list),
tmdb_id (--tmdb), imdb_id (--imdb), no_atmos (--noatmos), and output_dir
(-o). The Configuration Reference has the full list
and every available key.
The directory layout¶
The directories key controls where unshackle reads and writes its various files. Each directory has a sensible default, and you can override most of them by giving a new path. Paths support ~ for your home directory.
directories:
downloads: ~/Videos/unshackle
temp: /mnt/fast/unshackle-temp
cache: ~/.cache/unshackle
The directories unshackle uses:
| Name | Purpose | Overridable |
|---|---|---|
downloads |
Default output folder for finished downloads | Yes |
temp |
Temporary working files during a download | Yes |
cache |
Cache store (title cache, update checks, service caches) | Yes |
cookies |
Per-service cookie files | Yes |
logs |
Log files | Yes |
exports |
Export JSONs | Yes |
wvds |
Widevine devices (.wvd files) |
Yes |
prds |
PlayReady devices (.prd files) |
Yes |
dcsl |
DCSL data | Yes |
services |
Search paths for service code (see below) | Yes |
commands |
CLI command modules | Yes |
vaults |
Vault modules | Yes |
fonts |
Bundled fonts | Yes |
Some directories cannot be moved
A handful of internal locations are protected: the package root, the core directory, the user-config directory, and the data base. If you list them under directories, unshackle silently ignores the override. This is intentional; those paths are tied to where the package is installed.
The services directory is special¶
Unlike the other entries, services is a list, and each entry can be either a local folder or a remote repository. This lets you mix your own local service code with services pulled from Git:
directories:
services:
- unshackle-dl/services # a GitHub owner/repo shorthand
- https://github.com/me/my-services.git
- ~/code/local-services # a local folder
Entries are searched in the order listed, and the first source to define a given service tag wins, so put local folders last if you want them to act as fallbacks rather than overrides. Remote repositories are cloned and periodically updated for you. See Services for the full details on how service discovery and repositories work.
The filenames key¶
Alongside directories, the filenames key lets you override the templates unshackle uses when naming its own working and log files (for example the log filename or the temporary chapters file). Most users never need to touch this. The available names and their default templates are listed in the Configuration Reference.
Editing the config with unshackle cfg¶
You do not have to edit unshackle.yaml by hand. The unshackle cfg command reads and writes individual values for you, creating the config file (and its parent directory) if it does not exist yet.
Read a single value by passing its key. Nested keys use dot notation:
Set a value by passing a key and a value:
Values are parsed as Python literals where possible, so numbers, booleans, and lists work naturally, while bare text is treated as a string:
Remove a value with --unset:
List everything currently set with --list:
When it writes, unshackle cfg targets the config file that was loaded. If none exists yet, it creates unshackle.yaml in your OS user-config directory.
Editing with cfg strips comments
Because unshackle cfg rewrites the whole file when it saves, any comments in unshackle.yaml are removed by a write. If you keep important notes as comments, edit the file by hand instead, or keep those notes elsewhere.
Next steps¶
- Browse the Configuration Reference for every key and default.
- Set up your first download in Downloading.
- Learn how services are discovered and updated in Services.