pyfirstaid 🩹

First aid for broken Python environments. One command tells you what's broken and exactly how to fix it.

Status: v0.1, early. 3 checks work today, and more are on the roadmap. Feedback is very welcome in Issues. Which problems do you hit most?

Why

"It works on my machine" usually comes down to a broken environment: pip installing into a different Python than you run, SSL errors behind a corporate proxy, or a virtual environment that isn't active.

The errors are cryptic, the fixes are scattered across Stack Overflow, and there's no single command that checks it all.

This was discussed on the Python forum: Standard Library Health Check Module. The advice there was to start it as a package on PyPI.

Example

A real run: the virtual environment's Python is running, but the pip command on PATH belongs to the system Python:

$ python -m pyfirstaid

pyfirstaid 0.1.0: checking your Python environment
Python 3.13.1 (~/project/.venv/bin/python)

✔ Virtual environment active: ~/project/.venv
✘ `pip` installs into a DIFFERENT Python
    pip    -> /usr/lib/python3/dist-packages/pip (python 3.13)
    python -> ~/project/.venv/bin/python (python 3.13)
    fix: Use `python -m pip install <package>` instead of `pip install`. If a virtual environment should be active, activate it first.
✔ HTTPS to pypi.org works (OpenSSL 3.0.13 30 Jan 2024)

1 problem(s), 0 warning(s).

Try it

pyfirstaid is not on PyPI yet. To run it from source:

git clone https://github.com/sai-sakalam/pyfirstaid
cd pyfirstaid
python -m pip install .
python -m pyfirstaid

Or build the single file, which needs no install and works even when pip is broken:

python scripts/build_pyz.py
python dist/pyfirstaid.pyz

Options

Exit codes: 0 means no problems, 1 means problems were found, 2 means pyfirstaid itself failed.

Common situations

"I installed a package, but import says it doesn't exist."

python -m pyfirstaid --only pip-mismatch,venv

Usually pip installed into a different Python, or your virtual environment isn't active. pyfirstaid tells you which, and how to fix it.

"pip install fails with SSL: CERTIFICATE_VERIFY_FAILED at work."

python -m pyfirstaid --only ssl

This checks whether a company proxy is intercepting HTTPS and whether your certificate settings point at real files.

"I'm reporting a bug and the maintainer asked for my environment details."

python -m pyfirstaid --share

Paste the output into the issue. Your username and home folder are hidden.

"I want CI to fail if the environment is broken."

python -m pyfirstaid --offline --strict --json > env-report.json

The exit code is 1 if there are problems, and the JSON report can be saved as a build artifact.

"pip itself is broken, so I can't install anything."

Download pyfirstaid.pyz from the latest release and run:

python pyfirstaid.pyz

Checks

How is this different?

pyfirstaid's focus: diagnose the problem, explain it in plain English, and give a copy-paste fix.

Design principles

• Works when pip is broken. It runs as a single file (python pyfirstaid.pyz). A PyPI release is coming.
• Zero dependencies. Standard library only, Python 3.9+.
• Every problem comes with a fix command, not just a description.
• Conservative. It's better to miss an edge case than to raise a false alarm.
• Never crashes. A check that fails internally is reported, and the rest still run.
• Diagnose only. It never changes your environment.

Scope

In: pip, venv and uv on Windows, macOS and Linux. Out (for now): conda (use conda doctor), Poetry and pyenv specifics, automatic repair.

Contributing

• Hit an environment error? Open an issue with the error message, the cause and the fix. Real cases decide which checks come next.
• Development: python -m pip install -e ".[dev]", then python -m pytest and ruff check src tests.
• A new check is one file in src/pyfirstaid/checks/ that returns a list of Findings, registered in checks/__init__.py.

License

MIT