How to Fix A B0rked Python Environment

If you’ve spent any time working with Python environments you’re bound to have run into errors such as pip: command not found, No module named pip, ModuleNotFoundError: No module named 'distutils.util', or other Python 2.x vs Python 3.x issues. The purpose of this guide is to help troubleshoot common Python environment issues; at the very least after following these instructions you’ll have sufficient information to provide an online forum or another engineer to help them troubleshoot with you.

Step Zero: Remain calm. Don’t panic. Anyone who has ever worked a help desk, or emergency services, knows the worst thing you can do in a stressful situation is panic. If you are working on a normal computer system then configuration files can be rebuilt, software can be uninstalled and reinstalled, backups can be restored (assuming backups were made 😳). Things can be fixed.

Caveat: if you are running on Microsoft Windows, I personally can’t help much. May I strongly recommend running a version of Linux next to Windows to make Python programming significantly easier.

Now, let’s find out what version of Python is the default for your environment. On Linux, Mac OSX, and even Windows the command is the same.

python --version

You should see something like Python X.Y.Z. These three numbers are very important. Pay particular attention if the first number is 2, as this means your default Python interpreter is version 2 which was sunsetted January 1st 2020. If this is the case, let’s check to see if you have a newer version of Python installed next to Python 2.

python3 --version

Once we’re confident that python is, in fact, installed let’s see where it is installed.

which python which python3

These commands should almost always return /usr/bin/python and /usr/bin/python3 respectively. If they do not, this could mean that you are using a virtual environment, pyenv, deadsnakes or something similar. If this is the case, you can recreate the environment by using the documentation from the specific tool you are using.

Let’s now go through inspecting typical environment variables that can point python to strange and horrible places in your system.

env | grep PYTHON

Python’s documentation lists a number of environment variables that control how Python should run. If any of these variables are set to something unexpected, you should restore them to sane values or completely unset these environment variables. Use simple deductive reasoning to determine expected values. If your default python interpreter is 3.6.9 then you should expect to see version 3.6.9 for any environment variables set. If python is installed in /usr/bin you should expect to see environment variables set to /usr/lib or /usr/local/lib not something like ~/.env/.

After this we should check to make sure nothing is trying to hijack the python executable from your shell. Checking your shell’s environment will uncover any of these issues. Examples include a nonstandard PATH environment, an alias, or settings in ~/.profile or ~/.bashrc. Again, I’d recommend deductive reasoning to spot errors. Python tends to use the word python within environments, so common glaring issues are easy to spot.

Troubleshooting environment issues can be frustrating. With a little reasoning, base knowledge of how Python is called, and stubborn persistence I’m confident practically any environment can be brought back to a functional state.

Good luck and happy troubleshootin'!