This article will help you troubleshoot and solve some of the issues you might encounter as you start moving to Python 3.x on MacOS, including path conflicts, pip installation problems, and virtual environment setup.
Preventing Python Problems
Most issues you will encounter are related to where Python is installed vs what paths are in your system path variables vs where pip is installing your Python modules. You need to make sure all of these file system paths match up, otherwise you’ll encounter issues where you install a package with pip, but Python still complains that the package is missing.
Use Virtual Environments
The best way to prevent problems is to install virtualenv at the system level and use virtual environments for everything else. Virtual environments isolate your Python projects and prevent conflicts between different package versions.
Key Rule: Avoid using sudo when installing Python packages. When you install a package using sudo, you install as the root user, which can cause permission conflicts later.
Reinstalling Python
A lot of issues can be resolved by simply re-installing Python. This is easy to do if you used Homebrew. Here’s how to clean up and reinstall Python properly:
Uninstall Existing Python
brew uninstall python2 python3
Reinstall Python
brew install python3
After this is done, test again and see if you are still getting errors. If you continue having trouble, try removing python2 and python3 again and only installing python3.
Checking System and Python Paths
The system path variables tell your terminal which file system paths to look at when you run a command. If you have your Python folder as part of the path variable, then you will be able to run the Python command to execute your scripts.
Check Your System PATH
echo $PATH
You should see a bunch of folders listed. Most likely you will see the /usr/bin folder listed. This is where you would expect the Python binary files to be located.
Check Python Installation Paths
A shortcut to see all the different Python paths on your system is to run the following commands:
python -c "import sys; print(sys.path)"
python3 -c "import sys; print(sys.path)"
Find Which Python You’re Using
If you are not sure the path of the Python installation you are currently using, you can type:
which python
which python3
which pip
which pip3
Python Installation Paths
Understanding where Python is installed on MacOS helps you troubleshoot path-related issues more effectively.
Default MacOS Python Location
/usr/local/bin/python
Homebrew Python Locations
- Python 3:
/usr/local/Cellar/python/<Python Version> - Python 2:
/usr/local/Cellar/python@2/<Python Version>
Adding to System Paths
If a path is incorrect, it can cause things to not work. There are two kinds of paths to look at: system paths (where the system looks to find executable files) and Python paths (where Python looks to find packages).
Modifying System Paths
Warning: Be very careful when modifying system paths in /etc/paths. Incorrect changes can break your entire system.
Adding Python Paths
To add a path to your Python 3 installation, start by finding your site-packages folder:
python3 -m site
Create a .pth file in your site-packages directory to add custom paths:
sudo vi /usr/local/lib/python3.7/site-packages/example.pth