global.conf

Warning

This new configuration mechanism is an experimental feature subject to breaking changes in future releases.

The global.conf file is located in the Conan user home directory.

Global configuration

core:required_conan_version = expression allows defining a version expression like >=1.30. Conan will raise an error if its current version does not satisfy the condition
core.package_id:msvc_visual_incompatible allows opting-out the fallback from the new msvc compiler to the Visual Studio compiler existing binaries
core:default_profile defines the default host profile (‘default’ by default)
core:default_build_profile defines the default build profile (None by default)

Tools configurations

Tools and user configurations allows them to be defined both in the global.conf file and in profile files. Profile values will have priority over globally defined ones in global.conf, and can be defined as:

[settings]
...

[conf]
tools.microsoft.msbuild:verbosity=Diagnostic
tools.microsoft.msbuild:max_cpu_count=2
tools.microsoft.msbuild:vs_version = 16
tools.build:jobs=10

To list all possible configurations available, run conan config list.

$ conan config list
Supported Conan *experimental* global.conf and [conf] properties:
core:required_conan_version: Raise if current version does not match the defined range.
core.package_id:msvc_visual_incompatible: Allows opting-out the fallback from the new msvc compiler to the Visual Studio compiler existing binaries
core:default_profile: Defines the default host profile ('default' by default)
core:default_build_profile: Defines the default build profile (None by default)
tools.android:ndk_path: Argument for the CMAKE_ANDROID_NDK
tools.build:skip_test: Do not execute CMake.test() and Meson.test() when enabled
tools.build:jobs: Default compile jobs number -jX Ninja, Make, /MP VS (default: max CPUs)
tools.cmake.cmaketoolchain:generator: User defined CMake generator to use instead of default
tools.cmake.cmaketoolchain:find_package_prefer_config: Argument for the CMAKE_FIND_PACKAGE_PREFER_CONFIG
tools.cmake.cmaketoolchain:toolchain_file: Use other existing file rather than conan_toolchain.cmake one
tools.cmake.cmaketoolchain:user_toolchain: Inject existing user toolchains at the beginning of conan_toolchain.cmake
tools.cmake.cmaketoolchain:system_name: Define CMAKE_SYSTEM_NAME in CMakeToolchain
tools.cmake.cmaketoolchain:system_version: Define CMAKE_SYSTEM_VERSION in CMakeToolchain
tools.cmake.cmaketoolchain:system_processor: Define CMAKE_SYSTEM_PROCESSOR in CMakeToolchain
tools.env.virtualenv:auto_use: Automatically activate virtualenv file generation
tools.files.download:retry: Number of retries in case of failure when downloading
tools.files.download:retry_wait: Seconds to wait between download attempts
tools.gnu:make_program: Indicate path to make program
tools.gnu:define_libcxx11_abi: Force definition of GLIBCXX_USE_CXX11_ABI=1 for libstdc++11
tools.google.bazel:configs: Define Bazel config file
tools.google.bazel:bazelrc_path: Defines Bazel rc-path
tools.microsoft.msbuild:verbosity: Verbosity level for MSBuild: 'Quiet', 'Minimal', 'Normal', 'Detailed', 'Diagnostic'
tools.microsoft.msbuild:vs_version: Defines the IDE version when using the new msvc compiler
tools.microsoft.msbuild:max_cpu_count: Argument for the /m when running msvc to build parallel projects
tools.microsoft.msbuild:installation_path: VS install path, to avoid auto-detect via vswhere, like C:/Program Files (x86)/Microsoft Visual Studio/2019/Community
tools.microsoft.msbuilddeps:exclude_code_analysis: Suppress MSBuild code analysis for patterns
tools.microsoft.msbuildtoolchain:compile_options: Dictionary with MSBuild compiler options
tools.intel:installation_path: Defines the Intel oneAPI installation root path
tools.intel:setvars_args: Custom arguments to be passed onto the setvars.sh|bat script from Intel oneAPI
tools.system.package_manager:tool: Default package manager tool: 'apt-get', 'yum', 'dnf', 'brew', 'pacman', 'choco', 'zypper', 'pkg' or 'pkgutil'
tools.system.package_manager:mode: Mode for package_manager tools: 'check' or 'install'
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)
tools.apple.xcodebuild:verbosity: Verbosity level for xcodebuild: 'verbose' or 'quiet
tools.build:cxxflags: List of extra CXX flags used by different toolchains like CMakeToolchain, AutotoolsToolchain and MesonToolchain
tools.build:cflags: List of extra C flags used by different toolchains like CMakeToolchain, AutotoolsToolchain and MesonToolchain
tools.build:defines: List of extra definition flags used by different toolchains like CMakeToolchain and AutotoolsToolchain
tools.build:sharedlinkflags: List of extra flags used by CMakeToolchain for CMAKE_SHARED_LINKER_FLAGS_INIT variable
tools.build:exelinkflags: List of extra flags used by CMakeToolchain for CMAKE_EXE_LINKER_FLAGS_INIT variable

Configuration file template

Available since: 1.46.0

It is possible to use jinja2 template engine for global.conf. When Conan loads this file, immediately parses and renders the template, which must result in a standard tools-configuration text.

# Using all the cores automatically
tools.build:jobs={{os.cpu_count()}}
# Using the current OS
user.myconf.system:name = {{platform.system()}}

Note

The Python packages passed to render the template are only os and platform.

Configuration data types

Available since: 1.46.0

All the values will be interpreted by Conan as the result of the python built-in eval() function:

# String
tools.microsoft.msbuild:verbosity=Diagnostic
# Boolean
tools.system.package_manager:sudo=True
# Integer
tools.microsoft.msbuild:max_cpu_count=2
# List of values
user.myconf.build:ldflags=["--flag1", "--flag2"]
# Dictionary
tools.microsoft.msbuildtoolchain:compile_options={"ExceptionHandling": "Async"}

Configuration data operators

Available since: 1.46.0

It’s also possible to use some extra operators when you’re composing tool configurations in your global.conf or any of your profiles:

+= == append: appends values at the end of the existing value (only for lists).
=+ == prepend: puts values at the beginning of the existing value (only for lists).
=! == unset: gets rid of any configuration value.

myprofile

[settings]
...

[conf]
# Define the value => ["-f1"]
user.myconf.build:flags=["-f1"]

# Append the value ["-f2"] => ["-f1", "-f2"]
user.myconf.build:flags+=["-f2"]

# Prepend the value ["-f0"] => ["-f0", "-f1", "-f2"]
user.myconf.build:flags=+["-f0"]

# Unset the value
user.myconf.build:flags=!

Configuration in your profiles

Let’s see a little bit more complex example trying different configurations coming from the global.conf and a simple profile:

global.conf

# Defining several lists
user.myconf.build:ldflags=["--flag1 value1"]
user.myconf.build:cflags=["--flag1 value1"]

myprofile

[settings]
...

[conf]
# Appending values into the existing list
user.myconf.build:ldflags+=["--flag2 value2"]

# Unsetting the existing value (it'd be like we define it as an empty value)
user.myconf.build:cflags=!

# Prepending values into the existing list
user.myconf.build:ldflags=+["--prefix prefix-value"]

Running, for instance, conan install . -pr myprofile, the configuration output will be something like:

...
Configuration:
[settings]
[options]
[build_requires]
[env]
[conf]
user.myconf.build:cflags=!
user.myconf.build:ldflags=['--prefix prefix-value', '--flag1 value1', '--flag2 value2']
...

Configuration in your recipes

From Conan 1.46, the user interface to manage the configurations in your recipes has been improved. The self.conf_info object has the following methods available:

get(name, default=None, check_type=None): gets the value for the given configuration name. Besides that you can pass check_type to check the Python type matches with the value type returned, e.g., check_type=list. If the configuration does not exist, default will be returned instead. Notice that this default value won’t be affected by the check_type=list param.
pop(name, default=None): removes (if exists) the configuration name given. If the configuration does not exist, default will be returned instead.
define(name, value): sets value for the given configuration name. If it already exists, the configuration will be overwritten with the new value.
append(name, value): (only available for list) appends value into the existing list for the given configuration name. If the list does not exist yet, it’ll be created with the value given by default. value can be a list or a single value.
prepend(name, value): (only available for list) prepends value into the existing list for the given configuration name. If the list does not exist yet, it’ll be created with the value given by default. value can be a list or a single value.
update(name, value): (only available for dict) updates the existing dictionary with value for the given configuration name. If the dict does not exist yet, it’ll be created with the value given by default. value must be another dictionary.
remove(name, value): (only available for dict and list) removes value from the existing value for the given configuration name.
unset(name): removes any existing value for the given configuration name. It’s behaving like using define(name, None).

This example illustrates all of these methods:

import os
from conans import ConanFile

class Pkg(ConanFile):
    name = "pkg"

    def package_info(self):
        # Setting values
        self.conf_info.define("tools.microsoft.msbuild:verbosity", "Diagnostic")
        self.conf_info.define("tools.system.package_manager:sudo", True)
        self.conf_info.define("tools.microsoft.msbuild:max_cpu_count", 2)
        self.conf_info.define("user.myconf.build:ldflags", ["--flag1", "--flag2"])
        self.conf_info.define("tools.microsoft.msbuildtoolchain:compile_options", {"ExceptionHandling": "Async"})
        # Getting values
        self.conf_info.get("tools.microsoft.msbuild:verbosity")  # == "Diagnostic"
        # Getting default values from configurations that don't exist yet
        self.conf_info.get("user.myotherconf.build:cxxflags", default=["--flag3"])  # == ["--flag3"]
        # Getting values and ensuring the gotten type is the passed one otherwise an exception will be raised
        self.conf_info.get("tools.system.package_manager:sudo", check_type=bool)  # == True
        self.conf_info.get("tools.system.package_manager:sudo", check_type=int)  # ERROR! It raises a ConanException
        # Modifying configuration list-like values
        self.conf_info.append("user.myconf.build:ldflags", "--flag3")  # == ["--flag1", "--flag2", "--flag3"]
        self.conf_info.prepend("user.myconf.build:ldflags", "--flag0")  # == ["--flag0", "--flag1", "--flag2", "--flag3"]
        # Modifying configuration dict-like values
        self.conf_info.update("tools.microsoft.msbuildtoolchain:compile_options", {"ExpandAttributedSource": "false"})
        # Unset any value
        self.conf_info.unset("tools.microsoft.msbuildtoolchain:compile_options")
        # Remove
        self.conf_info.remove("user.myconf.build:ldflags", "--flag1")  # == ["--flag0", "--flag2", "--flag3"]
        # Removing completely the configuration
        self.conf_info.pop("tools.system.package_manager:sudo")

Important

Legacy configuration methods to set/get values like self.conf_info["xxxxx"] = "yyyyy" and v = self.conf_info["xxxxx"] are deprecated since Conan 1.46 version. Use self.conf_info.define("xxxxx", "yyyyy") and v = self.conf_info.get("xxxxx") instead like the example above.

Configuration from tool_requires

From Conan 1.37, it is possible to define configuration in packages that are tool_requires. For example, assuming there is a package that bundles the AndroidNDK, it could define the location of such NDK to the tools.android:ndk_path configuration as:

import os
from conans import ConanFile

class Pkg(ConanFile):
    name = "android_ndk"

    def package_info(self):
        self.conf_info.define("tools.android:ndk_path", os.path.join(self.package_folder, "ndk"))

Note that this only propagates from the immediate, direct tool_requires of a recipe.