Common Directories and File Locations

Jupyter stores different files (i.e. configuration, data, runtime) in a number of different locations. Environment variables may be set to customize for the location of each file type.

Jupyter separates data files (nbextensions, kernelspecs) from runtime files (logs, pid files, connection files) from configuration (config files, custom.js).

Configuration files

Config files are stored by default in the ~/.jupyter directory.

JUPYTER_CONFIG_DIR

Set this environment variable to use a particular directory, other than the default, for Jupyter config files.

Besides the JUPYTER_CONFIG_DIR, additional directories to search can be specified through JUPYTER_CONFIG_PATH.

JUPYTER_CONFIG_PATH

Set this environment variable to provide extra directories for the config search path. JUPYTER_CONFIG_PATH should contain a series of directories, separated by `` os.pathsep`` (; on Windows, : on Unix).

An example of where the JUPYTER_CONFIG_PATH can be set is if notebook or server extensions are installed in a custom prefix. Since notebook and server extensions are automatically enabled through configuration files, automatic enabling will only work if the custom prefix’s etc/jupyter directory is added to the Jupyter config search path.

Besides the user config directory mentioned above, Jupyter has a search path of additional locations from which a config file will be loaded. Here’s a table of the locations to be searched, in order of preference:

Unix	Windows
JUPYTER_CONFIG_DIR
JUPYTER_CONFIG_PATH
{sys.prefix}/etc/jupyter/
/usr/local/etc/jupyter/ /etc/jupyter/	%PROGRAMDATA%\jupyter\

To list the config directories currently being used you can run the below command from the command line:

jupyter --paths

The following command shows the config directory specifically:

jupyter --config-dir

Data files

Jupyter uses a search path to find installable data files, such as kernelspecs and notebook extensions. When searching for a resource, the code will search the search path starting at the first directory until it finds where the resource is contained.

Each category of file is in a subdirectory of each directory of the search path. For example, kernel specs are in kernels subdirectories.

JUPYTER_PATH

Set this environment variable to provide extra directories for the data search path. JUPYTER_PATH should contain a series of directories, separated by os.pathsep (; on Windows, : on Unix). Directories given in JUPYTER_PATH are searched before other locations. This is used in addition to other entries, rather than replacing any.

Linux (& other free desktops)	Mac	Windows
JUPYTER_PATH
JUPYTER_DATA_DIR or (if not set) ~/.local/share/jupyter/ (respects $XDG_DATA_HOME)	JUPYTER_DATA_DIR or (if not set) ~/Library/Jupyter	JUPYTER_DATA_DIR or (if not set) %APPDATA%\jupyter
{sys.prefix}/share/jupyter/
/usr/local/share/jupyter /usr/share/jupyter		%PROGRAMDATA\jupyter

The config directory for Jupyter data files, which contain non-transient, non-configuration files. Examples include kernelspecs, nbextensions, or voila templates.

JUPYTER_DATA_DIR

Set this environment variable to use a particular directory, other than the default, as the user data directory.

As mentioned above, to list the config directories currently being used you can run the below command from the command line:

jupyter --paths

The following command shows the data directory specifically:

jupyter --data-dir

Runtime files

Things like connection files, which are only useful for the lifetime of a particular process, have a runtime directory.

These runtime files are stored in a runtime/ subdirectory of the user’s data directory (second row of the table above).

An environment variable may also be used to set the runtime directory.

JUPYTER_RUNTIME_DIR

Set this to override where Jupyter stores runtime files.

As mentioned above, to list the config directories currently being used you can run the below command from the command line:

jupyter --paths

The following command shows the runtime directory specifically:

jupyter --runtime-dir

Summary

JUPYTER_CONFIG_DIR for config file location

JUPYTER_CONFIG_PATH for config file locations

JUPYTER_PATH for datafile directory locations

JUPYTER_DATA_DIR for data file location

JUPYTER_RUNTIME_DIR for runtime file location

See also

jupyter_core.paths

The Python API to locate these directories.

The jupyter Command

Locate these directories from the command line.