Fix Python After Brew Upgrade in MacOS

When you run brew upgrade or brew upgrade <package>, all the packages are upgraded or packages linked to that particular package you want to upgrade gets updated. For Python, if the version upgrade is minor, then it should be fine. But major updates break a lot of development setup like, if you are used to develop using virtual environment, then you might have re-install every package. Real problem comes in when packages do not get installed in newer environment, then you need to downgrade your Python to make those packages work. Don’t worry though, here are steps on how you can fix this problem and prevent it from happening in future.

Bonus content: How to create and maintain multiple Python 3.XX versions in your system 💥.

Homebrew based solution

If everything works just fine

If you have everything working, then you should consider keeping that formula being upgraded in future. As per documentation, you can pin the formula like this:

brew pin python

Then next time you consider upgrading python, unpin the formula and run upgrade:

brew unpin python
brew upgrade

Upgrade/Downgrade to specific version

If you want to install specific version of Python, then install it using:

brew install python@3.8.6

Keep multiple Python versions in brew

But lets say you do not want to disrupt your current version of Python, rather you would have a different Python version installed or keep multiple Python versions, then you can tap a new formula like this:

brew install python@3.8

Then if you want to change back to other Python versions, then link like this:

brew link --force python@3.9

PyEnv based solution

If you are already nuked, then why not consider changing to pyenv. Reason is that, you can easily switch between Python environments and create virtual environments without any issues.

Install Python using pyenv

Please follow these steps to install Python:

1. To install PyEnv, you can use brew:

brew update
brew install pyenv

2. Then clone the repository to to get the latest version of pyenv

git clone https://github.com/pyenv/pyenv.git ~/.pyenv

3. Now, define your environment variables

echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.bash_profile
echo 'export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.bash_profile

Or if you are using zsh shell, then:

echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.zshrc
echo 'export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.zshrc

Or fish shell:

set -Ux PYENV_ROOT $HOME/.pyenv
set -Ux fish_user_paths $PYENV_ROOT/bin $fish_user_paths

4. Restart your shell so the path changes take effect

exec "$SHELL"

5. Verify the installation and check the available python versions

pyenv install --list

6. Install the required python version

brew install zlib readline openssl xz
pyenv install 3.8.6

7. Set it as your global version after installation

pyenv global 3.8.6

8. Verify your current python version the system is using

python3 --version

9. [Optional] Use pyenv-virtualenv plugin to control virtual environments.

Switch system Python in pyenv

You can easily switch Python versions in your system like this:

pyenv install 3.7.0
pyenv versions
pyenv global 3.7.0
python --version

Anaconda based solution

If you do not want to take hassle of pip, then consider anaconda based environment. You can install Python versions using:

conda install python=$pythonversion$

If you want to maintain multiple environments, then try like this:

conda create --name py36 python=3.6
conda activate py36

In Conclusion

Some casual brew upgrade can nuke your Python development setup, but it should be okay as long as you can solve it in minimal amount of time. Also as a bonus, now you can maintain multiple Python 3.XX versions in your machine 😄.

Thank you for reading. If you have any questions or concerns, please share via comment section below.

Last updated: Apr 05, 2024