🩺 EnvRepair 
Fixing broken Python environments – safely, transparently, reproducibly
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-infofolders - mysterious
.pydconflicts on Windows conda-metaJSON 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.pydduplicates). - Find corrupted or incomplete
conda-metaentries. - 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.
mambain PATH for conda-style envs (preferred).conda/micromambaare supported when available.condais 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.exesyntax (.batblocks).
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:
rrestore from snapshotccontinue (skip)aabort (default)
- A
.env_repair\state.jsonfile 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.
shon Windows,ptyprocessmissingfcntlon 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-pipinstalls only mapped PyPI packages.--adopt-pipis conda-only; for plain venvs it is ignored.- After successful adoption, env-repair uninstalls the pip version by default; use
--keep-pipto skip. - For alias-like mappings (e.g. pip
msgpack→ condamsgpack-python), pip is only removed if both versions match. - Channels are loaded from
.condarcfirst, thendefaultsandanacondaunless disabled. --debugprints the exact external command lines as[cmd] ...(mamba/conda/pip), and streams live output to keep long operations transparent.- If
condacore is broken after updates, env-repair can auto-repair it in two stages: core packages first, thenpython/menuinstwhen health remains degraded or mixed ABI.pydresidue is detected. - For automated runs (CI/itest), set
ENV_REPAIR_AUTO_YES=1to bypass interactive confirmation prompts. - On Windows,
duplicate-pydissues from mixed Python ABI residues are now cleaned directly by removing stale.pydfiles 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-bindingspkg_resources->setuptools
- For Streamlit protobuf runtime/codegen mismatch (
_CheckCalledFromGeneratedFile), EnvRepair now schedules:protobuf>=4,<7alignmentstreamlit>=1.30upgrade/relink
- If
imblearnfails withfrom sklearn.base import clone, EnvRepair relinks the sklearn stack (numpy,scipy,scikit-learn) before relinkingimbalanced-learn. - If
sklearnstill fails in the same chain, EnvRepair also relinksnumpy+scipy+scikit-learn. - If
pyarrowreports DLL/procedure mismatch, EnvRepair relinkslibarrow+pyarrow. - If
pygithubfails in its import chain, EnvRepair relinksrequests+pynacl+pygithub. pkg_resourcesis 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, orstreamlitstill 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
pygithubfailures involvingnacl._sodiumDLL load issues, EnvRepair additionally relinkslibsodium+pynaclin the same repair batch. - Solver offender parsing accepts more libmamba output variants (
name =* * does not existandname ==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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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 logRelease 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 logSecurity 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.
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 logA 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.