Migrating from IPython Notebook¶

Automatic migration of files¶

The first time you run any jupyter command, it will perform an automatic migration of files. The automatic migration process copies files, instead of moving files, leaving the originals in place and the copies in the Jupyter file locations. You can re-run the migration, if needed, by calling jupyter migrate. Your custom configuration will be migrated automatically and should work with Jupyter without further editing. When you update or modify your configuration in the future, please keep in mind that the file locations may have changed.

Where have my configuration files gone?¶

Also known as: “Why isn’t my configuration having any effect anymore?”

Jupyter splitting out from IPython means that the locations of some files have moved, and Jupyter projects have not inherited everything from how IPython did it.

When you start your first Jupyter application, the relevant configuration files are automatically copied to their new Jupyter locations. The original configuration files in the IPython locations have no effect on Jupyter’s execution. If you accidentally edit your original IPython config file, you may not see the desired effect with Jupyter now. You should check that you are editing Jupyter’s configuration file, and you should see the expected effect after restarting the Jupyter server.

Configuration files¶

Configuration files customize Jupyter to the user’s preferences. The migrated files should all be automatically copied to their new Jupyter locations. Here are the location changes:

To choose a directory location other than the default ~/.jupyter, set the JUPYTER_CONFIG_DIR environment variable. You may need to run jupyter migrate after setting the environment variable for files to be copied to the desired directory.

Data files: kernelspecs and notebook extensions¶

Data files include files, other than configuration files, which are user installed. Examples include kernelspecs and notebook extensions. Like the configuration files, data files are also automatically migrated to their new Jupyter locations.

In IPython 3, data files lived in ~/.ipython.

In Jupyter, data files use platform-appropriate locations:

• OS X: ~/Library/Jupyter
• Windows: the location specified in %APPDATA% environment variable
• Elsewhere, $XDG_DATA_HOME is respected, with the default of ~/.local/share/jupyter

In all cases, the JUPYTER_DATA_DIR environment variable can be used to set a location explicitly.

Data files installed system-wide (e.g. in /usr/local/share/jupyter) have not changed. Per-user installation of data files has changed location from .ipython to the platform-appropriate Jupyter location.

Changing the Jupyter notebook configuration directory¶

If you want to change the notebook configuration, you can set the JUPYTER_CONFIG_DIR:

JUPYTER_CONFIG_DIR=./jupyter_config
jupyter notebook

Changing the Jupyter notebook configuration file¶

If you just want to change the config file, you can do:

jupyter notebook --config=/path/to/myconfig.py

Changing kernelspecs¶

If you do want to change the IPython kernel’s profile, you can’t do this at the server command-line anymore. Kernel arguments must be changed by modifying the kernelspec. You can do this without relaunching the server. Kernelspec changes take effect every time you start a new kernel. However, there isn’t a great way to modify the kernelspecs. One approach uses jupyter kernelspec list to find the kernel.json file and then modifies it, e.g. kernels/python3/kernel.json, by hand. Alternatively, a2km is an experimental project that tries to make these things easier.

Notebook extensions¶

Any IPython notebook extensions should be automatically migrated as part of the data files migration.

Notebook extensions were installed with:

ipython install-nbextension [--user] EXTENSION

Now, extensions are installed with:

jupyter nbextension install [--user] EXTENSION

The notebook extensions will be installed in a system-wide location (e.g. /usr/local/share/jupyter/nbextensions). If doing a --user install, the notebook extensions will go in the JUPYTER_DATA_DIR location. Installation SHOULD NOT be done manually by guessing where the files should go.

Kernels¶

Kernels are installed in much the same way as notebook extensions. They will also be automatically migrated.

Kernel specs used to be installed with:

ipython kernelspec install [--user] KERNEL

They are now installed with:

jupyter kernelspec install [--user] KERNEL

By default, kernel specs will go in a system-wide location (e.g. /usr/local/share/jupyter/kernels). If doing a --user install, the kernel specs will go in the JUPYTER_DATA_DIR location. Installation SHOULD NOT be done manually by guessing where the files should go.