skip to content

A release branch's Conan 2 build changed overnight because zlib/[>=1.3 <2] resolved to a new zlib release. How do you use a lockfile to stop this in CI?

level: seniorimportance: must knowfreq 45%

answer

  1. freeze the resolved graph
  2. conan.lock beside the conanfile
  3. picked up automatically
  4. missing entries are errors

basics

~20 s

Run conan lock create on the branch, commit the resulting conan.lock beside the conanfile, and let CI install with it: Conan 2 loads conan.lock automatically and resolves every range to the recorded version and recipe revision, failing if a requirement is missing.

solid answer

~50 s

The range was doing its job: a fresh CI cache resolved `[>=1.3 <2]` to the newest zlib on the remote. To freeze it, run `conan lock create .` with the branch's profiles. It writes `conan.lock`, a JSON file listing every resolved reference with its recipe revision and timestamp, split into `requires`, `build_requires`, `python_requires` and `config_requires`. Commit it next to the conanfile. Conan 2's `conan install`, `conan create` and `conan graph` commands load a `conan.lock` in that folder automatically, so ranges resolve to the locked version even after newer releases appear. A requirement absent from the lockfile is an error, `Requirement '...' not in lockfile 'requires'`, unless `--lockfile-partial` is passed. Running `conan lock create` with another profile extends the same file, and `--lockfile=""` ignores it for a deliberate re-resolution. By default the lockfile records recipe references, not package IDs, so binaries are still selected by package ID.

code

console · 7 lines
console
$ conan lock create .
Generated lockfile: .../app/conan.lock
$ conan export zlib.py --version 1.3.1     # a new release appears
$ conan graph info .                       # conan.lock picked up automatically
    zlib/1.3#e7ac6c6c6699427bbe5a7911a920e584 - Cache
$ conan graph info . --lockfile=""         # lock ignored
    zlib/1.3.1#e7ac6c6c6699427bbe5a7911a920e584 - Cache

go deeper

for a junior

Know that conan lock create writes conan.lock and that committing it freezes dependency versions.

for a middle

Explain what the lockfile records, that it is loaded automatically, and the strict error for unknown requirements.

for a senior

Run release CI on a committed lock, extend it across configurations, and update it through reviewed commits only.

for a principal

Decide which branches are locked, how often locks are refreshed, and who approves dependency updates on a release branch.

## What went wrong The release branch did not change, but its build did. The recipe asks for `zlib/[>=1.3 <2]`, and a range resolves to the newest matching version. The CI runner starts with an empty cache, so it searched the remote, found the zlib release published overnight, and built against it. The same would happen with a new **recipe revision** of an unchanged version. The fix is not to remove the range, which keeps the graph flexible on the main branch, but to **freeze the resolution** on the release branch. ## Creating the lockfile `conan lock create .` computes the dependency graph exactly as `conan install` would and writes the result, by default to `conan.lock` next to the conanfile: ```json { "version": "0.5", "requires": [ "zlib/1.3.1#e7ac6c6c6699427bbe5a7911a920e584%1793035377.394033", "libpng/1.6.45#1ba9d24e782d43bc873cca59fcf3651b%1793036261.88231" ], "build_requires": [], "python_requires": [], "config_requires": [] } ``` Each entry is a reference with its **recipe revision** after `#` and a timestamp after `%`. Tool requirements go under `build_requires`. Package IDs and package revisions are **not** recorded by default, so the lockfile pins which recipes are used while the profile still decides which binaries. ## Using it in CI 1. **Commit `conan.lock`** on the release branch, next to the conanfile. 2. **Install as usual.** Conan 2's graph commands load `conan.lock` from the conanfile's folder automatically; `--lockfile=<path>` names another file, and `--lockfile=""` disables it. 3. **Ranges resolve to the locked entries.** On a test run, exporting zlib 1.3.1 after locking 1.3 changed nothing for the locked build, while `--lockfile=""` immediately resolved 1.3.1. 4. **Unknown requirements fail.** Adding a dependency without updating the lock stops with `ERROR: Requirement 'libpng/1.6.44' not in lockfile 'requires'`, so nothing enters the graph unreviewed. `--lockfile-partial` relaxes this, which is useful while developing and dangerous in release CI. 5. **Several configurations, one file.** `conan lock create` itself loads the existing lockfile partially, so running it again with a Linux profile added the Linux-only `libpng` entry while keeping the locked zlib. `conan lock merge` combines lockfiles produced separately. ## Updating deliberately Freezing is only half of the policy; the other half is changing the lock on purpose: - `conan lock create . --lockfile=""` re-resolves from scratch, but only for the profile it is given, and it overwrites `conan.lock`; for further configurations, run `conan lock create` again **without** `--lockfile=""` so it extends the fresh file, or write each one with `--lockfile-out` and combine them with `conan lock merge`; - `--update` makes that resolution consult the remotes for newer versions and revisions instead of trusting the cache; - `conan lock add --requires=zlib/1.3.2` adds a specific newer reference, and `conan lock update` replaces matching ones; - `--lockfile-clean` removes entries the current graph no longer uses. The resulting diff of `conan.lock` goes through code review like any other change, so a dependency update on a release branch becomes a visible commit. ## A release pipeline, step by step 1. Check out the release branch, which carries `conanfile.py` and `conan.lock`. 2. Install the team's remotes and profiles with `conan config install`, so every runner uses the same remote order. 3. Run `conan install .` or `conan create .` with the branch's profiles; the lockfile is picked up and any unrecorded requirement fails the job. 4. Build and test as usual. 5. On main only, a scheduled job regenerates the lock, builds and tests, and proposes the diff for review; the release branch never runs that job. ## Limits worth knowing - A lockfile freezes **references**, not **binaries**: a changed profile still changes package IDs, and without stored package revisions the latest package revision for an ID is used. - It does not make a remote keep old revisions: when the locked recipe revision is gone, the locked build fails rather than silently moving. On a test run with the locked revision removed and a newer one still cached, Conan reported `Package 'zlib/1.3' not resolved` instead of using the newer one. - Overrides and forced versions in the graph are recorded too, in an `overrides` section, so a lockfile captures the effect of `force=True` and `override=True`.

  • Does the lockfile stop a profile change from rebuilding packages?
    No. By default it records recipe references with revisions, not package IDs. A changed setting still yields new package IDs, and binaries are found or built according to the profile and the --build policy.
  • How do you take a security fix of zlib onto the locked release branch?
    Update the lock deliberately, for example `conan lock add --requires=zlib/1.3.2` or a fresh `conan lock create --lockfile="" --update` extended to the other configurations, rebuild and test, and merge the reviewed `conan.lock` diff.
  • When is --lockfile-partial acceptable?
    While developing a change that adds dependencies, before the lock is regenerated. In release CI it defeats the purpose, because anything missing from the lock would resolve freely.

A version range is a shopping list that says any 1.x flour; the lockfile is the receipt from the bake that passed tasting. Reordering from the receipt gets the same bag, and anything not on the receipt has to be added on purpose.

  • Lockfiles must be passed explicitly; conan.lock beside the conanfile is ignored.
  • A Conan 2 lockfile records package IDs, so a profile change cannot rebuild anything.
  • A requirement missing from the lockfile is resolved freely without any error.
  • Each configuration needs a completely separate lockfile that cannot be combined.
  • Removing version ranges from all recipes is the only way to get reproducible CI.