Skip to main content

🩺 EnvRepair CI

Fixing broken Python environments – safely, transparently, reproducibly

EnvRepair icon

EnvRepair is a practical repair tool for the messy reality of Python environments:
Conda / Mamba / Micromamba mixed with pip, plus plain venv / virtualenv.

Instead of starting over (again), EnvRepair helps you understand what’s broken, why it’s broken, and fix it safely – with snapshots and rollback support, so you’re never locked in.


🤕 Why EnvRepair Exists

If you’ve ever seen things like:

  • duplicate .dist-info folders
  • mysterious .pyd conflicts on Windows
  • conda-meta JSON files that suddenly break tools like PyInstaller
  • environments that are “inconsistent” but still half-working
  • pip + conda silently stepping on each other’s toes

…then EnvRepair is for you.

It doesn’t try to replace conda or pip.
It steps in after things already went wrong.


✨ What EnvRepair Can Do

🔍 Diagnose

  • Detect duplicates and leftovers (.dist-info, stale artifacts, some Windows .pyd duplicates).
  • Find corrupted or incomplete conda-meta entries.
  • Detect pip/conda case-sensitivity conflicts.

🛠️ Repair (carefully!)

  • Repair mixed conda + pip installs using the right tool.
  • Reinstall broken packages with source awareness.
  • “Adopt” pip packages into conda where possible (--adopt-pip).
  • Handle plain venv / virtualenv setups (pip-only mode).

🛟 Safety First

  • Automatic rescue snapshots before any destructive action.
  • Graceful recovery after Ctrl+C.
  • Clear prompts instead of silent force-fixes.

🧰 Requirements

  • Windows, Linux, or macOS.
  • mamba in PATH for conda-style envs (preferred). conda/micromamba are supported when available.
  • conda is optional: mamba-only installs (e.g. Mambaforge/Miniforge variants) are supported.
  • Python available in the target environment.

🚀 Quick Start

All examples below use Windows cmd.exe syntax (.bat blocks).
Adjust paths/shells as needed for Linux/macOS.

Recommended first run (one-shot):

env-repair one-shot --env base -y

Basic scan (auto-discovers conda envs):

python env_repair.py

Install as a CLI (editable):

pip install -e .
env-repair --help

Install from local checkout (non-editable):

pip install .

🔁 Common Workflows

Use --use-uv to run pip operations through an available uv executable:

env-repair one-shot --env base -y --use-uv
env-repair verify-imports --env base --full --fix --use-uv

The selected environment's Python is passed explicitly to uv. If uv is unavailable, or a repair requires pip's --ignore-installed recovery behavior, pip is used instead.

One-shot repair flow (recommended):

env-repair one-shot --env base -y

Fix base:

python env_repair.py --env base --fix

Fix a plain venv (pip-only):

python env_repair.py --env .venv --fix

Same via installed CLI:

env-repair --env base --fix

Adopt pip packages into conda (where possible):

python env_repair.py --env base --fix --adopt-pip

Verify imports (and fix what can be fixed):

python env_repair.py verify-imports --env base --full --fix

⏪ Rollback & Rebuild

Rollback to previous conda revision:

env-repair rollback --env base --to prev

Rollback without prompt:

env-repair rollback --env base --to prev -y

Rebuild into a new env (name):

env-repair rebuild --env base --to base-rebuilt --verify

Rebuild into a new env (path):

env-repair rebuild --env base --to C:\temp\base-rebuilt --verify

🧪 Advanced Diagnostics

Diagnose a ClobberError from a logfile:

env-repair diagnose-clobber --env base --logfile clobber.txt

Diagnose / fix “inconsistent” env:

env-repair diagnose-inconsistent --env base
env-repair fix-inconsistent --env base --level safe

Cache check / fix:

env-repair cache-check
env-repair cache-fix --level safe

SSL diagnosis:

env-repair diagnose-ssl --base
env-repair diagnose-ssl --env base

Create a conda-style snapshot (YAML):

python env_repair.py --env base --snapshot snapshots\base.yaml

Debug output:

python env_repair.py --env base --fix --adopt-pip --debug

🛟 Safety Net (Ctrl+C / Rescue)

  • When you run with --fix, EnvRepair creates a rescue snapshot under:
    .env_repair\snapshots\...
    
  • If you abort during a pip/mamba/conda step, EnvRepair will prompt:
    • r restore from snapshot
    • c continue (skip)
    • a abort (default)
  • A .env_repair\state.json file records progress so you can inspect what happened and re-run later.

🔎 Import Verification (verify-imports)

EnvRepair can scan installed distributions and run python -c "import <name>" for their top-level modules.

Full scan + auto-fix (recommended when an env is “mostly working but randomly broken”):

python env_repair.py verify-imports --env base --full --fix --debug

Both --env placements are supported:

env-repair --env base verify-imports --full --fix
env-repair verify-imports --env base --full --fix

If you want the full sequence in one command (fix-inconsistent + scan/fix + verify-imports --fix):

env-repair one-shot --env base -y

Notes:

  • Repairs use batched conda/mamba operations (no slow one-by-one reinstalls).
  • If the solver fails for a specific package, EnvRepair retries the batch without the offending spec and remembers it in:
    • .env_repair\verify_imports_blacklist.json
  • Platform-only modules are skipped (e.g. sh on Windows, ptyprocess missing fcntl on Windows).
  • Import timeouts are reported separately ([TIMEOUT]) and are not treated as hard failures in fix planning.
  • For local/manual installs from direct_url=file://..., EnvRepair now probes conda/mamba search first; only packages without a conda candidate are skipped.

🧑‍💻 Development

Run tests:

python -m unittest discover -s tests -p "test_*.py"

Run integration tests (non-interactive):

python itest\scripts\run_itest.py --list
python itest\scripts\run_itest.py --scenario S01_DUP_DIST_INFO --summarize

JSON output:

python env_repair.py --env base --json

Release helper (patch bump in pyproject.toml):

python release.py
python release.py --sync

Sync conda recipe metadata from project version:

python tools\sync_versions.py
python tools\sync_versions.py --pypi-sdist --staged-recipes staged-recipes

📝 Notes

  • --adopt-pip installs only mapped PyPI packages.
  • --adopt-pip is conda-only; for plain venvs it is ignored.
  • After successful adoption, env-repair uninstalls the pip version by default; use --keep-pip to skip.
  • For alias-like mappings (e.g. pip msgpack → conda msgpack-python), pip is only removed if both versions match.
  • Channels are loaded from .condarc first, then defaults and anaconda unless disabled.
  • --debug prints the exact external command lines as [cmd] ... (mamba/conda/pip), and streams live output to keep long operations transparent.
  • If conda core is broken after updates, env-repair can auto-repair it in two stages: core packages first, then python/menuinst when health remains degraded or mixed ABI .pyd residue is detected.
  • For automated runs (CI/itest), set ENV_REPAIR_AUTO_YES=1 to bypass interactive confirmation prompts.
  • On Windows, duplicate-pyd issues from mixed Python ABI residues are now cleaned directly by removing stale .pyd files that do not match the active ABI tag.

Mini Troubleshooting

Signal in output Meaning Recommended next step
skip [installed from local file/path (direct_url=file://...)] Package was installed from a local/custom artifact and no conda candidate was found via search. Keep as-is or reinstall manually from your local source if needed.
[TIMEOUT] ... Import check exceeded the timeout window for this run. Re-run verify-imports; timeout entries are informational and not auto-repair targets.
skip [blacklisted for python X.Y ...] Previous solver run marked this package as incompatible for this Python version/channel set. Re-run after channel/version changes, or remove the entry from .env_repair\verify_imports_blacklist.json to retry once.
Solver hit pinned-python conflict; retrying without --force-reinstall... --force-reinstall could not satisfy pinned Python constraints. Usually safe to continue; env-repair already retries with upgrade-friendly solver behavior.
Post-fix: all non-skipped imports OK. Automatic repair succeeded for everything that is auto-fixable. Review skipped imports; handle only those manually if they matter for your workload.

verify-imports auto-repair hints

  • Missing private runtime modules are now mapped to the correct conda providers before regular fix planning:
    • _brotli -> brotli-python
    • _argon2_cffi_bindings -> argon2-cffi-bindings
    • pkg_resources -> setuptools
  • For Streamlit protobuf runtime/codegen mismatch (_CheckCalledFromGeneratedFile), EnvRepair now schedules:
    • protobuf>=4,<7 alignment
    • streamlit>=1.30 upgrade/relink
  • If imblearn fails with from sklearn.base import clone, EnvRepair relinks the sklearn stack (numpy, scipy, scikit-learn) before relinking imbalanced-learn.
  • If sklearn still fails in the same chain, EnvRepair also relinks numpy + scipy + scikit-learn.
  • If pyarrow reports DLL/procedure mismatch, EnvRepair relinks libarrow + pyarrow.
  • If pygithub fails in its import chain, EnvRepair relinks requests + pynacl + pygithub.
  • pkg_resources is treated as legacy and skipped to avoid pip/conda thrash loops.
  • For stubborn compiled/import-chain packages (pyarrow, scikit-learn, imbalanced-learn, pygithub, streamlit), EnvRepair now performs a targeted pre-clean of stale site-packages artifacts before conda relink.
  • If pyarrow, github, or streamlit still fail after conda repair, EnvRepair runs a last-chance pip wheel reinstall for exactly those imports and rechecks immediately.
  • For pygithub, EnvRepair now performs a hard conda remove before reinstall when needed, to recover from partial module-tree loss (No module named 'github').
  • For pygithub failures involving nacl._sodium DLL load issues, EnvRepair additionally relinks libsodium + pynacl in the same repair batch.
  • Solver offender parsing accepts more libmamba output variants (name =* * does not exist and name ==x ... does not exist) to avoid false negatives in blacklist/retry logic.

📁 Files

  • env_repair.py – CLI shim (kept for convenience).
  • env_repair/ – actual implementation.
  • docs/ – design notes, feature specs, and roadmaps.

📦 Releases

PyPI releases are automated via GitHub Actions (Trusted Publishing) on tags:

  • vX.Y.Z → .github/workflows/release-pypi.yml

conda-forge publishing is done via a feedstock (standard conda-forge process). For details see:

  • docs/releasing.md

Local conda recipe (for testing) lives in:

  • conda.recipe/

❤️ Philosophy

EnvRepair is opinionated, but cautious.
It prefers understanding and repair over brute-force reinstallation.

If you’ve ever said “I’ll just recreate the environment…”
EnvRepair is here to save you that hour.

Metadata

Release files for env-repair 0.2.7

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for env-repair 0.2.7
File Size Uploaded Provenance Actions
env_repair-0.2.7.tar.gz 73.1 kB With provenance Details for env_repair-0.2.7.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for env-repair 0.2.7
File Interpreter ABI Platform Actions
env_repair-0.2.7-py3-none-any.whl Python 3 none any Details for env_repair-0.2.7-py3-none-any.whl

Total release size: 136.9 kB

Release files / env_repair-0.2.7.tar.gz

Download URL env_repair-0.2.7.tar.gz
Size 73.1 kB
Tags Source
SHA-256 checksum
How to use checksums
6de7bb91b63fa50b6d59c51856066474be32f1f76200c7e2dd820edfd4b9aceb
BLAKE2b-256 checksum
How to use checksums
dacd9f6089cede774d8ad0875ae506d75e7ce61706f7a564ed0f7c7bc051d54b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 3, 2026.

Transparency log

Release files / env_repair-0.2.7-py3-none-any.whl

Download URL env_repair-0.2.7-py3-none-any.whl
Size 63.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
59772caaaca954f95348731d10682266e46837c6bab2df5de5ff9b537f0df969
BLAKE2b-256 checksum
How to use checksums
8ec6c668a38e6ae7e8899315bac4c9a3b1e41807086f864ce65f7dcd888261df
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 3, 2026.

Transparency log

Security for env-repair 0.2.7

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for env_repair-0.2.7.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 3, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page