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'!
-Sethers
P.S. You may also want to check out this quick overview of how I setup my Python environments.