Dependency Marker Resolution#

Dependency markers (PEP 508) attach conditions to package requirements — e.g., greenlet; platform_machine == "aarch64" or extra == "asyncio". Poetry must correctly evaluate, simplify, and persist these markers when locking and installing packages. The logic is split across poetry-core (marker algebra) and poetry (solver and lockfile generation).

Marker Model (poetry-core)#

The core abstraction lives in src/poetry/core/version/markers.py. The key types are:

exclude() — stripping a marker variable from an expression#

exclude(marker_name) removes all references to a given marker variable and returns the simplified result. Its semantics differ by type:

• SingleMarkerLike.exclude() 1: if the atom matches, returns AnyMarker().
• MarkerUnion.exclude() 2: iterates over union branches. As soon as it finds a branch matching marker_name, it immediately returns AnyMarker() — because any satisfiable branch in an OR makes the whole union unconstrained with respect to that variable.

This second rule was the site of a historical bug (see Known Bug: Union Exclusion below).

without_extras()#

A convenience wrapper that calls exclude("extra") 3. Used pervasively in the solver whenever extras-specific conditions must be stripped so that plain environment conditions survive into the lockfile.

Solver Integration (poetry)#

Lockfile marker calculation (DFS traversal)#

During poetry lock, the solver traverses the dependency graph in solver.py. For each package edge, it accumulates the effective marker by calling:

markers[dep][parent][groups] = prev_marker.union(new_marker)

where new_marker is edge.marker.without_extras() for non-root packages 4. Extras are intentionally stripped here — the goal is to record only platform/Python conditions in the lockfile marker; extra conditions are tracked separately.

Merging duplicate dependencies#

provider.py:_merge_dependencies_by_constraint() consolidates dependencies that share the same version constraint but carry different markers into a single dependency with a unioned marker. This reduces the number of solver "overrides" needed.

Extras + platform marker interaction (solver PR #7175)#

A specific edge case arises when a package declares the same dependency both unconditionally-for-an-extra and conditionally by platform — e.g.:

• B ; sys_platform != "linux" (mandatory)
• B ; extra == "foo" (extra-gated)

Before the fix in PR #7175 (released in Poetry 1.4.0, 5), stripping extras too early in _merge_dependencies_by_constraint() caused the extra-gated marker to be discarded, producing an incorrect combined marker. The fix changed this method to union all markers before stripping extras, preserving the sys_platform != "linux" or extra == "foo" union.

Known Bug: Union Exclusion (poetry-core #943)#

Root cause: MarkerUnion.exclude() had a logic error — instead of immediately returning AnyMarker() on finding a matching branch, it previously skipped the branch, rebuilt the union from the remaining branches, and only returned AnyMarker() if all branches were excluded. 6

Practical impact (greenlet / sqlalchemy): SQLAlchemy declares greenlet>=1 under two separate conditions 7:

1. platform_machine == "aarch64" or platform_machine == "x86_64" or ... (platform list)
2. extra == "asyncio"

When Poetry stripped extra == "asyncio" via without_extras() while writing the lockfile, the buggy code kept only the platform branch instead of collapsing to AnyMarker. On Apple Silicon (arm64, which is not in the platform list), the resulting lockfile marker evaluated to false, so greenlet was omitted at install time — causing No module named 'greenlet' errors. 8 9

The bug was latent in earlier versions but only became observable in Poetry 2.3+ after the installer was changed to stop re-resolving at install time 7. The fix 6 was released in poetry-core 2.4.1 10.

Key Files & Entry Points#

Related PRs#