Home/Blog/Python MacOS Troubleshoot | Fix Path Issues
Python

Python MacOS Troubleshoot | Fix Path Issues

Fix path issues, upgrade to Python 3, and resolve pip conflicts with virtual environments

Python MacOS Troubleshoot | Fix Path Issues

MacOS ships with Python 2.7 pre-installed, which is helpful when you’re just getting started with Python. However, Python 2.7 reached end-of-life in 2020, so everyone needs to upgrade to Python 3. When you start upgrading Python, there’s a good chance that Python will get messed up on your computer.

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

Frequently Asked Questions

Find answers to common questions

Managing multiple Python versions on MacOS can be challenging, especially considering that MacOS ships with Python 2.7 pre-installed. To effectively manage multiple versions and avoid path conflicts, it's crucial to use a version management tool such as `pyenv`. This tool allows you to easily switch between Python versions and ensures that the correct version is being used for your projects. 1. **Install pyenv**: If you haven't already, install `pyenv` using Homebrew with the following command: ```bash brew update brew install pyenv ``` 2. **Configure your shell**: After installing `pyenv`, you need to add it to your shell configuration file (e.g., `~/.bash_profile`, `~/.zshrc`). Add the following lines: ```bash export PATH="$HOME/.pyenv/bin:$PATH" eval "$(pyenv init --path)" eval "$(pyenv init -)" ``` Reload your shell configuration using `source ~/.bash_profile` or `source ~/.zshrc`. 3. **Install Python versions**: Use `pyenv` to install the desired Python versions. For example, to install Python 3.9.6, run: ```bash pyenv install 3.9.6 ``` 4. **Set global or local Python version**: You can set a global Python version that will be used across your system or a local version for a specific project directory. To set a global version, use: ```bash pyenv global 3.9.6 ``` For a specific project directory, navigate to that directory and run: ```bash pyenv local 3.9.6 ``` 5. **Verify your setup**: You can verify which Python version is currently active by running: ```bash python --version ``` This command should return the version set by `pyenv`. By following these steps, you can effectively manage multiple Python versions on MacOS, avoiding common path conflicts. Additionally, ensure that you are not mixing installations by checking that your system path variables are correctly configured to prioritize `pyenv` paths.

Automate Your IT Operations

Leverage automation to improve efficiency, reduce errors, and free up your team for strategic work.