Safely Choose a Default Command with update-alternatives

You will inspect a Debian alternatives group, choose a different implementation when needed, and return it to automatic selection without guessing what the system changed. The examples use update-alternatives from dpkg 1.22.6ubuntu6.6, whose installed manual page describes version 1.22.6.

Allow about ten minutes. You need a shell, an alternatives group such as editor or vi, and administrator access for commands that change links. Inspection is normally unprivileged.

1. Check the installed command

Confirm which executable and package version you are using. These commands only read local state:

$ command -v update-alternatives
/usr/bin/update-alternatives
$ dpkg-query -W -f='${Package} ${Version}\n' dpkg
dpkg 1.22.6ubuntu6.6
$ update-alternatives --version
update-alternatives version 1.22.6.

The tool maintains symbolic links for interchangeable programs. Its default alternatives directory is /etc/alternatives; its default administrative state is under /var/lib/dpkg/alternatives. Do not edit either location by hand. The command needs those records to keep a master link and any related slave links consistent.

2. Inspect a link group before changing it

Use --display for a readable overview. Here is a real group on this machine:

$ update-alternatives --display editor
editor - auto mode
  link best version is /bin/nano
  link currently points to /bin/nano
  link editor is /usr/bin/editor
  slave editor.1.gz is /usr/share/man/man1/editor.1.gz
/bin/ed - priority -100
  slave editor.1.gz: /usr/share/man/man1/ed.1.gz
/bin/nano - priority 40
  slave editor.1.gz: /usr/share/man/man1/nano.1.gz
/usr/bin/vim.basic - priority 30
  slave editor.1.gz: /usr/share/man/man1/vim.1.gz

Your list may contain different packages. In automatic mode, the group selects the available alternative with the highest priority. The master link is /usr/bin/editor. The manual page link is a slave, so it follows the selected editor rather than being changed independently.

3. Query machine-readable state when scripting

For a script or a careful audit, --query reports the same group in an RFC822-like format. It is still read-only:

$ update-alternatives --query editor | sed -n '1,18p'
Name: editor
Link: /usr/bin/editor
Slaves:
 editor.1.gz /usr/share/man/man1/editor.1.gz
Status: auto
Best: /bin/nano
Value: /bin/nano

Alternative: /bin/ed
Priority: -100
Slaves:
 editor.1.gz /usr/share/man/man1/ed.1.gz

Status is auto or manual. Best is the highest-priority available alternative, while Value is the current target. A missing or broken link can make the current value different from the best choice.

4. Choose an alternative interactively

When you need to select from the displayed list, use --config with elevated privileges:

$ sudo update-alternatives --config editor
There are 4 choices for the alternative editor (providing /usr/bin/editor).

  Selection    Path                  Priority   Status
------------------------------------------------------------
* 0            /bin/nano              40        auto mode
  1            /bin/ed               -100        manual mode
  2            /bin/nano              40        manual mode
  3            /usr/bin/vim.basic     30        manual mode

Press <enter> to keep the current choice[*], or type selection number:

The exact table depends on the installed packages. Enter the number for the path you actually want, then verify it:

$ update-alternatives --display editor | sed -n '1,5p'
editor - manual mode
  link currently points to /usr/bin/vim.basic
  link editor is /usr/bin/editor

5. Make a non-interactive choice

For automation, --set takes the alternative name and an exact absolute path. It performs the same kind of selection as --config without a prompt:

$ sudo update-alternatives --set editor /usr/bin/vim.basic
update-alternatives: using /usr/bin/vim.basic to provide /usr/bin/editor (editor) in manual mode
$ readlink -f /usr/bin/editor
/usr/bin/vim.basic
$ update-alternatives --query editor | grep -E '^(Status|Value):'
Status: manual
Value: /usr/bin/vim.basic

Only use a path shown by --display or --query. A path that is not registered is an error, not a reason to add a new alternative. Keep the command's exit status in scripts: status 0 means the action succeeded, while status 2 means command-line or action problems were encountered.

6. Return to automatic selection

Manual mode is deliberate: package installation and removal will not normally choose a different target for that group. To let priorities decide again, run:

$ sudo update-alternatives --auto editor
update-alternatives: using /bin/nano to provide /usr/bin/editor (editor) in auto mode
$ update-alternatives --display editor | sed -n '1,5p'
editor - auto mode
  link best version is /bin/nano
  link currently points to /bin/nano
  link editor is /usr/bin/editor

This is the recovery command for the ordinary selection workflow. If the original group had a higher-priority alternative installed, automatic mode may select that instead. Verify both the mode and target before relying on the result.

Common traps

• Confusing a generic name with a real program. Pass the group name, such as editor, to --display, --config, --set, or --auto. The selected target is a separate absolute path.
• Expecting manual mode to follow package changes. It will retain your administrator choice. Use --auto when that is no longer wanted.
• Changing only the executable. A link group can include slave links such as translated manual pages. Use the alternatives command so they move together.
• Using --install to override an unmanaged file. Alternatives only coordinates packages that use the mechanism. It cannot safely take over an arbitrary file from a package that does not.
• Using --force casually. It permits replacing or dropping a real file where an alternatives link must be installed or removed. Treat that as potentially destructive and inspect the conflict first.