global.conf

The global.conf file is located in the Conan user home directory, e.g., [CONAN_HOME]/global.conf. If it does not already exist, a default one is automatically created.

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:

  1. $ conan config list
  2. core.cache:storage_path: Absolute path where the packages and database are stored
  3. core.download:download_cache: Define path to a file download cache
  4. core.download:parallel: Number of concurrent threads to download packages
  5. core.download:retry: Number of retries in case of failure when downloading from Conan server
  6. core.download:retry_wait: Seconds to wait between download attempts from Conan server
  7. core.gzip:compresslevel: The Gzip compression level for Conan artifacts (default=9)
  8. core.net.http:cacert_path: Path containing a custom Cacert file
  9. core.net.http:clean_system_proxy: If defined, the proxies system env-vars will be discarded
  10. core.net.http:client_cert: Path or tuple of files containing a client cert (and key)
  11. core.net.http:max_retries: Maximum number of connection retries (requests library)
  12. core.net.http:no_proxy_match: List of urls to skip from proxies configuration
  13. core.net.http:proxies: Dictionary containing the proxy configuration
  14. core.net.http:timeout: Number of seconds without response to timeout (requests library)
  15. core.package_id:config_mode: How the 'config_version' affects binaries. By default 'None'
  16. core.package_id:default_build_mode: By default, 'None'
  17. core.package_id:default_embed_mode: By default, 'full_mode'
  18. core.package_id:default_non_embed_mode: By default, 'minor_mode'
  19. core.package_id:default_python_mode: By default, 'minor_mode'
  20. core.package_id:default_unknown_mode: By default, 'semver_mode'
  21. core.scm:excluded: List of excluded patterns for builtin git dirty checks
  22. core.sources:download_cache: Folder to store the sources backup
  23. core.sources:download_urls: List of URLs to download backup sources from
  24. core.sources:exclude_urls: URLs which will not be backed up
  25. core.sources:upload_url: Remote URL to upload backup sources to
  26. core.upload:parallel: Number of concurrent threads to upload packages
  27. core.upload:retry: Number of retries in case of failure when uploading to Conan server
  28. core.upload:retry_wait: Seconds to wait between upload attempts to Conan server
  29. core.version_ranges:resolve_prereleases: Whether version ranges can resolve to pre-releases or not
  30. core:allow_uppercase_pkg_names: Temporarily (will be removed in 2.X) allow uppercase names
  31. core:default_build_profile: Defines the default build profile ('default' by default)
  32. core:default_profile: Defines the default host profile ('default' by default)
  33. core:non_interactive: Disable interactive user input, raises error if input necessary
  34. core:required_conan_version: Raise if current version does not match the defined range.
  35. core:skip_warnings: Do not show warnings matching any of the patterns in this list. Current warning tags are 'network', 'deprecated'
  36. core:warnings_as_errors: Treat warnings matching any of the patterns in this list as errors and then raise an exception. Current warning tags are 'network', 'deprecated'
  37. tools.android:cmake_legacy_toolchain: Define to explicitly pass ANDROID_USE_LEGACY_TOOLCHAIN_FILE in CMake toolchain
  38. tools.android:ndk_path: Argument for the CMAKE_ANDROID_NDK
  39. tools.apple:enable_arc: (boolean) Enable/Disable ARC Apple Clang flags
  40. tools.apple:enable_bitcode: (boolean) Enable/Disable Bitcode Apple Clang flags
  41. tools.apple:enable_visibility: (boolean) Enable/Disable Visibility Apple Clang flags
  42. tools.apple:sdk_path: Path to the SDK to be used
  43. tools.build.cross_building:can_run: (boolean) Indicates whether is possible to run a non-native app on the same architecture. It's used by 'can_run' tool
  44. tools.build.cross_building:cross_build: (boolean) Decides whether cross-building or not regardless of arch/OS settings. Used by 'cross_building' tool
  45. tools.build:cflags: List of extra C flags used by different toolchains like CMakeToolchain, AutotoolsToolchain and MesonToolchain
  46. tools.build:compiler_executables: Defines a Python dict-like with the compilers path to be used. Allowed keys {'c', 'cpp', 'cuda', 'objc', 'objcxx', 'rc', 'fortran', 'asm', 'hip', 'ispc', 'ld', 'ar'}
  47. tools.build:cxxflags: List of extra CXX flags used by different toolchains like CMakeToolchain, AutotoolsToolchain and MesonToolchain
  48. tools.build:defines: List of extra definition flags used by different toolchains like CMakeToolchain, AutotoolsToolchain and MesonToolchain
  49. tools.build:download_source: Force download of sources for every package
  50. tools.build:exelinkflags: List of extra flags used by CMakeToolchain for CMAKE_EXE_LINKER_FLAGS_INIT variable
  51. tools.build:jobs: Default compile jobs number -jX Ninja, Make, /MP VS (default: max CPUs)
  52. tools.build:linker_scripts: List of linker script files to pass to the linker used by different toolchains like CMakeToolchain, AutotoolsToolchain, and MesonToolchain
  53. tools.build:sharedlinkflags: List of extra flags used by CMakeToolchain for CMAKE_SHARED_LINKER_FLAGS_INIT variable
  54. tools.build:skip_test: Do not execute CMake.test() and Meson.test() when enabled
  55. tools.build:sysroot: Pass the --sysroot=<tools.build:sysroot> flag if available. (None by default)
  56. tools.build:verbosity: Verbosity of build systems if set. Possible values are 'quiet' and 'verbose'
  57. tools.cmake.cmake_layout:build_folder: (Experimental) Allow configuring the base folder of the build for local builds
  58. tools.cmake.cmake_layout:build_folder_vars: Settings and Options that will produce a different build folder and different CMake presets names
  59. tools.cmake.cmake_layout:test_folder: (Experimental) Allow configuring the base folder of the build for test_package
  60. tools.cmake.cmaketoolchain:enabled_blocks: Select the specific blocks to use in the conan_toolchain.cmake
  61. tools.cmake.cmaketoolchain:extra_variables: Dictionary with variables to be injected in CMakeToolchain (potential override of CMakeToolchain defined variables)
  62. tools.cmake.cmaketoolchain:find_package_prefer_config: Argument for the CMAKE_FIND_PACKAGE_PREFER_CONFIG
  63. tools.cmake.cmaketoolchain:generator: User defined CMake generator to use instead of default
  64. tools.cmake.cmaketoolchain:presets_environment: String to define wether to add or not the environment section to the CMake presets. Empty by default, will generate the environment section in CMakePresets. Can take values: 'disabled'.
  65. tools.cmake.cmaketoolchain:system_name: Define CMAKE_SYSTEM_NAME in CMakeToolchain
  66. tools.cmake.cmaketoolchain:system_processor: Define CMAKE_SYSTEM_PROCESSOR in CMakeToolchain
  67. tools.cmake.cmaketoolchain:system_version: Define CMAKE_SYSTEM_VERSION in CMakeToolchain
  68. tools.cmake.cmaketoolchain:toolchain_file: Use other existing file rather than conan_toolchain.cmake one
  69. tools.cmake.cmaketoolchain:toolset_arch: Toolset architecture to be used as part of CMAKE_GENERATOR_TOOLSET in CMakeToolchain
  70. tools.cmake.cmaketoolchain:toolset_cuda: (Experimental) Path to a CUDA toolset to use, or version if installed at the system level
  71. tools.cmake.cmaketoolchain:user_toolchain: Inject existing user toolchains at the beginning of conan_toolchain.cmake
  72. tools.cmake:cmake_program: Path to CMake executable
  73. tools.cmake:install_strip: Add --strip to cmake.install()
  74. tools.compilation:verbosity: Verbosity of compilation tools if set. Possible values are 'quiet' and 'verbose'
  75. tools.deployer:symlinks: Set to False to disable deployers copying symlinks
  76. tools.env.virtualenv:powershell: If it is set to True it will generate powershell launchers if os=Windows
  77. tools.files.download:retry: Number of retries in case of failure when downloading
  78. tools.files.download:retry_wait: Seconds to wait between download attempts
  79. tools.files.download:verify: If set, overrides recipes on whether to perform SSL verification for their downloaded files. Only recommended to be set while testing
  80. tools.gnu:build_triplet: Custom build triplet to pass to Autotools scripts
  81. tools.gnu:define_libcxx11_abi: Force definition of GLIBCXX_USE_CXX11_ABI=1 for libstdc++11
  82. tools.gnu:host_triplet: Custom host triplet to pass to Autotools scripts
  83. tools.gnu:make_program: Indicate path to make program
  84. tools.gnu:pkg_config: Path to pkg-config executable used by PkgConfig build helper
  85. tools.google.bazel:bazelrc_path: List of paths to bazelrc files to be used as 'bazel --bazelrc=rcpath1 ... build'
  86. tools.google.bazel:configs: List of Bazel configurations to be used as 'bazel build --config=config1 ...'
  87. tools.graph:skip_binaries: Allow the graph to skip binaries not needed in the current configuration (True by default)
  88. tools.graph:vendor: (Experimental) If 'build', enables the computation of dependencies of vendoring packages to build them
  89. tools.info.package_id:confs: List of existing configuration to be part of the package ID
  90. tools.intel:installation_path: Defines the Intel oneAPI installation root path
  91. tools.intel:setvars_args: Custom arguments to be passed onto the setvars.sh|bat script from Intel oneAPI
  92. tools.meson.mesontoolchain:backend: Any Meson backend: ninja, vs, vs2010, vs2012, vs2013, vs2015, vs2017, vs2019, xcode
  93. tools.meson.mesontoolchain:extra_machine_files: List of paths for any additional native/cross file references to be appended to the existing Conan ones
  94. tools.microsoft.bash:active: If Conan is already running inside bash terminal in Windows
  95. tools.microsoft.bash:path: The path to the shell to run when conanfile.win_bash==True
  96. tools.microsoft.bash:subsystem: The subsystem to be used when conanfile.win_bash==True. Possible values: msys2, msys, cygwin, wsl, sfu
  97. tools.microsoft.msbuild:installation_path: VS install path, to avoid auto-detect via vswhere, like C:/Program Files (x86)/Microsoft Visual Studio/2019/Community. Use empty string to disable
  98. tools.microsoft.msbuild:max_cpu_count: Argument for the /m when running msvc to build parallel projects
  99. tools.microsoft.msbuild:vs_version: Defines the IDE version (15, 16, 17) when using the msvc compiler. Necessary if compiler.version specifies a toolset that is not the IDE default
  100. tools.microsoft.msbuilddeps:exclude_code_analysis: Suppress MSBuild code analysis for patterns
  101. tools.microsoft.msbuildtoolchain:compile_options: Dictionary with MSBuild compiler options
  102. tools.microsoft:msvc_update: Force the specific update irrespective of compiler.update (CMakeToolchain and VCVars)
  103. tools.microsoft:winsdk_version: Use this winsdk_version in vcvars
  104. tools.system.package_manager:mode: Mode for package_manager tools: 'check', 'report', 'report-installed' or 'install'
  105. tools.system.package_manager:sudo: Use 'sudo' when invoking the package manager tools in Linux (False by default)
  106. tools.system.package_manager:sudo_askpass: Use the '-A' argument if using sudo in Linux to invoke the system package manager (False by default)
  107. tools.system.package_manager:tool: Default package manager tool: 'apk', 'apt-get', 'yum', 'dnf', 'brew', 'pacman', 'choco', 'zypper', 'pkg' or 'pkgutil'

Description of configurations

core.cache:storage_path

Absolute path to a folder where the Conan packages and the database of the packages will be stored. This folder will be the heaviest Conan storage folder, as it stores the binary packages downloaded or created.

global.conf

  1. core.cache.storage_path = C:\Users\danielm\my_conan_storage_folder

Default value: <CONAN_HOME>/p

core.download:download_cache

Absolute path to a folder where the Conan packages will be stored compressed. This is useful to avoid recurrent downloads of the same packages, especially in CI.

global.conf

  1. core.cache.download_cache = C:\Users\danielm\my_download_cache

Default value: Not defined.

User/Tools configurations

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

global.conf

  1. tools.build:verbosity=verbose
  2. tools.microsoft.msbuild:max_cpu_count=2
  3. tools.microsoft.msbuild:vs_version = 16
  4. tools.build:jobs=10
  5. # User conf variable
  6. user.confvar:something=False

Important

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

These are some hints about configuration items scope and naming:

  • core.xxx and tools.yyy are Conan built-ins, users cannot define their own ones in these scopes.

  • core.xxx can be defined in global.conf or via the --core-conf CLI argument only, but not in profiles.

  • tools.yyy can be defined in global.conf, in profiles [conf] section and as CLI -c arguments

  • user.zzz can be defined everywhere, and they are totally at the user discretion, no established naming convention. However this would be more or less expected:

    • For open source libraries, specially those in conancenter, user.packagename:conf might be expected, like the boost recipe defining user.boost:conf conf

    • For private usage, the recommendation could be to use something like user.orgname:conf for global org configuration across all projects, user.orgname.project:conf for project or package configuration, though user.project:conf might be also good if the project name is unique enough.

    • They _must_ have one : separator, like user.myorg:conf, but not user.myorg.conf or user.myorg. This is to disambiguate from patterns, which are discussed below.

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.

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

Conan also injects detect_api (non-stable, read the reference) to the jinja rendering context. You can use it like this:

  1. user.myteam:myconf1={{detect_api.detect_os()}}
  2. user.myteam:myconf2={{detect_api.detect_arch()}}

For more information on how to use it, please check the detect_api section in the profiles reference.

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:

  1. # String
  2. tools.build:verbosity=verbose
  3. # Boolean
  4. tools.system.package_manager:sudo=True
  5. # Integer
  6. tools.microsoft.msbuild:max_cpu_count=2
  7. # List of values
  8. user.myconf.build:ldflags=["--flag1", "--flag2"]
  9. # Dictionary
  10. tools.microsoft.msbuildtoolchain:compile_options={"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).

  • *= == update: updates the specified keys only, leaving the rest unmodified (only for dictionaries)

  • =! == unset: gets rid of any configuration value.

global.conf

  1. # Define the value => ["-f1"]
  2. user.myconf.build:flags=["-f1"]
  4. # Append the value ["-f2"] => ["-f1", "-f2"]
  5. user.myconf.build:flags+=["-f2"]
  7. # Prepend the value ["-f0"] => ["-f0", "-f1", "-f2"]
  8. user.myconf.build:flags=+["-f0"]
  10. # Unset the value
  11. user.myconf.build:flags=!
  13. # Define the value => {"a": 1, "b": 2}
  14. user.myconf.build:other={"a": 1, "b": 2}
  16. # Update b = 4 => {"a": 1, "b": 4}
  17. user.myconf.build:other*={"b": 4}

Configuration patterns

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

  1. *:tools.cmake.cmaketoolchain:generator=Ninja
  2. 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:

  1. zlib/*:tools.cmake.cmaketoolchain:generator=Visual Studio 16 2019
  2. *:tools.cmake.cmaketoolchain:generator=Ninja

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.

Information about built-in confs

This section provides extra information about specific confs.

Networking confs

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:

  • core.net.http:cacert_path: Path containing a custom Cacert file.

  • core.net.http:client_cert: 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

  1. core.net.http:cacert_path=/path/to/cacert.pem
  2. core.net.http:client_cert=('/path/client.cert', '/path/client.key')

See also

  • Managing configuration in your recipes (self.conf_info)

  • tools.files.download:verify: Setting tools.files.download:verify=False constitutes a security risk if enabled, as it disables certificate validation. Do not use it unless you understand the implications (And even then, properly scoping the conf to only the required recipes is a good idea) or if you are using it for development purposes

UX confs

Skip warnings

There are several warnings that Conan outputs in certain cases which can be omitted via the core:skip_warnings conf, by adding the warning tag to its value.

Those warnings are:

  • deprecated: Messages for deprecated features such as legacy generators

  • network: Messages related to network issues, such as retries