The global.conf file is located in the Conan user home directory, e.g., [CONAN_HOME]/global.conf.

Introduction to configuration

global.conf is aimed to save some core/tools/user configuration variables that will be used by Conan. For instance:

  • Package ID modes.
  • General HTTP(python-requests) configuration.
  • Number of retries when downloading/uploading recipes.
  • Related tools configurations (used by toolchains, helpers, etc.)
  • Others (required Conan version, CLI non-interactive, etc.)

Let’s briefly explain the three types of existing configurations:

  • core.*: aimed to configure values of Conan core behavior (download retries, package ID modes, etc.). Only definable in global.conf file.
  • tools.*: aimed to configure values of Conan tools (toolchains, build helpers, etc.) used in your recipes. Definable in both global.conf and profiles.
  • user.*: aimed to define personal user configurations. They can define whatever user wants. Definable in both global.conf and profiles.

To list all the possible configurations available, run conan config list:

$ conan config list

core.cache:storage_path: Absolute path where the packages and database are stored Define path to a file download cache Number of concurrent threads to download packages Number of retries in case of failure when downloading from Conan server Seconds to wait between download attempts from Conan server
core.gzip:compresslevel: The Gzip compresion level for Conan artifacts (default=9) Path containing a custom Cacert file If defined, the proxies system env-vars will be discarded Path or tuple of files containing a client cert (and key) Maximum number of connection retries (requests library) List of urls to skip from proxies configuration Dictionary containing the proxy configuration Number of seconds without response to timeout (requests library)
core.package_id:default_build_mode: By default, 'None'
core.package_id:default_embed_mode: By default, 'full_mode'
core.package_id:default_non_embed_mode: By default, 'minor_mode'
core.package_id:default_python_mode: By default, 'minor_mode'
core.package_id:default_unknown_mode: By default, 'semver_mode'
core.upload:retry: Number of retries in case of failure when uploading to Conan server
core.upload:retry_wait: Seconds to wait between upload attempts to Conan server
core:allow_uppercase_pkg_names: Temporarily (will be removed in 2.X) allow uppercase names
core:default_build_profile: Defines the default build profile (None by default)
core:default_profile: Defines the default host profile ('default' by default)
core:non_interactive: Disable interactive user input, raises error if input necessary
core:required_conan_version: Raise if current version does not match the defined range. Argument for the CMAKE_ANDROID_NDK (boolean) Enable/Disable ARC Apple Clang flags (boolean) Enable/Disable Bitcode Apple Clang flags (boolean) Enable/Disable Visibility Apple Clang flags Path to the SDK to be used Bool value that indicates whether is possible to run a non-native app on the same architecture. It's used by 'can_run' tool List of extra C flags used by different toolchains like CMakeToolchain, AutotoolsToolchain and MesonToolchain Defines a Python dict-like with the compilers path to be used. Allowed keys {'c', 'cpp', 'cuda', 'objc', 'objcxx', 'rc', 'fortran', 'asm', 'hip', 'ispc'} List of extra CXX flags used by different toolchains like CMakeToolchain, AutotoolsToolchain and MesonToolchain List of extra definition flags used by different toolchains like CMakeToolchain and AutotoolsToolchain Force download of sources for every package List of extra flags used by CMakeToolchain for CMAKE_EXE_LINKER_FLAGS_INIT variable Default compile jobs number -jX Ninja, Make, /MP VS (default: max CPUs) List of linker script files to pass to the linker used by different toolchains like CMakeToolchain, AutotoolsToolchain, and MesonToolchain List of extra flags used by CMakeToolchain for CMAKE_SHARED_LINKER_FLAGS_INIT variable Do not execute CMake.test() and Meson.test() when enabled Pass the --sysroot=<> flag if available. (None by default) Verbosity of MSBuild and XCodeBuild build systems. Possible values are 'quiet', 'error', 'warning', 'notice', 'status', 'verbose', 'normal', 'debug', 'v', 'trace' and 'vv'
tools.cmake.cmake_layout:build_folder_vars: Settings and Options that will produce a different build folder and different CMake presets names
tools.cmake.cmaketoolchain:find_package_prefer_config: Argument for the CMAKE_FIND_PACKAGE_PREFER_CONFIG
tools.cmake.cmaketoolchain:generator: User defined CMake generator to use instead of default
tools.cmake.cmaketoolchain:system_name: Define CMAKE_SYSTEM_NAME in CMakeToolchain
tools.cmake.cmaketoolchain:system_processor: Define CMAKE_SYSTEM_PROCESSOR in CMakeToolchain
tools.cmake.cmaketoolchain:system_version: Define CMAKE_SYSTEM_VERSION in CMakeToolchain
tools.cmake.cmaketoolchain:toolchain_file: Use other existing file rather than conan_toolchain.cmake one
tools.cmake.cmaketoolchain:toolset_arch: Toolset architecture to be used as part of CMAKE_GENERATOR_TOOLSET in CMakeToolchain
tools.cmake.cmaketoolchain:user_toolchain: Inject existing user toolchains at the beginning of conan_toolchain.cmake
tools.env.virtualenv:powershell: If it is set to True it will generate powershell launchers if os=Windows Define the cache folder to store downloads from Number of retries in case of failure when downloading Seconds to wait between download attempts
tools.gnu:define_libcxx11_abi: Force definition of GLIBCXX_USE_CXX11_ABI=1 for libstdc++11
tools.gnu:host_triplet: Custom host triplet to pass to Autotools scripts
tools.gnu:make_program: Indicate path to make program
tools.gnu:pkg_config: Path to pkg-config executable used by PkgConfig build helper Defines Bazel rc-path Define Bazel config file List of existing configuration to be part of the package ID Defines the Intel oneAPI installation root path Custom arguments to be passed onto the|bat script from Intel oneAPI
tools.meson.mesontoolchain:backend: Any Meson backend: ninja, vs, vs2010, vs2012, vs2013, vs2015, vs2017, vs2019, xcode
tools.meson.mesontoolchain:extra_machine_files: List of paths for any additional native/cross file references to be appended to the existing Conan ones If Conan is already running inside bash terminal in Windows The path to the shell to run when conanfile.win_bash==True The subsystem to be used when conanfile.win_bash==True. Possible values: msys2, msys, cygwin, wsl, sfu VS install path, to avoid auto-detect via vswhere, like C:/Program Files (x86)/Microsoft Visual Studio/2019/Community. Use empty string to disable Argument for the /m when running msvc to build parallel projects Defines the IDE version when using the new msvc compiler Suppress MSBuild code analysis for patterns Dictionary with MSBuild compiler options
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.system.package_manager:tool: Default package manager tool: 'apt-get', 'yum', 'dnf', 'brew', 'pacman', 'choco', 'zypper', 'pkg' or 'pkgutil'

User/Tools configurations

Tools and user configurations can be defined in both the global.conf file and Conan profiles. They look like:

global.conf = 16
# User conf variable


Profiles values will have priority over globally defined ones in global.conf.

Configuration file template

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

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

The Python packages passed to render the template are os and platform for all platforms and distro in Linux platforms. Additionally, the variables conan_version and conan_home_folder are also available.

Configuration data types

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

# String
# Boolean
# Integer
# List of values["--flag1", "--flag2"]
# Dictionary{"ExceptionHandling": "Async"}

Configuration data operators

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.
# Define the value => ["-f1"]["-f1"]

# Append the value ["-f2"] => ["-f1", "-f2"]["-f2"]

# Prepend the value ["-f0"] => ["-f0", "-f1", "-f2"]["-f0"]

# Unset the value!

Configuration patterns

You can use package patterns to apply the configuration in those dependencies which are matching:

zlib:tools.cmake.cmaketoolchain:generator=Visual Studio 16 2019

This example shows you how to specify a general generator for all your packages except for zlib which is defining Visual Studio 16 2019 as its generator.

Besides that, it’s quite relevant to say that the order matters. So, if we change the order of the configuration lines above:

zlib:tools.cmake.cmaketoolchain:generator=Visual Studio 16 2019

The result is that you’re specifying a general generator for all your packages, and that’s it. The zlib line has no effect because it’s the first one evaluated, and after that, Conan is overriding that specific pattern with the most general one, so it deserves to pay special attention to the order.

Configuration of client certificates

Conan supports client TLS certificates. You can configure the path to your existing Cacert file and/or your client certificate (and the key) using the following configuration variables:

  • Path containing a custom Cacert file.
  • Path or tuple of files containing a client certificate (and the key). See more details in Python requests and Client Side Certificates

For instance:

[CONAN_HOME]/global.conf'/path/client.cert', '/path/client.key')