Install & Compatibility
Where this runs
tested against v2.31.2 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 1.052s · 32.4MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 3.3s · import 0.940s · 34MB
32MB installed
● package 32MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
ConanAPI
✓ from conan.api.conan_api import ConanAPI
✗ from conans.client.api import Conan
The Python API for Conan was completely rewritten for Conan 2.x, changing import paths and class structures from the Conan 1.x API.
This quickstart initializes the Conan API and demonstrates how to programmatically interact with Conan, specifically by listing recipes in the local cache and retrieving the Conan home directory. The `ConanAPI` object provides access to various sub-APIs for different functionalities.
from conan.api.conan_api import ConanAPI
# Initialize the Conan API. For advanced use, cache_folder can be specified.
conan_api = ConanAPI()
print("Conan API initialized.")
# Example: List installed recipes in the local cache
# The 'list' sub-API provides methods for inspecting packages and recipes.
local_recipes = conan_api.list.recipes(query="*")
if local_recipes:
print(f"Found {len(local_recipes)} local recipes:")
for ref in local_recipes:
print(f" - {ref}")
else:
print("No recipes found in the local Conan cache.")
# Example: Get Conan's current home folder
conan_home = conan_api.home_folder
print(f"Conan home folder: {conan_home}")
conan --version
Debug
Known issues
breakingConan 2.0 introduced major breaking changes compared to Conan 1.x. The Python API, recipe format (`conanfile.py`), command-line interface, and binary package formats are incompatible. Recipes and existing builds from Conan 1.x projects *must* be migrated.fixConsult the official Conan 2.0 Migration Guide (e.g., in the Conan documentation) to understand the necessary updates for recipes, commands, and project integrations. Existing Conan 1.x binary packages cannot be reused directly with Conan 2.x.
affects: 2.0.0 and later (when upgrading from 1.x)
gotchaThe Conan Python API (`conan.api.conan_api.ConanAPI`) is currently experimental and explicitly stated to be subject to breaking changes across minor versions. Relying heavily on it for critical automation may require frequent updates.fixMonitor Conan release notes for Python API changes. For stable long-term automation, consider wrapping the `conan` CLI commands via `subprocess` or limit Python API usage to documented and stable parts.
affects: 2.0.0 and later (all 2.x versions)
gotchaOlder Conan 2.x versions (specifically 2.25.0 to 2.25.2, and some 2.26.x before 2.26.2) had issues with atomic file operations during package binary downloads on Windows, often clashing with antivirus software, leading to failures or corrupted caches.fixEnsure you are running Conan 2.26.2 or newer, especially on Windows, to benefit from fixes addressing issues with antivirus interference during package downloads.
affects: 2.25.0 - 2.25.2, 2.26.0 - 2.26.1
gotchaThe behavior of `conan profile detect` changed significantly from Conan 1.x to 2.x. Relying on its output as a stable baseline, especially for build automation, can lead to unexpected results in Conan 2.x.fixIn Conan 2.x, it is recommended to explicitly define and manage profiles rather than relying on `conan profile detect` for critical build configurations. Manually review and update profiles after migration.
affects: 2.0.0 and later (when migrating from 1.x)
Errors
Common errors & fixes
ERROR: Missing prebuilt package
Conan could not find a pre-compiled binary package matching the current settings, options, and dependencies in its local cache or configured remotes.
fixBuild the package from sources using `conan install . --build=<package_name>` or `conan install . --build=missing`, or ensure your Conan profile settings (compiler, OS, architecture, etc.) match an available pre-built binary.
ERROR: The default build profile doesn't exist. You need to create a default profile (type 'conan profile detect' command) or specify your own profile with '--profile:build=<myprofile>'
In Conan 2.x, the default profile is not automatically created upon installation, and Conan requires a profile to be explicitly specified or detected for operations.
fixRun `conan profile detect` to create a default profile based on your system's detected environment, or explicitly specify a custom profile using the `--profile:build=<myprofile>` argument with your Conan commands.
ERROR: Invalid setting 'X' is not a valid 'settings.Y' value.
The Conan recipe or your current configuration attempts to use a value for a setting (e.g., `compiler.version`) that is not defined or supported within Conan's `settings.yml` file or by the package recipe itself.
fixModify your `~/.conan2/settings.yml` file to include the missing setting value, or adjust your Conan profile or command-line arguments to use a value that is already defined and supported.
ERROR: Failed to remove folder (Windows)
On Windows, Conan is unable to delete a folder or file within its local cache, usually because another process (like a text editor, terminal, or the Windows Search Indexer) has a lock on it.
fixClose any applications that might be accessing files within the Conan cache (`~/.conan2/`), disable the Windows Search Indexer for the Conan cache directory, or as a last resort, reboot your machine to release file locks.
ERROR: Package-id doesn't match the locked one
A mismatch occurred between the expected package ID (often recorded in a Conan lockfile) and the package ID calculated during the current build, indicating inconsistencies in settings, options, or transitive dependencies.
fixEnsure that the Conan profiles (host and build), options, and dependency versions used during lockfile generation are precisely the same as those used for subsequent builds. Utilize `conan graph explain` to pinpoint the exact differences causing the package ID mismatch.
Upgrade
Version history
2.31.2latest on PyPI · released Aug 4, 2026
Audit
Dependencies
No dependency data recorded yet.