Upgrading or downgrading your Python version¶

Sometimes a package wants a newer Python. Sometimes you install a shiny new Python and discover that half the things you need aren't ready for it yet. Fun!

Either way, the fix is the same: pick the Python version you want, rebuild your environment, and reinstall your packages.

These instructions are for the shared data environment from the Python setup guide, using uv. They work in Terminal on macOS and Git Bash in Windows Terminal.

Which Python do you want?¶

For these setup guides, we're using Python 3.14. That's the version we'll use in the commands below.

If you're currently on 3.15, this is a downgrade. If you're on 3.13, it's an upgrade. Same commands! If you need a different version, replace 3.14 in the commands with the version you want.

Bigger numbers aren't always better. Versions with a, b, or rc in their names are previews, and packages might not work with them yet. For example, installing JupyterLab on Python 3.15.0b1 ran into a PyYAML build error that went away when we used Python 3.14.

If you just want to see whether a package works with another Python, you can try it in a temporary environment first.

Check what you're using now¶

Open a new command line. You should see (data) at the beginning of it. Run:

which python
python --version

The path should mention .venvs and data. The version tells you which Python is in that environment right now.

Already on the right version?

If it says Python 3.14.something and that's what you wanted, you're all set! You don't need to rebuild anything just to install Jupyter. Head over to the Jupyter setup guide.

If the path points somewhere else, go back to the Python setup guide before continuing. We want to make sure we're changing the right environment.

Save your package list¶

First, shut down Jupyter and any notebooks running in VS Code. If Jupyter is running in a command line, press Ctrl+C there to stop it.

With (data) still active, run:

uv pip freeze > ~/data-packages.txt

This saves a list of your installed packages and their versions in a file called data-packages.txt in your home folder. You can open it in VS Code if you want to see what's in there.

This is a list, not a backup of the packages themselves. We're going to reinstall them in a moment.

Replace your environment¶

Installing a new Python doesn't change an environment you already made. Your old data environment will happily keep using its old Python forever! We need to replace it.

Your installed packages will be removed

The --clear command below empties ~/.venvs/data and creates a fresh environment there. You'll need to reinstall your packages afterward. Notebooks and project files saved outside that folder are unaffected.

Run these commands one at a time:

deactivate
uv venv ~/.venvs/data --python 3.14 --seed --clear

The first command turns off the old environment. The second replaces it with one using Python 3.14, downloading Python if needed. --seed includes pip, so commands like %pip install will still work inside notebooks.

Wait for it to finish successfully before continuing. If it says it can't find the Python version you requested, update uv using the same method you used to install it, then try again:

macOS Windows

brew upgrade uv

winget upgrade --id=astral-sh.uv -e --source winget

Turn it back on¶

Close your command line and open a new one. The setup we did earlier should turn (data) on automatically.

If it doesn't, you can turn it on yourself:

macOS Windows

source ~/.venvs/data/bin/activate

source ~/.venvs/data/Scripts/activate

Confirm it worked

which python
python --version

The path should still mention .venvs and data, but the version should now say Python 3.14.something. Same place, different Python!

Reinstall your packages¶

Let's get Jupyter and a couple of our usual data packages back:

uv pip install jupyterlab notebook ipykernel pandas requests

You can use data-packages.txt as a reminder of anything else you need. If you'd like to try reinstalling everything at the exact versions you had before, run:

uv pip install -r ~/data-packages.txt

If that fails, an old package version might not work with your new Python. Read the error to see which package is causing trouble. You can install the packages you need by name, as we did above, to let uv choose compatible versions.

Reconnect Jupyter and VS Code¶

Give this Python the data name again:

python -m ipykernel install --user --name data --display-name data

Then start Jupyter:

jupyter lab

Choose data as your notebook's kernel. In VS Code, select data again and restart the kernel if you had a notebook open.

Confirm it worked

Run this in a notebook cell:

import sys
print(sys.executable)
print(sys.version)

The path should mention .venvs and data, and the version should start with 3.14. If the notebook still shows the old Python, shut down its kernel and select data again.

That's it! Your command line and your notebooks should now be using the same new Python.