Basically it says to your machine to use this alternative of Jave JDK instead of the default one, which, in Linux systems, is OpenJDK.

A brief extract from the man page is better than any answer I could write:

update-alternatives creates, removes, maintains and displays information about the symbolic links comprising the Debian alternatives system.

It is possible for several programs fulfilling the same or similar functions to be installed on a single system at the same time. For example, many systems have several text editors installed at once. This gives choice to the users of a system, allowing each to use a different editor, if desired, but makes it difficult for a program to make a good choice for an editor to invoke if the user has not specified a particular preference.

Debian's alternatives system aims to solve this problem. A generic name in the filesystem is shared by all files providing interchangeable functionality. The alternatives system and the system administrator together determine which actual file is referenced by this generic name. For example, if the text editors ed(1) and nvi(1) are both installed on the system, the alternatives system will cause the generic name /usr/bin/editor to refer to /usr/bin/nvi by default. The system administrator can override this and cause it to refer to /usr/bin/ed instead, and the alternatives system will not alter this setting until explicitly requested to do so.

With --install you specified a link, "/usr/bin/java" a name "java" and a path "/usr/lib/java/JDK...." and you add a group of alternatives to the system. link is the generic name for the master link, name is the name of its symlink in the alternatives directory, and path is the alternative being introduced for the master link.

I hope to be clear enough, Here there is a post regarding java alternatives.

For the complete usage list I suggest to look at the same manual page, typing man update-alternatives on your OS shell;

Answer from Fjordo on Stack Overflow
🌐
Linux Man Pages
man7.org › linux › man-pages › man1 › update-alternatives.1.html
update-alternatives(1) - Linux manual page
Note: In most (if not all) cases no other maintainer script actions should call update-alternatives, in particular neither of upgrade nor disappear, as any other such action can lose the manual state of an alternative, or make the alternative temporarily flip-flop, or completely switch when ...
🌐
Linux Man Pages
linux.die.net › man › 8 › update-alternatives
update-alternatives(8) - Linux man page
When each package providing a file with a particular functionality is installed, changed or removed, alternatives is called to update information about that file in the alternatives system. alternatives is usually called from the %post or %pre scripts in RPM packages.
🌐
Baeldung
baeldung.com › home › administration › the update-alternatives command in linux
The update-alternatives Command in Linux | Baeldung on Linux
July 24, 2024 - Then, we’re provided with data concerning all other editor‘s alternatives. Let’s find out from display‘s output that the link to the actual program may be accompanied by slave links. Consequently, the program’s link is the master one. The slave links point to other files and should follow the change of the master. In our case, they point to manuals. So, let’s select vim as editor and check editor‘s manual: $ sudo update-alternatives --set editor /usr/bin/vim.tiny update-alternatives: using /usr/bin/vim.tiny to provide /usr/bin/editor (editor) in manual mode
🌐
SUSE
documentation.suse.com › sled › 15-SP7 › html › SLED-all › cha-update-alternative.html
update-alternatives: managing multiple versions of commands and files | Administration Guide | SLED 15 SP7
May 12, 2024 - But you can run it manually from the command line for: displaying the current alternatives for a generic name. ... > sudo update-alternatives --get-selections asadmin auto /usr/bin/asadmin-2.7 awk auto /usr/bin/gawk chardetect auto /usr/bin/chardetect-3.6 dbus-launch auto /usr/bin/dbus-launch.x11 default-displaymanager auto /usr/lib/X11/displaymanagers/gdm [...]
🌐
Debian
wiki.debian.org › DebianAlternatives
DebianAlternatives - Debian Wiki
One way to find the syntax is to look at the postinst script of something already providing an alternative. If you have added the new alternative with a higher priority it will be automatically promoted to the default: $ update-alternatives --config www-browser There are 2 choices for the ...
Top answer
1 of 2
9

Basically it says to your machine to use this alternative of Jave JDK instead of the default one, which, in Linux systems, is OpenJDK.

A brief extract from the man page is better than any answer I could write:

update-alternatives creates, removes, maintains and displays information about the symbolic links comprising the Debian alternatives system.

It is possible for several programs fulfilling the same or similar functions to be installed on a single system at the same time. For example, many systems have several text editors installed at once. This gives choice to the users of a system, allowing each to use a different editor, if desired, but makes it difficult for a program to make a good choice for an editor to invoke if the user has not specified a particular preference.

Debian's alternatives system aims to solve this problem. A generic name in the filesystem is shared by all files providing interchangeable functionality. The alternatives system and the system administrator together determine which actual file is referenced by this generic name. For example, if the text editors ed(1) and nvi(1) are both installed on the system, the alternatives system will cause the generic name /usr/bin/editor to refer to /usr/bin/nvi by default. The system administrator can override this and cause it to refer to /usr/bin/ed instead, and the alternatives system will not alter this setting until explicitly requested to do so.

With --install you specified a link, "/usr/bin/java" a name "java" and a path "/usr/lib/java/JDK...." and you add a group of alternatives to the system. link is the generic name for the master link, name is the name of its symlink in the alternatives directory, and path is the alternative being introduced for the master link.

I hope to be clear enough, Here there is a post regarding java alternatives.

For the complete usage list I suggest to look at the same manual page, typing man update-alternatives on your OS shell;

2 of 2
0

i want to explain it for you from scratch ... if you have 2 or more versions of a program that starts with a same command in linux you can use update-alternatives command for determining the default version of that program and you can also change the default version of that command easily .. assume that you have 2 version of python on your system. python 2 & python 3. by default python command on linux starts the python2 interpreter on the shell . you think that python 2 is old and you want to use python 3 instead of python2 . one of the solution is that you enter python3 command on the shell and start the python interpreter that its version is more than 3 ... but you want to enter python command and shell recognize that you want to run python3 interpreter . here,update-alternatives command do it's work and determine the default version and versions of a program you want to use for a specific command .

i told you that python command start python 2 interpreter by default . you want to change it . follow the example :

sudo update-alternatives --install /usr/bin/python python /usr/bin/python3 1.

when you execute this command on linux you are telling to shell that after this time two links of two different programs are linked to python command on linux .. infact you install the python3 program on python command on linux and two programs exist at 1 command that you can change the defaults of these programs and run what of these programs you want by changing priority in command or configure it manually to set the default program ..

hope this is useful for you !

🌐
Arch Linux Man Pages
man.archlinux.org › man › update-alternatives.1.en
update-alternatives(1) — Arch manual pages
It is often useful for a number of alternatives to be synchronized, so that they are changed as a group; for example, when several versions of the vi(1) editor are installed, the manual page referenced by /usr/share/man/man1/vi.1 should correspond to the executable referenced by /usr/bin/vi. update-alternatives handles this by means of master and slave links; when the master is changed, any associated slaves are changed too.
Find elsewhere
🌐
Noman
noman.sh › en › pages › update-alternatives
update-alternatives command: noman - Man pages without the man
Manages symbolic links determining ... update-alternatives creates, removes, maintains, and displays information about symbolic links that determine which commands are run when a user enters a particular command name....
🌐
CommandLinux
commandlinux.com › home › man page › update-alternatives
Update-alternatives
May 13, 2026 - In the process, the master symlink and its slaves are updated to point to the highest priority installed alternatives. ... Display information about the link group. Information displayed includes the group’s mode (auto or manual), which alternative the master link currently points to, what other alternatives are available (and their corresponding slave alternatives), and the highest priority alternative currently installed.
🌐
DEV Community
dev.to › webduvet › how-to-manage-versions-using-update-alternatives-258e
How to manage versions using update-alternatives - DEV Community
November 24, 2022 - It is a tool provided by Debian based distributions which is designed to help to manage multiple versions or different implementations of a command or program, read more on Debian Alternatives. Update-alternatives in Debian based system like Ubuntu is used as default option by apt, however, it offers the command-line interface to interact with the settings and to add and remove entries manually.
🌐
Linux Manpages
man.cx › update-alternatives
update-alternatives [option...] command
This is done so that the system ... is a Good Thing. When each package providing a file with a particular functionality is installed, changed or removed, update-alternatives is called to update information about that file in the alternatives system....
🌐
Ubuntu Manpages
manpages.ubuntu.com › manpages › trusty › en › man8 › update-alternatives.8.html
Ubuntu Manpage: update-alternatives - maintain symbolic links determining default commands
In the process, the master symlink and its slaves are updated to point to the highest priority installed alternatives. --display · name Display information about the link group. Information displayed includes the group's mode (auto or manual), which alternative the master link currently points to, what other alternatives are available (and their corresponding slave alternatives), and the highest priority alternative currently installed.
🌐
Linux Hint
linuxhint.com › update_alternatives_ubuntu
How to Use update-alternatives Command on Ubuntu – Linux Hint
In auto mode, the alternatives selects the command/executable/alternative with the highest available priority by default. In manual mode, you select the default command/executable/alternative for the alternatives manually.
🌐
TecAdmin
tecadmin.net › linux-update-alternatives-command
Update-alternatives Command: A Comprehensive Guide for Linux Users – TecAdmin
April 26, 2025 - For example, you have 2 versions of Java installed on your system. Thyen you can install the alternatives as: sudo update-alternatives --install /usr/bin/java java /usr/lib/jvm/java-11-openjdk-amd64/bin/java 1100 sudo update-alternatives --install /usr/bin/java java /usr/lib/jvm/java-8-openjdk-amd64/bin/java 800
🌐
Reddit
reddit.com › r/linux4noobs › understanding update-alternatives
r/linux4noobs on Reddit: Understanding update-alternatives
August 2, 2019 -

(tl;dr at bottom)

Apologies for sounding dumb, but I'm trying to understand Ubuntu's update-alternatives by reading the man pages and I just can't seem to understand it.

I'm trying to set atom (/usr/bin/atom) as an alternative for editor. There are two ways the man pages seem to be telling me to do it, but I get an error on both that I don't totally understand:

$ sudo update-alternatives --set editor /usr/bin/atom
update-alternatives: error: alternative /usr/bin/atom for editor not registered; not setting

There's also update-alternatives --install <link> <name> <path> <priority>, but I can't figure out what it wants for <link>. For all other alternatives it seems to just be a symlink to <path>, which is a bit strange, but I tried creating a symlink and I got an error Okay, now I'm not getting the same error, but it was something like "Max recursion reached". Now I can set the editor alternative to atom, but nothing appears to be different when I try to open a text document.

I feel like I'm just misunderstanding the arguments... could I get some help, please?

TL;DR I want to set /usr/bin/atom as the editor alternative, how do I do it

🌐
Debian Manpages
manpages.debian.org › trixie › dpkg › update-alternatives(1)
update-alternatives(1) — dpkg — Debian trixie — Debian Manpages
It is often useful for a number of alternatives to be synchronized, so that they are changed as a group; for example, when several versions of the vi(1) editor are installed, the manual page referenced by /usr/share/man/man1/vi.1 should correspond to the executable referenced by /usr/bin/vi. update-alternatives handles this by means of master and slave links; when the master is changed, any associated slaves are changed too.
🌐
LinuxConfig
linuxconfig.org › home › how to set default programs using update-alternatives on debian-based distributions
How to set default programs using update-alternatives on Debian-based distributions
February 1, 2023 - To list all the groups of alternatives available on the system, we just invoke “update-alternatives” with the --get-selections option: ... arptables auto /usr/sbin/arptables-nft awk auto /usr/bin/mawk builtins.7.gz auto /usr/share/man/man7/bash-builtins.7.gz cpp auto /usr/bin/cpp default-GM.sf2 ...
Top answer
1 of 4
19

To answer your first question I'd like to hint you to --query:

   --query name
          Display information about the link group like --display does, but in a machine parseable way (see section QUERY FORMAT below).

Armed with this you will get the link source, e.g. in my case for java:

usr@srv % update-alternatives --query java
Name: java
Link: /usr/bin/java
[...]

So, you see my chain goes like /usr/bin/java -> /etc/alternatives/java -> ....

Unfortunately, I don't have an answer to your second question. I've been searching for a solution for this some time ago, but it seems that there is no simple workaround, yet. What you could do is writing some hack to parse the output of the --query call, maybe like this:

update-alternatives --query java | /bin/grep Link | cut -f 2 -d " "

which you could then use as input for the --install call. But since this is quite messy in my opinion I won't recommend it. Instead you might want to have a look at galternatives, a front-end to the alternatives system. Even if I don't like to use graphical stuff for such basic jobs it is quite convenient and I ended up using this tool instead of the command line tools.

EDIT

I've been curious how update-alternatives knows what's the command symlink and took a short look into the sources. Of course the alternatives system has to store the config for each group and it turns out that it's called administrative directory and written on the man page ;-)

You'll find this information in /var/lib/dpkg/alternatives (by default). The second line in each of these files defines the master link you're looking for. You may extract it like this:

usr@srv $ sed -ne 2p /var/lib/dpkg/alternatives/java
/usr/bin/java

However, this is just a workaround for those having an older version of update-alternatives.

2 of 4
5

Simpleton question here: Isn't the <link> always going to be the same one retrieved by a simple which [program] since that is the link that the system uses to call a program by command-line?

For instance, tracing back the links for pycharm I get:

user@computer:~$ which pycharm
/usr/bin/pycharm
user@computer:~$ ll /usr/bin/pycharm
lrwxrwxrwx 1 root root 25 Mar 12  2015 /usr/bin/pycharm -> /etc/alternatives/pycharm*
user@computer:~$ ll /etc/alternatives/pycharm 
lrwxrwxrwx 1 root root 43 Mar 12  2015 /etc/alternatives/pycharm -> /opt/pycharm-community-4.0.5/bin/pycharm.sh*

And I can then use:

sudo update-alternatives --install /usr/bin/pycharm pycharm /opt/pycharm-community-4.5.0/bin/pycharm.sh 0

For my new pycharm install.

Then maybe you could construct a script to use the output of which.

🌐
Unix.com
unix.com › man_page › suse › 8 › update-alternatives
update-alternatives(8) suse man page | unix.com
DESCRIPTION update-alternatives creates, removes, maintains and displays information about the symbolic links comprising the SUSE alternatives system. It is possible for several programs fulfilling the same or similar functions to be installed ...