What this article covers and why it matters
This evergreen overview explains Conan 3 with an emphasis on durable concepts, practical commands, and migration guidance rather than time-sensitive news. You will find verified details about core behavior changes, profiles, lockfiles, package_id rules, and how Conan 3 compares to earlier versions. The content prioritizes clarity for developers and maintainers who need reliable reference material they can return to as tooling and ecosystems evolve.
Conan 3 in one sentence
Conan 3 is a backward-compatible package manager release that introduces stricter package identity rules based on the full dependency graph, richer lockfile behavior, clearer profile composition, and improved error messages, while preserving most recipes and workflows from Conan 1.x and 2.x.
Key goals of Conan 3
The design intent behind Conan 3 centers on stability for consumers and more predictable builds. These goals are reflected in tighter package id computation, improved workspace handling, better interaction with existing CMake and Autotools tooling, and clearer separation between user preferences and binary compatibility. The changes aim to reduce subtle mismatches that can surface only at test or runtime, especially in complex dependency graphs or monorepo setups where multiple versions coexist.
Conan 3 vs. Conan 2: what changed at a high level
Conan 2 introduced graph-based package IDs, and Conan 3 builds on that with stronger enforcement, clearer error messages, and more explicit handling of options and settings. Compared to Conan 1, the package_id model is more rigorous, and the profile system is more composable. Build and host contexts are better separated, and recipe helper APIs have been aligned to reduce deprecated patterns. While many Conan 2 recipes work unchanged, some assumptions that were previously tolerated now surface earlier as clear errors or warnings.
Quick comparison of core concepts
| Aspect | Conan 1 | Conan 2 | Conan 3 |
|---|---|---|---|
| Package id computation | Settings and options only | Introduction of graph-based influence | Full dependency graph by default, stricter validation |
| Lockfile behavior | Basic versions | First robust lockfile support | Mandatory lockfile use in certain workflows, improved merging |
| Profile composition | Simple profile layers | More flexible composition | Explicit context separation (build/host), validation |
| Error messages | Sometimes opaque | Improved | Clear, contextual guidance and migration hints |
| Recipe deprecations handled | N/A | Many cleaned | Fewer legacy shims; clearer migration paths |
Understanding package_id in Conan 3
Package identity in Conan 3 combines settings, options, and, by default, the dependency graph when compute_package_id runs. This means two recipes with identical settings and options can still receive different package ids if their transitive requirements differ. For maintainers, this increases correctness at the cost of needing to be explicit when package id behavior should be narrowed. You can influence the graph subset used via package_id_mode and package_id_python_mode, and document why certain transitive dependencies are excluded rather than included in the package binary identity.
Practical guidance for package_id_mode
- recipe_default_mode: include relevant options and settings, keep graph influence when it meaningfully changes the ABI or linkage.
- semver_mode, full_dep_mode, patch_mode: choose based on your compatibility guarantees.
- disabled modes for specific dependencies: useful when a dependency is only a tool-time or build-time concern and should not affect the consumer package id.
Lockfiles in Conan 3
Lockfiles are more central in Conan 3, with clearer roles for conan.lock and manifest behaviors. A lockfile captures exact versions, revisions, and package ids for a given graph, enabling reproducible installs and CI consistency. The conan lock create command now integrates tightly with the updated graph resolver, and merge strategies address monorepo and workspace scenarios. Consumers can verify locked entries with conan graph lock verify, and recipes can express lockfile hints to guide automatic captures without forcing a particular workflow.
Common lockfile workflows
- Create or update a lockfile while developing: conan lock create "*" --build=missing.
- CI verification: conan graph lock verify conan.lock --require-overrides.
- Selective consumer lockfile generation: conan lock create consumer/1.0 --lockfile-clean.
Profile composition and contexts
Conan 3 clarifies profile usage through explicit build and host contexts. A profile can define settings and options for the build machine, the target host, or both. When you run conan install, the command reconciles these contexts so toolchain generators and package binaries align with the intended deployment scenario. This reduces subtle bugs where a host compiler accidentally pairs with build-time tools, or when cross-compiling settings are incompletely specified. You can still compose profiles using includes, and layering remains supported, but context validation helps catch misconfiguration earlier.
Best practices for profile hygiene
- Separate build and host profiles when cross-compiling or using different toolchains.
- Keep shared settings in a base profile and override context-specific values with includes.
- Use conan profile show to inspect the composed profile and verify settings, options, and package remotes.
Migration checklist and compatibility notes
Most recipes and workflows continue to work under Conan 3, but it is wise to validate key assumptions early. Run your test pipeline with the new version on a branch, monitor compute_package_id outputs for critical packages, and confirm that lockfile workflows behave as expected in both local development and CI. If you rely on legacy implicit behaviors, update package_id_mode or recipe helpers rather than relying on shims. Projects using CMakeDeps and AutotoolsDeps should regenerate tools and verify include paths, as generator outputs can shift slightly due to stricter package_id rules.
Minimal migration steps
- Upgrade Conan and update global.conf if needed.
- Run conan profile detect to refresh default profiles.
- Inspect package_id outputs for flagship dependencies; adjust modes if too noisy.
- Regenerate lockfiles and run CI verification passes.
- Update any custom helper plugins that depend on deprecated APIs.
Common commands and useful flags
The command set remains familiar, but help text is more precise. Use conan profile show to review composed profiles, conan graph info to explore dependency resolution, and conan lock create or conan graph lock to manage lockfiles. When troubleshooting, prefer verbose or --format=json to surface structured output that can be compared across runs. These commands are stable across Conan 3.x releases and form part of the durable mental model for package management with Conan.
Essential command list
- conan profile detect: create or refresh default profiles.
- conan install --lockfile-out=conan.lock: capture a lockfile.
- conan graph lock: generate or update lockfiles without installing.
- conan package_id: inspect and test package_id decisions.
- conan profile show: view the effective profile after composition.
Frequently asked questions about Conan 3
Below are recurring questions with concise, practical answers to reduce noise during adoption.
Will my Conan 2 recipes break in Conan 3?
Most will continue to work. If package_id behavior changes affect your graph, adjust package_id_mode or recipe helpers. Lockfiles created under Conan 2 may need to be regenerated, but the format is compatible and mergeable in many cases.
Do I have to use lockfiles with Conan 3?
Not strictly, but lockfiles are strongly recommended for reproducible builds and to benefit from the stricter package_id model. You can opt out selectively for experimental work, while keeping lockfile checks in CI.
How does Conan 3 affect CI pipelines?
CI can become more deterministic because lockfile verification is stricter and profile composition is validated. Expect clearer errors if profiles or lockfiles drift, which helps catch environment mismatches before they reach production.
Wrap-up and next steps
Conan 3 delivers a more consistent and verifiable package management experience by tightening package identity, improving lockfile workflows, and clarifying profile contexts. By understanding package_id modes, adopting lockfile verification, and validating profiles early, teams can upgrade with confidence and reduce hard-to-debug build or runtime issues over time. Treat this overview as a durable reference and revisit configuration decisions when dependencies or toolchains change.