Jupyter on your system: Commands, directories, files¶

The jupyter command¶

Jupyter applications are started with commands like jupyter notebook. The jupyter command is primarily a namespace for subcommands: a command like jupyter-foo found on your PATH will be available as a subcommand jupyter foo.

The jupyter command can also do a few basic things itself:

--help, -h¶: Show help information, including available subcommands.

--config-dir¶: Show the location of the config directory.

--data-dir¶: Show the location of the data directory.

--runtime-dir¶: Show the location of the data directory.

--paths¶: Show all Jupyter directories and search paths.

--json¶: Print directories and search paths in machine-readable JSON format.

Jupyter directories¶

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

Configuration¶

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

JUPYTER_CONFIG_DIR¶: Set this environment variable to use a directory, other than the above default, for Jupyter config files.

Besides the main user config directory mentioned above, Jupyter has a search path of additional locations from which config will be loaded. Here’s a table of the locations:

Unix	Windows
Config directory
`{sys.prefix}/etc/jupyter/`
`/usr/local/etc/jupyter/` `/etc/jupyter/`	`%PROGRAMDATA%\jupyter\`

Data files¶

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

Each category of file in here is in a subdirectory of each directory of the search path. E.g. kernel specs are in kernels subdirectories.

JUPYTER_PATH¶: Set this environment variable to provide extra directories for the data search path. It should be a series of directory paths, separated by os.pathsep (i.e. ; on Windows, : on Unix). Directories given in JUPTYER_PATH are searched first.

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

Runtime files¶

Things like connection files, which are only useful for the lifetime of a specific process, have their own directory.

On Linux and other free desktop platforms, these runtime files are stored in $XDG_RUNTIME_DIR/jupyter by default. On other platforms, it’s a runtime/ subdirectory of the user’s data directory (second row of the table above).

An environment variable may also be set:

JUPYTER_RUNTIME_DIR¶: Set this to override where Jupyter stores runtime files.