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:

conanfile.py

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 parameter check is True it will check if those packages are already installed before installing them. If the parameter update is True it will try to update the package manager database before checking and installing. Its behaviour is affected by the value of tools.system.package_manager:mode configuration. If the parameter host_package is True 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 previous install(packages, update=update, check=check) method, so update and check have the same purpose as above.

• update() update the system package manager database. Its behaviour is affected by the value of tools.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 for conan graph info commands.

  • "report-installed": Report, without failing which packages are needed (same as report) 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 for Apt is named libxcb-util-dev in Ubuntu >= 15.0 and libxcb-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 using x86_64 Conan architecture setting, it will map this value to amd64 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 is False 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 for Apt is named libxcb-util-dev in Ubuntu >= 15.0 and libxcb-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:

conanfile.py

...
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 using x86 Conan architecture setting, it will map this value to i?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 for Apt is named libxcb-util-dev in Ubuntu >= 15.0 and libxcb-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 using x86 Conan architecture setting, it will map this value to lib32 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 for Apt is named libxcb-util-dev in Ubuntu >= 15.0 and libxcb-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 for Apt is named libxcb-util-dev in Ubuntu >= 15.0 and libxcb-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 for Apt is named libxcb-util-dev in Ubuntu >= 15.0 and libxcb-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 for Apt is named libxcb-util-dev in Ubuntu >= 15.0 and libxcb-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 for Apt is named libxcb-util-dev in Ubuntu >= 15.0 and libxcb-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 for Apt is named libxcb-util-dev in Ubuntu >= 15.0 and libxcb-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.