Python has an interacting interpreter called REPL, and ipython is a generalization of REPL. When Jupyter is a working environment on Web browsers. Jupyter can have multiple kernels for each language to execute the code. If the coding language is Python, then Jupyter uses ipython kernel.

Jupyter is a notebook interface of Pyhton and works like Mathematica notebooks. One can immediately execute the program without compiling the code. Jupyter is one of the Python libraries. There are useful libraries such as sympy (Symbolic computation), TensorFlow (Machine learning).

Jupyter can be installed in several ways;

1. (minimal) by pip, the official package installer of Pyhton; should install additional modules later.
2. (simple) downloading OS X graphical version of Anaconda; should launch it from Application and not Terminal
3. (advanced) by Environment Isolation Tool (EIT); see also this page

These installations are completely independent. When you use Jupyter under EIT, you need to activate the particular virtual environment every time, rather than immediately typing jupyter notebook in Terminal.

If you do not want to skip installation troubles, the simplest way to use Python is to use Google Colab. However, you may lose the calculation results on Colab when you are disconnected from Internet.

Text editors such as Visual Studio Code can open .ipynb files. Another simple way is to use Google Colab.

Here we explain how to open a jupyter notebook, assuming we finished installation in Section 4.

First go to the folder where your code is found. Check the installed virtual environments by

$ pyenv virtualenvs

Activate the preferred virtual environment

pyenv activate environment_name

jupyter notebook

To use TensorFlow, follow the official instruction. There is also an instruction for Apple Silicon devices here. We use virtualenv to install TensorFlow. In other words, you install Jupyter below the TensorFlow folder, even if you have Jupyter elsewhere; see this post. Of course, one can work with other machine learning frameworks, other virtual environments of Python, and other bash profiles.

i) Launch TensorFlow from Terminal ¹

source ~/tensorflow/bin/activate

ii) Open Jupyter notebook ²

jupyter notebook

or

jupyter notebook filename.ipynb

iii) Copy & paste the URL shown in Terminal to the web browser:

http://localhost:8888/?token=(something)

To skip this step, try the tricks of this and that.

iv) We should terminate the virtual environment

source deactivate

If you use Anaconda, this should be

conda deactivate

Commands are executed by Shift+Return. "In []" becomes "[*]" during evaluating, and turns into "[number]" when it finishes.

People emphasize the importance of virtual environments, to check the consistency of python versions, package requirements and package installation trees. Several tools are available, such as pyenv-virtualenv, pyenv-virtualenv, Anaconda and Pipenv. Below I explain pyenv-virtualenv.

First, we install or upgrade pyenv by Homebrew,

brew install pyenv

brew install pyenv-virtualenv

To install Homebrew on Linux, see SE. The mirror in Tsinghua is useful if you are inside China. The system may automatically launch

brew cleanup

In case you find a permission error, try (see this post)

sudo chown -R $(whoami) $(brew --prefix)/*

Second, we install the latest version of Python. You can check it by the official website, or by typing

pyenv install --list

If the latest version is 3.x.y, you install it, change the python version of the current user, and refresh the status.³

pyenv install 3.x.y

pyenv global 3.x.y

eval "$(pyenv init -)"

We can check installed versions,

pyenv versions

python --version

pip -V

Do not forget to switch the python version in pyenv to the latest one, because the system (default) python does not contain pip.⁴

pyenv global 3.x.y

Third, we install (the latest version of) Jupyter. However, Jupyter is not in the pyenv's install list. A typical error is

pyenv: jupyter: command not found

We solve this problem under a virtual environment. For this purpose, let us create a virtual environment under the name environment_name.

pyenv virtualenv python_version environment_name

If we omit python_version, then the system uses the default environment specified by ~/.pyenv/version. We can check newly created environments by "$ pyenv versions".

pyenv activate environment_name

python3 -m pip install jupyter

We installed the Jupyter module under your environment. The last command is needed to avoid the error Defaulting to user installation because normal site-packages is not writeable; see this website. If the Jupyter module is not installed on the working environment, Python may launch the Jupyter installed on your system, which can cause extra troubles. Other modules can be installed in a similar way.

You should turn on a virtual environment whenever you launch a jupyter notebook,

pyenv activate environment_name

jupyter notebook

You can deactivate an environment by

pyenv deactivate

You can delete an environment by

pyenv virtualenv-delete environment_name

5. Troubleshooting

Check if your problem is related to the virtual environment or not. The difference between two notebooks can be checked by installing nbdime.

5-1. Error: module not found

One of the most common reason is that you did not switch iPython kernel. Check "Kernels > Switch Kernel" in the menu of Jupyter notebook.

If it does not solve the problem, the reason can be more complicated. For example

• Pyenv tries to use the same jupyter kernel for any virtual environments; see discussion here. You can localize Jupyter for each environment to avoid this problem. Try installing this plugin.
• Sometimes pip and Jupyter notebook use different paths or kernels. This means that, after you install some modules by pip inside a Jupyter notebook, the Jupyter kernel cannot detect the modules. See this discussion.
• Another possible workaound is to write a PATH to shims and not bin. A shim is an English word for something like a washer. See this page to find what shims do in pyenv.

5-2. Apple Silicon problems

Migration from Intel (x64) to Apple Silicon (ARM) causes a lot of problems for OSX users.

First, you need to reinstall Homebrew; see this page. Second, when two homebrew folders coexist (/usr/local/ for x64 and /opt/homebrew/ for ARM), some python packages find the old folder and cause errors. This can be avoided by deleting the wrong package from x64 homebrew; see discussion here. For example, one can remove a package by

/usr/local/bin/brew uninstall package_name

or completely remove the old brew by (cf. this page)

sudo /bin/zsh 

arch -x86_64 /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/uninstall.sh)"

Third, before installing python you should delete cache to avoid downloading x64 packages.

pip cache purge

pyenv install 3.11.2

for python and pyenv. Fourth, jupyter kernel may still die immediately after launch; see this page to fix it.

In my environment, several python versions are found at $HOME/Library/Python/X.Y/. These files seem to be installed by "pip --user" for Intel CPU, but they cannot be removed by "pip uninstall" anymore. Instead of deleting the files (and reinstalling XCode Command Line Tools), I deleted PYTHONPATH from $HOME/.zshrc. Then "jupyter notebook" launches the newly installed kernel.

Note that ZSH has several environment files. In particular, $HOME/.zprofile is loaded earlier than $HOME/.zshrc; see here.

6. Uninstall

We can remove the old version of Anaconda, python or unwanted virtual environments by

pyenv uninstall anaconda3-x.y.z

If we remove pyenv and pyenv-virtualenv, execute the following steps. First delete folders,

sudo rm -rf ~/.pyenv

Uninstall pyenv and pyenv-virtualenv using homebrew,

brew uninstall pyenv-virtualenv

brew uninstall pyenv

brew list

The last command checks whether you uninstalled pyenv and pyenv-virtualenv successfully.