pyvenvmerge

A Python CLI utility for safely merging multiple virtual environments through deterministic dependency reconstruction instead of direct venv modification.

---

Features

Environment Analysis

• Virtual environment validation
• Python version compatibility checks
• Dependency extraction using pip freeze

Dependency Resolution

• PEP 508 compliant parsing
• Specifier-based merging
• Conflict detection and resolution
• Semantic dependency validation

Merge Intelligence

• Dependency graph analysis
• Conflict classification
• Risk analysis and compatibility scoring
• Dry-run diagnostics

Dependency Support

• PyPI packages
• Editable installs (-e)
• Git dependencies (git+...)
• File dependencies (package @ file://...)

Reliability

• Deterministic environment rebuild
• Two-phase installation pipeline
• Integrity verification using pip check
• JSON merge reports

Reporting & Reproducibility

• Structured merge report generation
• JSON report export
• Deterministic lockfile export
• Resuable report generation layer
• Serializable merge metadata artifacts

Example

pyvenvmerge envA envB --dry-run

Example output:

Compatibility Score : 82/100
Risk Level          : MEDIUM

Warnings:
⚠ pandas requires numpy<2.0 but selected version is 2.4.2

---

Installation

pip install pyvenvmerge

---

Usage

pyvenvmerge envA envB -o mergedEnv

Save structured data

pyvenvmerge envA envB --dry-run --save-report report.json

Export deterministic lockfile

pyvenvmerge envA envB --dry-run --export-lock requirements.lock

---

Conflict Resolution Strategies

pyvenvmerge envA envB -o mergedEnv --strategy highest
# default

pyvenvmerge envA envB -o mergedEnv --strategy strict

pyvenvmerge envA envB -o mergedEnv --strategy unpinned

---

Dry-Run Mode

Preview the merge plan without creating an environment:

pyvenvmerge envA envB --dry-run

---

JSON Report

pyvenvmerge envA envB --dry-run --report json

---

Limitations

Current limitations:

• No deep resolution for Git/file dependencies.
• Environment markers are partially evaluated.
• Extra merging is basic.
• Advanced specifiers such as !=, ~=, === are not fully optimized yet.
• Complex specifier combination are not fully optimized yet.

These will be improved in future versions.

---

Documentation

Detailed documentation:

ARCHITECTURE CHANGELOG

---

License

MIT License