conan.tools.system.package_manager¶
The tools under conan.tools.system.package_manager are wrappers around some of the most
popular system package managers for different platforms. You can use them to invoke system
package managers in recipes and perform the most typical operations, like installing a
package, updating the package manager database or checking if a package is installed. By
default, when you invoke them they will not try to install anything on the system, to
change this behavior you can set the value of the tools.system.package_manager:mode
configuration.
You can use these tools inside the system_requirements()
method of your recipe, like:
from conan.tools.system.package_manager import Apt, Yum, PacMan, Zypper
def system_requirements(self):
# depending on the platform or the tools.system.package_manager:tool configuration
# only one of these will be executed
Apt(self).install(["libgl-dev"])
Yum(self).install(["libglvnd-devel"])
PacMan(self).install(["libglvnd"])
Zypper(self).install(["Mesa-libGL-devel"])
Conan will automatically choose which package manager to use by looking at the Operating
System name. In the example above, if we are running on Ubuntu Linux, Conan will ignore
all the calls except for the Apt()
one and will only try to install the packages using the
apt-get
tool. Conan uses the following mapping by default:
Apt for Linux with distribution names: ubuntu, debian, raspbian or linuxmint
Yum for Linux with distribution names: pidora, scientific, xenserver, amazon, oracle, amzn, almalinux or rocky
Dnf for Linux with distribution names: fedora, rhel, centos, mageia
Apk for Linux with distribution names: alpine
Brew for macOS
PacMan for Linux with distribution names: arch, manjaro and when using Windows with msys2
Chocolatey for Windows
Zypper for Linux with distribution names: opensuse, sles
Pkg for FreeBSD
PkgUtil for Solaris
You can override this default mapping and set the package manager tool you want to use by default setting the configuration property tools.system.package_manager:tool.
Methods available for system package manager tools¶
All these wrappers share three methods that represent the most common operations with a system package manager. They take the same form for all of the package managers except for Apt that also accepts the recommends argument for the install method.
install(self, packages, update=False, check=True, host_package=True):
try to install the list of packages passed as a parameter. If the parametercheck
isTrue
it will check if those packages are already installed before installing them. If the parameterupdate
isTrue
it will try to update the package manager database before checking and installing. Its behaviour is affected by the value oftools.system.package_manager:mode
configuration. If the parameterhost_package
isTrue
it will install the packages for the host machine architecture (the machine that will run the software), it has an effect when cross building. This method will return the return code of the executed commands.install_substitutes(packages_substitutes, update=False, check=True)
: try to install the list of lists of substitutes packages passed as a parameter, e.g.,[["pkg1", "pkg2"], ["pkg3"]]
. It succeeds if one of the substitutes list is completely installed, so it’s intended to be used when you have different packages for different distros. Internally, it’s calling the previousinstall(packages, update=update, check=check)
method, soupdate
andcheck
have the same purpose as above.update()
update the system package manager database. Its behaviour is affected by the value oftools.system.package_manager:mode
configuration.check(packages)
check if the list of packages passed as parameter are already installed. It will return a list with the packages that are missing.
Configuration properties that affect how system package managers are invoked¶
As explained above there are several [conf]
that
affect how these tools are invoked:
tools.system.package_manager:tool
: to choose which package manager tool you want to use by default:"apk"
,"apt-get"
,"yum"
,"dnf"
,"brew"
,"pacman"
,"choco"
,"zypper"
,"pkg"
or"pkgutil"
tools.system.package_manager:mode
: mode to use when invoking the package manager tool. There are two possible values:"check"
: it will just check for missing packages at most and will not try to update the package manager database or install any packages in any case. It will raise an error if required packages are not installed in the system. This is the default value."report"
: Just capture the.install()
calls to capture packages, but do not check nor install them. Never raises an error. Mostly useful forconan graph info
commands."report-installed"
: Report, without failing which packages are needed (same asreport
) and also check which of them are actually installed in the current system."install"
: it will allow Conan to perform update or install operations.
tools.system.package_manager:sudo
: Use sudo when invoking the package manager tools in Linux (False
by default)tools.system.package_manager:sudo_askpass
: Use the-A
argument if using sudo in Linux to invoke the system package manager (False
by default)
There are some specific arguments for each of these tools. Here is the complete reference:
conan.tools.system.package_manager.Apk¶
Will invoke the apk command. Enabled by default for Linux with distribution names: alpine.
Reference¶
- class Apk(conanfile, _arch_names=None)¶
Constructor method. Note that Apk does not support architecture names since Alpine Linux does not support multiarch. Therefore, the
arch_names
argument is ignored.- Parameters:
conanfile – the current recipe object. Always use
self
.
- check(*args, **kwargs)¶
Check if the list of packages passed as parameter are already installed.
- Parameters:
packages – list of packages to check.
- Returns:
list of packages from the packages argument that are not installed in the system.
- install(*args, **kwargs)¶
Will try to install the list of packages passed as a parameter. Its behaviour is affected by the value of
tools.system.package_manager:mode
configuration.- Parameters:
packages – try to install the list of packages passed as a parameter.
update – try to update the package manager database before checking and installing.
check – check if the packages are already installed before installing them.
- Returns:
the return code of the executed package manager command.
- install_substitutes(*args, **kwargs)¶
Will try to call the install() method with several lists of packages passed as a variable number of parameters. This is useful if, for example, the names of the packages are different from one distro or distro version to another. For example,
libxcb
forApt
is namedlibxcb-util-dev
in Ubuntu >= 15.0 andlibxcb-util0-dev
for other versions. You can call to:# will install the first list of packages that succeeds in the installation Apt.install_substitutes(["libxcb-util-dev"], ["libxcb-util0-dev"])
- Parameters:
packages_alternatives – try to install the list of packages passed as a parameter.
update – try to update the package manager database before checking and installing.
check – check if the packages are already installed before installing them.
- Returns:
the return code of the executed package manager command.
- update(*args, **kwargs)¶
Update the system package manager database. Its behaviour is affected by the value of
tools.system.package_manager:mode
configuration.- Returns:
the return code of the executed package manager update command.
Alpine Linux does not support multiple architectures in the same repository, so there is no mapping from Conan architectures to Alpine architectures.
conan.tools.system.package_manager.Apt¶
Will invoke the apt-get command. Enabled by default for Linux with distribution names: ubuntu, debian, raspbian and linuxmint.
Reference¶
- class Apt(conanfile, arch_names=None)¶
- Parameters:
conanfile – The current recipe object. Always use
self
.arch_names – This argument maps the Conan architecture setting with the package manager tool architecture names. It is
None
by default, which means that it will use a default mapping for the most common architectures. For example, if you are usingx86_64
Conan architecture setting, it will map this value toamd64
for Apt and try to install the<package_name>:amd64
package.
- install(packages, update=False, check=True, recommends=False, host_package=True)¶
Will try to install the list of packages passed as a parameter. Its behaviour is affected by the value of
tools.system.package_manager:mode
configuration.- Parameters:
packages – try to install the list of packages passed as a parameter.
update – try to update the package manager database before checking and installing.
check – check if the packages are already installed before installing them.
host_package – install the packages for the host machine architecture (the machine that will run the software), it has an effect when cross building.
recommends – if the parameter
recommends
isFalse
it will add the'--no-install-recommends'
argument to the apt-get command call.
- Returns:
the return code of the executed apt command.
- check(*args, **kwargs)¶
Check if the list of packages passed as parameter are already installed.
- Parameters:
packages – list of packages to check.
- Returns:
list of packages from the packages argument that are not installed in the system.
- install_substitutes(*args, **kwargs)¶
Will try to call the install() method with several lists of packages passed as a variable number of parameters. This is useful if, for example, the names of the packages are different from one distro or distro version to another. For example,
libxcb
forApt
is namedlibxcb-util-dev
in Ubuntu >= 15.0 andlibxcb-util0-dev
for other versions. You can call to:# will install the first list of packages that succeeds in the installation Apt.install_substitutes(["libxcb-util-dev"], ["libxcb-util0-dev"])
- Parameters:
packages_alternatives – try to install the list of packages passed as a parameter.
update – try to update the package manager database before checking and installing.
check – check if the packages are already installed before installing them.
- Returns:
the return code of the executed package manager command.
- update(*args, **kwargs)¶
Update the system package manager database. Its behaviour is affected by the value of
tools.system.package_manager:mode
configuration.- Returns:
the return code of the executed package manager update command.
You can pass the arch_names
argument to override the default Conan mapping like this:
...
def system_requirements(self):
apt = Apt(self, arch_names={"<conan_arch_setting>": "apt_arch_setting"})
apt.install(["libgl-dev"])
The default mapping that Conan uses for APT packages architecture is:
self._arch_names = {"x86_64": "x86_64",
"x86": "i?86",
"ppc32": "powerpc",
"ppc64le": "ppc64le",
"armv7": "armv7",
"armv7hf": "armv7hl",
"armv8": "aarch64",
"s390x": "s390x"} if arch_names is None else arch_names
conan.tools.system.package_manager.Yum¶
Will invoke the yum command. Enabled by default for Linux with distribution names: pidora, scientific, xenserver, amazon, oracle, amzn and almalinux.
Reference¶
- class Yum(conanfile, arch_names=None)¶
- Parameters:
conanfile – the current recipe object. Always use
self
.arch_names – this argument maps the Conan architecture setting with the package manager tool architecture names. It is
None
by default, which means that it will use a default mapping for the most common architectures. For example, if you are usingx86
Conan architecture setting, it will map this value toi?86
for Yum and try to install the<package_name>.i?86
package.
- check(*args, **kwargs)¶
Check if the list of packages passed as parameter are already installed.
- Parameters:
packages – list of packages to check.
- Returns:
list of packages from the packages argument that are not installed in the system.
- install(*args, **kwargs)¶
Will try to install the list of packages passed as a parameter. Its behaviour is affected by the value of
tools.system.package_manager:mode
configuration.- Parameters:
packages – try to install the list of packages passed as a parameter.
update – try to update the package manager database before checking and installing.
check – check if the packages are already installed before installing them.
- Returns:
the return code of the executed package manager command.
- install_substitutes(*args, **kwargs)¶
Will try to call the install() method with several lists of packages passed as a variable number of parameters. This is useful if, for example, the names of the packages are different from one distro or distro version to another. For example,
libxcb
forApt
is namedlibxcb-util-dev
in Ubuntu >= 15.0 andlibxcb-util0-dev
for other versions. You can call to:# will install the first list of packages that succeeds in the installation Apt.install_substitutes(["libxcb-util-dev"], ["libxcb-util0-dev"])
- Parameters:
packages_alternatives – try to install the list of packages passed as a parameter.
update – try to update the package manager database before checking and installing.
check – check if the packages are already installed before installing them.
- Returns:
the return code of the executed package manager command.
- update(*args, **kwargs)¶
Update the system package manager database. Its behaviour is affected by the value of
tools.system.package_manager:mode
configuration.- Returns:
the return code of the executed package manager update command.
The default mapping Conan uses for Yum packages architecture is:
self._arch_names = {"x86_64": "x86_64",
"x86": "i?86",
"ppc32": "powerpc",
"ppc64le": "ppc64le",
"armv7": "armv7",
"armv7hf": "armv7hl",
"armv8": "aarch64",
"s390x": "s390x"} if arch_names is None else arch_names
conan.tools.system.package_manager.Dnf¶
Will invoke the dnf command. Enabled by default for Linux with distribution names: fedora, rhel, centos and mageia. This tool has exactly the same default values, constructor and methods than the Yum tool.
conan.tools.system.package_manager.PacMan¶
Will invoke the pacman command. Enabled by default for Linux with distribution names: arch, manjaro and when using Windows with msys2
Reference¶
- class PacMan(conanfile, arch_names=None)¶
- Parameters:
conanfile – the current recipe object. Always use
self
.arch_names – this argument maps the Conan architecture setting with the package manager tool architecture names. It is
None
by default, which means that it will use a default mapping for the most common architectures. If you are usingx86
Conan architecture setting, it will map this value tolib32
for PacMan and try to install the<package_name>-lib32
package.
- check(*args, **kwargs)¶
Check if the list of packages passed as parameter are already installed.
- Parameters:
packages – list of packages to check.
- Returns:
list of packages from the packages argument that are not installed in the system.
- install(*args, **kwargs)¶
Will try to install the list of packages passed as a parameter. Its behaviour is affected by the value of
tools.system.package_manager:mode
configuration.- Parameters:
packages – try to install the list of packages passed as a parameter.
update – try to update the package manager database before checking and installing.
check – check if the packages are already installed before installing them.
- Returns:
the return code of the executed package manager command.
- install_substitutes(*args, **kwargs)¶
Will try to call the install() method with several lists of packages passed as a variable number of parameters. This is useful if, for example, the names of the packages are different from one distro or distro version to another. For example,
libxcb
forApt
is namedlibxcb-util-dev
in Ubuntu >= 15.0 andlibxcb-util0-dev
for other versions. You can call to:# will install the first list of packages that succeeds in the installation Apt.install_substitutes(["libxcb-util-dev"], ["libxcb-util0-dev"])
- Parameters:
packages_alternatives – try to install the list of packages passed as a parameter.
update – try to update the package manager database before checking and installing.
check – check if the packages are already installed before installing them.
- Returns:
the return code of the executed package manager command.
- update(*args, **kwargs)¶
Update the system package manager database. Its behaviour is affected by the value of
tools.system.package_manager:mode
configuration.- Returns:
the return code of the executed package manager update command.
The default mapping Conan uses for PacMan packages architecture is:
self._arch_names = {"x86": "lib32"} if arch_names is None else arch_names
conan.tools.system.package_manager.Zypper¶
Will invoke the zypper command. Enabled by default for Linux with distribution names: opensuse, sles.
Reference¶
- class Zypper(conanfile)¶
- Parameters:
conanfile – The current recipe object. Always use
self
.
- check(*args, **kwargs)¶
Check if the list of packages passed as parameter are already installed.
- Parameters:
packages – list of packages to check.
- Returns:
list of packages from the packages argument that are not installed in the system.
- install(*args, **kwargs)¶
Will try to install the list of packages passed as a parameter. Its behaviour is affected by the value of
tools.system.package_manager:mode
configuration.- Parameters:
packages – try to install the list of packages passed as a parameter.
update – try to update the package manager database before checking and installing.
check – check if the packages are already installed before installing them.
- Returns:
the return code of the executed package manager command.
- install_substitutes(*args, **kwargs)¶
Will try to call the install() method with several lists of packages passed as a variable number of parameters. This is useful if, for example, the names of the packages are different from one distro or distro version to another. For example,
libxcb
forApt
is namedlibxcb-util-dev
in Ubuntu >= 15.0 andlibxcb-util0-dev
for other versions. You can call to:# will install the first list of packages that succeeds in the installation Apt.install_substitutes(["libxcb-util-dev"], ["libxcb-util0-dev"])
- Parameters:
packages_alternatives – try to install the list of packages passed as a parameter.
update – try to update the package manager database before checking and installing.
check – check if the packages are already installed before installing them.
- Returns:
the return code of the executed package manager command.
- update(*args, **kwargs)¶
Update the system package manager database. Its behaviour is affected by the value of
tools.system.package_manager:mode
configuration.- Returns:
the return code of the executed package manager update command.
conan.tools.system.package_manager.Brew¶
Will invoke the brew command. Enabled by default for macOS.
Reference¶
- class Brew(conanfile)¶
- Parameters:
conanfile – The current recipe object. Always use
self
.
- check(*args, **kwargs)¶
Check if the list of packages passed as parameter are already installed.
- Parameters:
packages – list of packages to check.
- Returns:
list of packages from the packages argument that are not installed in the system.
- install(*args, **kwargs)¶
Will try to install the list of packages passed as a parameter. Its behaviour is affected by the value of
tools.system.package_manager:mode
configuration.- Parameters:
packages – try to install the list of packages passed as a parameter.
update – try to update the package manager database before checking and installing.
check – check if the packages are already installed before installing them.
- Returns:
the return code of the executed package manager command.
- install_substitutes(*args, **kwargs)¶
Will try to call the install() method with several lists of packages passed as a variable number of parameters. This is useful if, for example, the names of the packages are different from one distro or distro version to another. For example,
libxcb
forApt
is namedlibxcb-util-dev
in Ubuntu >= 15.0 andlibxcb-util0-dev
for other versions. You can call to:# will install the first list of packages that succeeds in the installation Apt.install_substitutes(["libxcb-util-dev"], ["libxcb-util0-dev"])
- Parameters:
packages_alternatives – try to install the list of packages passed as a parameter.
update – try to update the package manager database before checking and installing.
check – check if the packages are already installed before installing them.
- Returns:
the return code of the executed package manager command.
- update(*args, **kwargs)¶
Update the system package manager database. Its behaviour is affected by the value of
tools.system.package_manager:mode
configuration.- Returns:
the return code of the executed package manager update command.
conan.tools.system.package_manager.Pkg¶
Will invoke the pkg command. Enabled by default for Linux with distribution names: freebsd.
Reference¶
- class Pkg(conanfile)¶
- Parameters:
conanfile – The current recipe object. Always use
self
.
- check(*args, **kwargs)¶
Check if the list of packages passed as parameter are already installed.
- Parameters:
packages – list of packages to check.
- Returns:
list of packages from the packages argument that are not installed in the system.
- install(*args, **kwargs)¶
Will try to install the list of packages passed as a parameter. Its behaviour is affected by the value of
tools.system.package_manager:mode
configuration.- Parameters:
packages – try to install the list of packages passed as a parameter.
update – try to update the package manager database before checking and installing.
check – check if the packages are already installed before installing them.
- Returns:
the return code of the executed package manager command.
- install_substitutes(*args, **kwargs)¶
Will try to call the install() method with several lists of packages passed as a variable number of parameters. This is useful if, for example, the names of the packages are different from one distro or distro version to another. For example,
libxcb
forApt
is namedlibxcb-util-dev
in Ubuntu >= 15.0 andlibxcb-util0-dev
for other versions. You can call to:# will install the first list of packages that succeeds in the installation Apt.install_substitutes(["libxcb-util-dev"], ["libxcb-util0-dev"])
- Parameters:
packages_alternatives – try to install the list of packages passed as a parameter.
update – try to update the package manager database before checking and installing.
check – check if the packages are already installed before installing them.
- Returns:
the return code of the executed package manager command.
- update(*args, **kwargs)¶
Update the system package manager database. Its behaviour is affected by the value of
tools.system.package_manager:mode
configuration.- Returns:
the return code of the executed package manager update command.
conan.tools.system.package_manager.PkgUtil¶
Will invoke the pkgutil command. Enabled by default for Solaris.
Reference¶
- class PkgUtil(conanfile)¶
- Parameters:
conanfile – The current recipe object. Always use
self
.
- check(*args, **kwargs)¶
Check if the list of packages passed as parameter are already installed.
- Parameters:
packages – list of packages to check.
- Returns:
list of packages from the packages argument that are not installed in the system.
- install(*args, **kwargs)¶
Will try to install the list of packages passed as a parameter. Its behaviour is affected by the value of
tools.system.package_manager:mode
configuration.- Parameters:
packages – try to install the list of packages passed as a parameter.
update – try to update the package manager database before checking and installing.
check – check if the packages are already installed before installing them.
- Returns:
the return code of the executed package manager command.
- install_substitutes(*args, **kwargs)¶
Will try to call the install() method with several lists of packages passed as a variable number of parameters. This is useful if, for example, the names of the packages are different from one distro or distro version to another. For example,
libxcb
forApt
is namedlibxcb-util-dev
in Ubuntu >= 15.0 andlibxcb-util0-dev
for other versions. You can call to:# will install the first list of packages that succeeds in the installation Apt.install_substitutes(["libxcb-util-dev"], ["libxcb-util0-dev"])
- Parameters:
packages_alternatives – try to install the list of packages passed as a parameter.
update – try to update the package manager database before checking and installing.
check – check if the packages are already installed before installing them.
- Returns:
the return code of the executed package manager command.
- update(*args, **kwargs)¶
Update the system package manager database. Its behaviour is affected by the value of
tools.system.package_manager:mode
configuration.- Returns:
the return code of the executed package manager update command.
conan.tools.system.package_manager.Chocolatey¶
Will invoke the choco command. Enabled by default for Windows.
Reference¶
- class Chocolatey(conanfile)¶
- Parameters:
conanfile – The current recipe object. Always use
self
.
- check(*args, **kwargs)¶
Check if the list of packages passed as parameter are already installed.
- Parameters:
packages – list of packages to check.
- Returns:
list of packages from the packages argument that are not installed in the system.
- install(*args, **kwargs)¶
Will try to install the list of packages passed as a parameter. Its behaviour is affected by the value of
tools.system.package_manager:mode
configuration.- Parameters:
packages – try to install the list of packages passed as a parameter.
update – try to update the package manager database before checking and installing.
check – check if the packages are already installed before installing them.
- Returns:
the return code of the executed package manager command.
- install_substitutes(*args, **kwargs)¶
Will try to call the install() method with several lists of packages passed as a variable number of parameters. This is useful if, for example, the names of the packages are different from one distro or distro version to another. For example,
libxcb
forApt
is namedlibxcb-util-dev
in Ubuntu >= 15.0 andlibxcb-util0-dev
for other versions. You can call to:# will install the first list of packages that succeeds in the installation Apt.install_substitutes(["libxcb-util-dev"], ["libxcb-util0-dev"])
- Parameters:
packages_alternatives – try to install the list of packages passed as a parameter.
update – try to update the package manager database before checking and installing.
check – check if the packages are already installed before installing them.
- Returns:
the return code of the executed package manager command.
- update(*args, **kwargs)¶
Update the system package manager database. Its behaviour is affected by the value of
tools.system.package_manager:mode
configuration.- Returns:
the return code of the executed package manager update command.