Fix 5 Python Setup Errors With One Command

pyfirstaid is a free tool that checks your Python environment and gives you a copy-paste fix for every problem.

You type pip install requests. It says “Successfully installed”. You feel good.

Then you run your script:

ModuleNotFoundError: No module named 'requests'

But you just installed it.

When I first hit this, I lost a whole evening. I reinstalled the package. I reinstalled Python. I opened twelve Stack Overflow tabs. Each answer fixed a different problem, and none of them told me which problem I had.

Here is the thing I learned later. Most of the time, your code is fine. Your environment is broken.

So I built a small tool that checks the environment for you, tells you what is wrong in plain English, and gives you the exact command to fix it. It is called pyfirstaid, and it is free and open source.

Try it now (30 seconds)

pip install pyfirstaid
python -m pyfirstaid

That is it. You get a list of checks. Each line starts with one of three symbols:

• ✔ means this part is fine.
• ! means a warning. Take a look.
• ✘ means a problem. Here is the fix.

If you only had 30 seconds, you are done. If you want to understand why these errors happen, keep reading.

The idea: a check-up, not surgery

Think about a visit to the doctor for a check-up. The doctor checks your heart, your blood pressure and your eyes. Then the doctor tells you what is wrong and which medicine to take. The doctor does not start an operation without asking you.

pyfirstaid works the same way. It runs 12 checks on your Python setup and prints a fix for every problem it finds. It only diagnoses. It never changes anything on your machine. You decide what to run.

A few words we will use, explained once:

• Environment: everything your Python uses when it runs. Which Python program, which installed packages, and which settings.
• Virtual environment (venv): a private box of packages for one project, so projects do not mix their packages.
• site-packages: the folder where pip puts the packages it installs. Every Python has its own.
• PATH: a list of folders your computer searches, in order, when you type a command like python3.

One command checks your whole Python setup and gives a fix for each problem.

Now let us look at the five errors I see most, one by one.

1. “ModuleNotFoundError” right after pip install

Imagine you have two kitchens in your house. You put the groceries in kitchen A. Then you go to kitchen B to cook. Of course the vegetables are not there.

This is exactly what happens when pip and python belong to different Pythons. Your computer can have many Pythons: the system one, one from Homebrew or python.org, one inside your project’s venv. The pip command might belong to one of them, while the python command runs another. The package goes into the first one’s site-packages. Your script runs with the second one, and it cannot see the package.

When pip and python point to different places, your package lands in the wrong one.

Check it:

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

The fix pyfirstaid gives is a habit worth learning anyway:

python -m pip install requests

python -m pip means “use the pip that belongs to this Python”. Groceries and cooking now happen in the same kitchen.

2. “module ‘random’ has no attribute ‘randint’”

Imagine a class with two kids named Ravi. The teacher calls “Ravi!”, and the wrong Ravi stands up.

When you write import random, Python looks for a module called random. And the first place it looks is the folder of your script. If you made a practice file called random.py there, Python happily loads your file instead of the real random module from the standard library. Your file has no randint, so you get a strange error.

This is called shadowing: your file hides a real module with the same name. It happens a lot with random.py, json.py, email.py and requests.py.

Python checks your folder first, so your file can hide a real module.

Check it:

python -m pyfirstaid --only shadowing

pyfirstaid names the exact file. The fix is to rename it (for example my_random.py) and delete any __pycache__ folder next to it.

3. “python3 –version” still shows the old version

You installed a new Python. You open a terminal, type python3 --version, and it still shows the old one.

Think of a postman with a list of houses. He checks the list from the top and delivers to the first house with the right name, even if there is a newer house with the same name further down.

Your PATH works like that list. When you type python3, your computer searches the PATH folders from top to bottom and runs the first python3 it finds. If the old Python’s folder is higher up, it wins.

The first match on PATH wins, even if it is the wrong Python.

Check it:

python3 -m pyfirstaid --only path,python-version

This shows which Python python and python3 really start. It also warns about two common traps: Apple’s built-in Python on macOS, and the Microsoft Store shortcut on Windows. And it flags Pythons that are past end of life.

4. “SSL: CERTIFICATE_VERIFY_FAILED” at work

This one hits many of us in office networks. At home pip install works. At work it fails with an SSL error.

Get Sai Gavaskar Sakalam’s stories in your inbox

Join Medium for free to get updates from this writer.

Remember me for faster sign in

Short version: many companies have a security system (a proxy) that opens and re-seals your secure internet traffic, like a security desk that opens every letter and puts it in a new envelope. Python does not recognise the new seal, so it refuses.

python -m pyfirstaid --only ssl

This checks whether HTTPS to pypi.org works, whether a proxy is in the way, and whether your certificate settings point at real files. I will cover this one properly in Part 2.

5. “ImportError” or “DLL load failed” after upgrading Python

Some packages, like numpy, contain compiled parts. These are built for one exact Python version. It is like a phone charger made for an old phone model. After you upgrade the phone, the plug does not fit.

If you upgrade Python but keep old packages around, or an install was stopped halfway, you get errors like ImportError, undefined symbol, or DLL load failed.

python -m pyfirstaid --only compiled,broken-installs

You get the exact reinstall command for the package that is broken.

A real run

Here is a real run inside a project folder that has three problems on purpose. The venv’s Python is running, but pip belongs to the system Python, and a file called random.py sits in the folder.

$ python -m pyfirstaid --share

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

✔ Python 3.13.1 (supported until October 2029)
✔ Virtual environment active: ~/project/.venv
✘ `pip` installs into a DIFFERENT Python
    pip    -> /opt/homebrew/lib/python3.13/site-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.
! Typing `python3` runs a DIFFERENT Python than this one
    python3 -> /opt/homebrew
    this Python -> ~/project/.venv
    fix: Activate the virtual environment you want, or call Python by its full path. To change the default, put the right Python's folder first in PATH.
✔ No PYTHONPATH / PYTHONHOME leaks
! `random.py` in this folder hides the standard library module `random`
    `import random` will load your file instead, which causes confusing errors like "module 'random' has no attribute ...".
    fix: Rename it (e.g. my_random.py) and delete any __pycache__ folder next to it.
✔ HTTPS to pypi.org works (OpenSSL 3.4.0 22 Oct 2024)
✔ 12 compiled package(s) match this Python
✔ No broken or duplicate installs (1 folder(s) scanned)
✔ No dependency conflicts (pip check)
✔ site-packages is writable
✔ Default text encoding is UTF-8

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

Read it from top to bottom:

• The first two lines tell you which Python was checked. This alone solves half of the confusion.
• The ✘ line is the two-kitchens problem from error 1, with both paths shown side by side.
• The two ! lines are the PATH problem (error 3) and the shadowing problem (error 2).
• Every warning and problem ends with a fix: line you can copy.
• --share replaced my home folder with ~, so this is safe to paste into a bug report.

The program also returns an exit code, a number that scripts and CI tools can read:

• 0 means no problems.
• 1 means problems were found.
• 2 means pyfirstaid itself failed.

Green means fine, yellow means take a look, red means fix it now.

All 12 checks at a glance

You do not need to remember these. Run python -m pyfirstaid --list any time. But here is what it looks at:

pyfirstaid’s 12 checks, grouped like a doctor’s check-up.

• Python and venv: python-version, venv, path, leaks
• Packages: pip-mismatch, shadowing, compiled, broken-installs, dependencies
• Network: ssl
• System: permissions, encoding

Why you can trust it

I know it feels risky to run a stranger’s tool on your machine. So here is how it is built:

• Zero dependencies. It uses only Python’s standard library. Python 3.9 or newer.
• Diagnose only. It never installs, deletes or changes anything.
• Works even when pip is broken. You can download a single file, pyfirstaid.pyz, from the GitHub releases page and run python pyfirstaid.pyz. No install needed.
• Privacy option. --share hides your username and home folder.
• Open source, MIT licence. The PyPI files are published straight from GitHub Actions, and PyPI shows the build proof (provenance) on the project page.
• Honest status. It is early (alpha), tested on Windows, macOS and Linux with Python 3.9 to 3.14. It does not cover conda yet (use conda doctor for that), or Poetry and pyenv specifics.

Tips and common mistakes

• Use python -m pip install, not pip install. This one habit prevents error 1 for good.
• Do not name your files after real modules. No random.py, json.py, test.py experiments in your project folder.
• Activate your venv before installing. If you forget, packages go into the wrong place.
• Installed pyfirstaid with pipx or uv tool? Then it lives in its own private environment, and it checks the Python behind python3 (it tells you so). To check a project’s venv, point at it: pyfirstaid --python .venv/bin/python.
• Run only what you need. --only ssl,path runs some checks. --skip ssl skips some. --offline skips checks that need the internet.

Recap

• Most “it works on my machine” problems are environment problems, not code problems.
• pip install pyfirstaid, then python -m pyfirstaid, checks 12 common causes.
• Every problem comes with a copy-paste fix, and nothing on your machine is changed.
• python -m pip install and good file names prevent the two most common errors.

Try it and tell me what it found

Run it once, even if nothing feels broken right now:

pip install pyfirstaid
python -m pyfirstaid

Then leave a comment with which check flagged something on your machine. I read every comment, and real cases decide which checks I build next.

If it helped you, a star on GitHub helps other people find it. And if you hit an environment error it does not catch yet, please open an issue with the error message.

• PyPI: https://pypi.org/project/pyfirstaid/
• GitHub: https://github.com/sai-sakalam/pyfirstaid
• Where the idea started: https://discuss.python.org/t/standard-library-health-check-module/105153

Next in this series: Part 2, “Python at work”: fixing SSL errors behind company proxies, and making your CI fail early when the environment is broken.