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

--prefer mamba is the default, both for one-shot and the regular scan/fix. Conda packages use mamba whenever it is available in PATH; otherwise conda is the fallback. A failed mamba info call does not switch repairs to conda. Successful mamba discovery uses mamba env list and does not additionally invoke conda info; channel discovery also prefers mamba when external tooling is needed. The bootstrap health check still diagnoses an installed conda separately, even when mamba is the installer. These diagnostic calls do not change the selected installer. Failures are captured (health probes time out after 30 seconds), and known dependency errors are repaired using mamba and local conda-meta records before retrying conda. Conda error-report uploads are disabled for health probes. If the same dependency error survives relinking, bootstrap repair requests a strictly newer version of the affected provider and checks conda health again. It respects pins and does not uninstall the package or its dependents first. --prefer auto and --prefer conda retain this executable selection; --prefer pip prefers pip packages when fixing duplicates.

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

  • A parallel import timeout is retried sequentially with a 90-second limit. If it still times out, --fix can request a strictly newer version of an identified conda-managed distribution, respecting pins and checking the import again. Local/pip-only packages are not upgraded for timeouts. Remaining timeouts produce complete: false in the report and exit code 1; they are not silently counted as successful checks.

  • Shared dependency failures (including missing distribution metadata and module attribute errors) are repaired before dependent packages, with conda targets batched together. Unresolved consumers are reported as defer, not silently counted as repaired or repeatedly uninstalled.

  • Duplicate cleanup preserves a valid .dist-info directory and keeps the repair pending until reinstallation succeeds. Conda-owned metadata is preferred.

  • After repairing charset-normalizer, unowned Windows .pyd files shadowing existing conda-owned cd/md modules (Python source or binary extensions) are moved into the target environment's .env_repair/quarantine/ directory rather than deleted. Repair actions include original and quarantine paths; conda-owned extensions are left untouched.

  • 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.8

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.8
File Size Uploaded Provenance Actions
env_repair-0.2.8.tar.gz 81.5 kB With provenance Details for env_repair-0.2.8.tar.gz

Built distribution (wheel)

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

Total release size: 152.6 kB

Release files / env_repair-0.2.8.tar.gz

Download URL env_repair-0.2.8.tar.gz
Size 81.5 kB
Tags Source
SHA-256 checksum
How to use checksums
1f7f6123c8d223204cef1d51fc2b00f1be3cd4816d620fa91f6ed19f5efcd07e
BLAKE2b-256 checksum
How to use checksums
ff3355a1c20ed9b5dcae25d5eca40f834722f76f4464e74a0449388991222110
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

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 Nov 1, 2026.

Transparency log

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

Download URL env_repair-0.2.8-py3-none-any.whl
Size 71.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
f38e6ce69df64c3f67bc0d675acf51d4aaf9f201af7061fab91405c8fe08a0be
BLAKE2b-256 checksum
How to use checksums
a4765d6084753242a158c10f5890de85aa1c33eb60edb40f8a91f960bc2e9cac
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

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 Nov 1, 2026.

Transparency log

Security for env-repair 0.2.8

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.8.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 Nov 1, 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