skip to content

In Conan 2, what does a Version conflict error mean, and how do force=True and override=True on self.requires resolve it?

level: middleimportance: should knowfreq 40%

answer

  1. two paths, two versions
  2. one version per context
  3. force adds a direct dependency
  4. override only redirects others

basics

~20 s

Two requirements in one context ask for different versions of the same package, and Conan 2 refuses to guess. force=True in the consumer makes its version win and adds it as a dependency; override=True only replaces the version others request, without adding one.

solid answer

~40 s

A Conan 2 graph holds **one** version of a package per context. When your app requires `zlib/1.3.1` and `libpng/1.6.44` requires `zlib/1.3`, Conan stops with `Version conflict: Conflict between zlib/1.3 and zlib/1.3.1 in the graph. Conflict originates from libpng/1.6.44`. It does not pick one silently. In the consumer recipe, `self.requires("zlib/1.3.1", force=True)` declares zlib as a direct dependency and forces that version throughout the graph. `self.requires("zlib/1.3.1", override=True)` only redirects what other packages request: if nothing else requires zlib, it adds nothing, which a test run confirmed with an empty graph. Tool requirements are invisible downstream, so they do not conflict with host packages. Upstream ranges such as `[>=1.3 <2]` instead of exact pins avoid many conflicts in the first place.

code

python · 11 lines
python
from conan import ConanFile


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

    def requirements(self):
        self.requires("libpng/1.6.44")             # pins zlib/1.3 internally
        self.requires("zlib/1.3.1", override=True)  # redirect libpng's zlib
        # or, if the viewer itself calls zlib:
        # self.requires("zlib/1.3.1", force=True)

go deeper

for a junior

Know that one graph holds one version of a package and that Conan reports a conflict instead of guessing.

for a middle

Explain force versus override from the consumer, and why ranges in library recipes prevent many conflicts.

for a senior

Trace a conflict to its origin, judge whether forcing a version is ABI-safe, and expect the rebuilds a forced version can cause.

for a principal

Set the rule that libraries use ranges and applications pin, so conflicts are settled at the root instead of patched downstream.

## What a conflict is A Conan 2 dependency graph contains each package at most once per **context** (host or build). When two paths through the graph require the same package at **different versions**, Conan cannot satisfy both and reports a conflict instead of choosing. In a test graph where the application requires `libpng/1.6.44` and `zlib/1.3.1`, and libpng's recipe pins `zlib/1.3`, Conan 2.33 printed: ```plaintext ERROR: Version conflict: Conflict between zlib/1.3 and zlib/1.3.1 in the graph. Conflict originates from libpng/1.6.44 ``` It also suggests `conan graph info ... --format=html > graph.html` to inspect the conflict visually. A conflict needs two requirements that are both **visible**. Regular `requires` are visible by default; `tool_requires` are created with `visible=False`, so a build tool used by one package never conflicts with the same tool elsewhere. ## The two consumer-side fixes The consumer, usually the application at the root, can settle the question with a requirement trait: | Declaration in the consumer | Adds zlib as a dependency | Changes what libpng gets | |---|---|---| | `self.requires("zlib/1.3.1")` | yes | no, so the conflict remains | | `self.requires("zlib/1.3.1", force=True)` | yes | yes, everywhere upstream | | `self.requires("zlib/1.3.1", override=True)` | only if someone else requires zlib | yes, where zlib is required | - **`force=True`** says "this is my dependency and this version wins". It is right when the application really uses zlib itself. - **`override=True`** says "if anything below me needs zlib, give it this version". It is right for a transitive dependency the application never includes; on a test run, a recipe whose only requirement was `zlib/1.3.1` with `override=True` produced a graph with no zlib at all. Both resolved the test conflict, leaving `libpng/1.6.44` and `zlib/1.3.1` in the graph. ## Avoiding conflicts upstream 1. **Ranges in libraries.** If libpng's recipe required `zlib/[>=1.3 <2]`, any 1.x zlib chosen by the consumer would satisfy it. A test with such a libpng and the consumer's own `[>=1.3 <2]` resolved to a single zlib with no error. 2. **Exact pins at the top.** Applications and lockfiles are the right places to fix exact versions; libraries that pin exact versions push conflicts onto every consumer. 3. **Declaration order is not a fix.** In the test, a consumer range `[>=1.3 <2]` listed after libpng was satisfied by libpng's `zlib/1.3`, while the same range listed before libpng resolved to `1.3.1` first and then conflicted with libpng's pin. Relying on that order is fragile; an explicit `force` or `override` states the intent. ## Forcing has consequences - **ABI and behaviour.** Forcing libpng onto a zlib it was not tested with is a decision about compatibility. For zlib's stable C interface it is usually fine; for a C++ library with a changing ABI it can produce link errors or worse, which is why Conan makes you say it. - **Package IDs.** libpng's package ID depends on the zlib version according to the package ID modes, so a forced version may need a different libpng binary and trigger a build. - **Lockfiles record it.** Overrides and forced versions are stored in the lockfile's `overrides` section, so a locked build reproduces the same resolution. ## Choosing the fix - The application includes zlib headers itself: `force=True`, because the dependency is real and its version is the application's decision. - The application never touches zlib, but two libraries disagree: `override=True` at the root, so the application does not gain a target it should not link. - You maintain the library that pins exactly: change its recipe to a range and release it, which removes the conflict for every consumer instead of one. - The conflict involves a build tool: check whether it was declared with `requires` by mistake; as a tool requirement it would not have conflicted. Whatever the fix, run the tests of the package whose request was overridden, because it now builds or links against a version its own maintainers did not choose. ## Reading a conflict quickly - The message names both versions and the package the conflict originates from: the second path to the package. - `conan graph info --format=html` shows every path to the package, which tells you whether to fix it at the root with `force`/`override` or upstream with a range. - A conflict that appears only on one platform usually comes from a conditional requirement in some recipe's `requirements()`.

  • Why does a cmake tool_requires used by two packages at different versions not conflict?
    Tool requirements are created with `visible=False`, so each stays private to the package that declared it. Only visible requirements, which regular `requires` are by default, must agree on one version.
  • When would you choose override over force?
    When the application does not use the package directly. override fixes the transitive version without making it a direct dependency, so CMakeDeps does not hand the application a target it should not link.

  • Conan 2 silently picks the newest version when two packages disagree.
  • override=True adds the package as a direct dependency, just like force=True.
  • tool_requires of different versions in two packages always cause a conflict.
  • Listing my range before the conflicting package is a reliable fix.
  • Forcing a version never affects other packages' binaries.