Setting Up Jupyter Notebook on OSX Catalina
By: Robert Boscacci
Tags: Catalina, Python, Jupyter, Venv, Mac

Setting Up Jupyter Notebook on OSX Catalina

Image via PixaBay.com under Creative Commons

Intro

I try to avoid (ana)conda when I can. I prefer PyEnv.

Lately, I’ve found myself repeatedly fumbling trying to get Jupyter up and running and packages like pandas importing properly. Maybe this had to do with recent upgrades to my OS (to Catalina) or switching from bash to zsh as my primary shell. In any case, I’d like to lay out some steps to repeatably getting jupyter notebooks running on OSX Catalina, in a normal (brew/pyenv) python virtual environment, without conda.

Steps Overview

Here’s the 9-step-process that seems to be working for me right now:

Via zsh: Install homebrew Via homebrew: Install pyenv Via homebrew: Install jupyter (maybe unnecessary) Via Pyenv: Install python (3.8.x) Via venv: Make a virtual env Activate the virtual env Via pip: Install jupyter to the venv Via pip: Install ipykernel to the venv Via ipykernel: Give knowledge of the new venv to jupyter

Maybe you can manage these steps on your own without reading further.

You should only have to do steps 1 through 4 once, then you’re set to make a different python 3.8.[x] virtual env for each code project where you plan to use jupyter.

Steps In Some Detail

1. Install Homebrew via zsh

zsh is the new default shell in Catalina. I made it my primary shell.

Brew is the missing package manager for osx. It’s great, go get it.

Drink a cup of tea while it downloads Xcode tools for you if it needs to.

2. Install pyenv through Brew

Pyenv is fantastic for managing different python versions on mac. Once Brew is installed, you should be able to go into the mac terminal and type:

% brew search pyenv and it will be like, yes, that’s a thing you can install now:

(Using percent sign to denote shell prompt, do not type the percent signs)

Image by Author

So go ahead and do it:

% brew install pyenv

Then go to the Github page for pyenv and follow “the post-installation steps under Basic GitHub Checkout, starting with #3” taking note to “Modify your ~/.zshrc file instead of ~/.bash_profile ” if you’re on zsh and not bash.

3. Jupyter Can Be Installed via Brew

But I’m not totally sure that this is necessary. I did it:

% brew install jupyter but try skipping this step on the first go-around. This might just make redundant things.

4. Install python 3.8.x with PyEnv

Check to make sure you have pyenv installed:

% pyenv command should give you a menu now:

Image by Author

Now you can issue the command:

% pyenv install 3.8.6 or whichever python version tickles your fancy.

You should now be able to set this as your default python:

% pyenv global 3.8.6 to set 3.8.6 as global primary python.

To make sure everything is working so far, launch a new terminal window and issue some commands to see if pyenv is in charge of python in your shell now:

% python (then ctrl-d to exit python)

% which python

% python -V

Yep, pyenv is in charge of python in my shell now. (Image by Author)

Check % pyenv versions and % pyenv global :

Pyenv has installed python versions and made them global. (Image by Author)

Looking good. If you’re still seeing your base system python 2 launching when you ask for python , go back and figure out where you went astray. Did you carefully read the pyenv installation notes?

5. Make Virtual Env with Python

Now that you’re running a decently up to date version of python which is managed by pyenv which is managed by brew,

Navigate terminal to your current project folder:

% cd ~/Documents/

% mkdir project_folder

% cd project_folder

…and make a new regular old python virtual env:

% python -m venv "YOUR_VENV_NAME"

6. Activate Virtual Env:

% source YOUR_VENV_NAME/bin/activate

Now you’re in a shiny new python virtual environment. If you % pip list there shouldn’t be much listed:

(Image by Author)

7. Install jupyter with pip

% pip install jupyter

8. Install ipykernel with pip

% pip install ipykernel

9. Make Jupyter aware of your new python venv

At this point you should already be able to launch:

% jupyter notebook

But it might not be aware of site-packages installed in the venv, like if you:

% pip install pandas

You might still be having trouble getting it to import in a notebook.

That’s because you have yet to:

% python -m ipykernel install --user --name YOUR_VENV_NAME

(Image by Author)

Once you do that, you should be able to select that kernel in jupyter:

(Image by Author)

Done!

Now, any packages you install ( % pip install pandas ) while you’ve got your virtual environment activated should be importable in jupyter, as long as you have that venv’s corresponding kernel running in the notebook.

As mentioned previously, once you have pyenv installed, you can install whichever and however many versions of python you like, and swap out your global python version as you please. You can make as many virtual envs as needed—I enjoy making one per project—and installing jupyter into those venvs when required.

Conclusion

If you’ve gone through these steps carefully on a Mac running Catalina without success, and already tried some debugging on your own, please feel free to leave a comment. I suspect there may be some confounding factors, such as the fact that I am actually running OSX on PC hardware, amongst others.

I hope this helps! I know I’ll be referring back to this for my own purposes. I love having the flexibility to use pyenv and avoid installing conda, while still enjoying the capabilities of jupyter notebooks, but these steps are a little hard to remember offhand.