skip to content

In Conan 2, how does a requirement like zlib/[>=1.3 <2] resolve, and what do the ~ and ^ range operators mean?

level: middleimportance: must knowfreq 50%

answer

  1. square brackets mark a range
  2. newest match, cache first
  3. tilde locks the minor
  4. caret locks the major
  5. pre-releases excluded by default

basics

~20 s

A bracketed range resolves to the newest matching version, taken from the local cache if one matches there, otherwise from the first remote with a match. ~1.3 means >=1.3 <1.4, ^1.3 means >=1.3 <2, and pre-releases are skipped unless requested.

solid answer

~40 s

In `zlib/[>=1.3 <2]` the brackets hold a range: space-separated conditions must all hold, and `||` separates alternatives. Conan 2 resolves it to the **newest** version that satisfies it, looking in the **local cache** first; if any cached version matches, remotes are not consulted unless you pass `--update`. Otherwise it takes the newest match from the first remote that has one, or, with `--update`, the newest across all remotes. `~1.3` is a tilde range, `>=1.3 <1.4`, allowing patch releases; `^1.3` is a caret range, `>=1.3 <2`, allowing minor releases, and `^0.3` stays below `0.4`. Pre-release versions such as `2.0-rc1` are excluded unless the expression adds `include_prerelease` or `core.version_ranges:resolve_prereleases` says otherwise. The result is printed as `zlib/[>=1.3 <2]: zlib/1.3.1` in the graph output.

code

python · 10 lines
python
from conan import ConanFile


class ImageToolRecipe(ConanFile):
    settings = "os", "compiler", "build_type", "arch"

    def requirements(self):
        self.requires("zlib/[>=1.3 <2]")
        self.requires("fmt/[~11.0]")
        self.requires("spdlog/[^1.14, include_prerelease]")

go deeper

for a junior

Recognise the bracket syntax and know that a range resolves to the newest matching version.

for a middle

Expand ~ and ^ into explicit bounds, explain cache-first resolution and --update, and the pre-release rule.

for a senior

Explain why two machines resolve the same range differently and why a release needs a lockfile on top of the range.

for a principal

Decide where ranges are allowed, for example in internal libraries to avoid conflicts, and where exact pins or lockfiles are mandatory.

## Range syntax A Conan 2 requirement can name an exact version, `zlib/1.3.1`, or a **version range** in square brackets, `zlib/[>=1.3 <2]`. Inside the brackets: - a **condition** is an operator and a version: `>`, `>=`, `<`, `<=`, `=`, plus the shorthand operators `~` and `^`; - conditions separated by spaces must **all** hold; - `||` separates **alternatives**, any of which may hold; - a trailing `, include_prerelease` lets the range match pre-release versions. Evaluating a few expressions with Conan 2.33's own range parser gives: | Expression | 1.3.0 | 1.3.1 | 1.4.0 | 1.9 | 2.0 | 2.0-rc1 | 3.1 | |---|---|---|---|---|---|---|---| | `~1.3` | yes | yes | no | no | no | no | no | | `^1.3` | yes | yes | yes | yes | no | no | no | | `>=1.3 <2` | yes | yes | yes | yes | no | no | no | | `>=1.3 <2 \|\| >=3` | yes | yes | yes | yes | no | no | yes | | `>1.0` | yes | yes | yes | yes | yes | no | yes | Two shorthand operators deserve care: 1. **Tilde** `~1.3` becomes `>=1.3 <1.4`: the last given component may not grow, so patch releases are accepted. With a single component, `~2`, the bound is `<3`. 2. **Caret** `^1.3` becomes `>=1.3 <2`: the first non-zero component is fixed. That is why `^0.3` accepts `0.3.5` but not `0.4.0`. ## How Conan 2 picks a version For each range Conan 2.33's range resolver does the following: 1. **Search the local cache** for versions of that package and keep those that satisfy the range. 2. If at least one cached version matches and `--update` was not given, **take the newest cached match** and stop. No remote is contacted. 3. Otherwise **search the remotes in order**; without `--update`, the newest match in the first remote that has one wins. 4. With `--update`, collect the newest match from every remote and take the newest of those. Afterwards the chosen version's recipe revision is selected the usual way: the latest one unless the reference or a lockfile pins it. ## Pre-releases Versions with a pre-release tag such as `2.0-rc1` are **excluded** by default; note that `>1.0` rejected `2.0-rc1` in the table. Two switches change that: - adding `include_prerelease` to the expression, for one requirement; - the `core.version_ranges:resolve_prereleases` conf, which, when set, overrides what the expressions say for every range. ## Checking what a range resolved to Never guess which version a range picked; Conan prints it. Every graph command shows a **Resolved version ranges** block, for example `zlib/[>=1.3 <2]: zlib/1.3.1`, and `conan graph info --format=json` carries the same information for scripts. When two machines disagree, compare that block first: - if the versions differ, the caches or remotes differ, and `--update` or a shared lockfile aligns them; - if the versions match but behaviour differs, compare the recipe revisions after the `#`, which a range does not constrain at all; - if a pre-release unexpectedly appears, look for `include_prerelease` in the expression or a `core.version_ranges:resolve_prereleases` setting in someone's global configuration. ## Consequences - **Machines can disagree.** A developer whose cache holds zlib 1.3.0 keeps resolving `[>=1.3 <2]` to 1.3.0, while a CI runner with an empty cache resolves it to the newest release on the remote. Neither is wrong; they simply searched different places. - **Builds drift over time.** The same commit resolves differently after a new upstream release, which is exactly what lockfiles exist to stop. - **Ranges reduce conflicts.** When libraries in a graph accept ranges instead of exact pins, Conan can often satisfy them all with one version, where exact pins would collide. A range is therefore a statement of compatibility, not of reproducibility; pairing ranges with a committed lockfile gives both.

  • The cache already holds zlib 1.3.0 and the remote has 1.3.1. Which one does zlib/[>=1.3 <2] get?
    1.3.0. A cached version satisfies the range, so Conan 2 does not query remotes. Passing `--update` makes it check the remotes and pick 1.3.1.
  • Why does ^0.3 not accept 0.4.0?
    The caret fixes the first non-zero component. For `0.3` that is the 3, so the range becomes `>=0.3 <0.4`. Pre-1.0 versions are treated as if every minor release may break compatibility.

  • A version range always queries every remote for the newest version.
  • ~1.3 accepts any 1.x release from 1.3 upwards.
  • ^0.3 accepts 0.4.0 because the major version is still 0.
  • Ranges include pre-releases such as 2.0-rc1 by default.
  • Conditions in a range are combined with OR unless written with &&.