Poetry lockfile resolution fails under memory pressure

Resolver Memory and Determinism Analysis

Peak resident memory during lockfile resolution differs between Poetry 1.x and 2.x based on the shape of the dependency graph. Poetry 2.x utilizes a PubGrub-based resolver, which generally reduces the number of resolution steps compared to the 1.x backtracking resolver. However, while deep dependency trees often see a reduction in peak memory, very wide trees (those with thousands of transitive dependencies) may experience a slight increase in peak resident set size (RSS) due to the memory required for PubGrub's clause-learning structures.

Regarding determinism, poetry.lock is not guaranteed to be byte-identical across different Python versions. While content hashes for specific package versions remain constant, the evaluation of environment markers (e.g., python_version, platform_system) occurs during the resolution process. Consequently, a lockfile generated using a Python 3.11 interpreter may differ in structure or included dependencies from one generated using Python 3.12, even with an identical pyproject.toml.

Likely Explanations for Observed Behavior

• Memory Pressure: OOM kills in constrained CI environments are typically caused by the materialization of large partial solution sets in memory. In Poetry 2.x, the transition to the v2 lockfile format and the PubGrub algorithm changes how these sets are stored and processed.
• Non-Byte-Identity: Differences in lockfiles across Python versions stem from how markers are serialized and evaluated. Furthermore, Poetry 2.x writes metadata version 2.0; if a project is round-tripped between 1.x and 2.x, the TOML ordering and whitespace will change, breaking byte-for-byte equality.

Resolution Steps for Memory Exhaustion

If your lockfile resolution is failing under memory pressure on constrained runners, apply the following scoped changes:

1. Use the --no-cache flag: This reduces peak memory by skipping the population of the local cache during the resolution phase.
2. Use --dry-run: If you only need to verify that a resolution is possible without writing to disk or triggering the installer, this reduces the overall resource footprint.
3. Standardize the Resolution Environment: To minimize lockfile churn and marker discrepancies, ensure all developers and CI runners use the same Python interpreter version to execute poetry lock.

Verification Commands

To verify peak memory usage on Linux runners, use the time utility:

/usr/bin/time -v poetry lock --no-cache 2>&1 | grep 'Maximum resident set size'

To check for byte-level differences across Python versions:

diff -u lock-python311.lock lock-python312.lock

Diagnostic Requirement: To provide a more specific recommendation for memory failures, please provide the approximate number of transitive dependencies in your project, as the PubGrub resolver's memory profile shifts significantly between deep and wide graphs.