update-alternatives: Usage, Options & Common CI Errors
update-alternatives picks which binary a generic command (python, gcc, java) points to.
update-alternatives maintains the Debian "alternatives" symlinks, letting you choose which concrete binary a generic name resolves to. In CI it is how you make python mean python3.12 or pick a gcc version.
What it does
update-alternatives manages symlinks in /etc/alternatives so a generic command (the "link") resolves to one of several "alternatives", chosen by priority or explicitly. --install registers a candidate, --set forces one, --config prompts to choose. It is the canonical way to set a default compiler or Python in CI.
Common usage
update-alternatives --install /usr/bin/python python /usr/bin/python3.12 1
update-alternatives --set python /usr/bin/python3.12
update-alternatives --config gcc # interactive (avoid in CI)
update-alternatives --query python # show current state
update-alternatives --remove python /usr/bin/python3.10Common errors in CI
"update-alternatives: error: no alternatives for X" means nothing was registered for that link yet - run --install first. --config is interactive and will hang a non-TTY job; use --set <name> <path> instead. A wrong choice silently sticks because alternatives prefer the highest priority in auto mode - use --set to force a specific path and pin it in manual mode. The target binary must exist or --install fails with "alternative path ... doesn't exist".
Options
| Flag | What it does |
|---|---|
| --install <link> <name> <path> <pri> | Register a candidate with a priority |
| --set <name> <path> | Force a specific alternative (manual mode) |
| --config <name> | Interactively choose (avoid in CI) |
| --query / --display <name> | Show the current configuration |
| --remove <name> <path> | Remove a candidate |