.. _jupyter_directories: Common Directories and File Locations ===================================== .. contents:: Contents :local: 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). .. _config_dir: Configuration files ------------------- Config files are stored by default in the :file:`~/.jupyter` directory. .. envvar:: JUPYTER_CONFIG_DIR Set this environment variable to use a particular directory, other than the default, for Jupyter config files. Besides the :envvar:`JUPYTER_CONFIG_DIR`, additional directories to search can be specified through :envvar:`JUPYTER_CONFIG_PATH`. .. envvar:: JUPYTER_CONFIG_PATH Set this environment variable to provide extra directories for the config search path. :envvar:`JUPYTER_CONFIG_PATH` should contain a series of directories, separated by `` os.pathsep`` (``;`` on Windows, ``:`` on Unix). An example of where the :envvar:`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 | +==============================+============================+ | :envvar:`JUPYTER_CONFIG_DIR` | +------------------------------+----------------------------+ | :envvar:`JUPYTER_CONFIG_PATH` | +-----------------------------------------------------------+ | ``{sys.prefix}/etc/jupyter/`` | +------------------------------+----------------------------+ | ``/usr/local/etc/jupyter/`` | ``%PROGRAMDATA%\jupyter\`` | | ``/etc/jupyter/`` | | +------------------------------+----------------------------+ To list the config directories currently being used you can run the below command from the :term:`command line`:: jupyter --paths The following command shows the config directory specifically:: jupyter --config-dir Data files ---------- .. _jupyter_path: Jupyter uses a search path to find installable data files, such as :ref:`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. .. envvar:: JUPYTER_PATH Set this environment variable to provide extra directories for the data search path. :envvar:`JUPYTER_PATH` should contain a series of directories, separated by ``os.pathsep`` (``;`` on Windows, ``:`` on Unix). Directories given in :envvar:`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 | +===============================+============================+============================+ | :envvar:`JUPYTER_PATH` | +-------------------------------+----------------------------+----------------------------+ | :envvar:`JUPYTER_DATA_DIR` | :envvar:`JUPYTER_DATA_DIR` | :envvar:`JUPYTER_DATA_DIR` | | or (if not set) | or (if not set) | or (if not set) | | ``~/.local/share/jupyter/`` | ``~/Library/Jupyter`` | ``%APPDATA%\jupyter`` | | (respects ``$XDG_DATA_HOME``) | | | +-------------------------------+----------------------------+----------------------------+ | ``{sys.prefix}/share/jupyter/`` | +-------------------------------+----------------------------+----------------------------+ | ``/usr/local/share/jupyter`` | ``%PROGRAMDATA\jupyter`` | | ``/usr/share/jupyter`` | | +-------------------------------+----------------------------+----------------------------+ .. _jupyter_data_dir: The config directory for Jupyter data files, which contain non-transient, non-configuration files. Examples include kernelspecs, nbextensions, or voila templates. .. envvar:: 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 :term:`command line`:: jupyter --paths The following command shows the data directory specifically:: jupyter --data-dir .. _jupyter_runtime_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. .. envvar:: 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 :term:`command line`:: jupyter --paths The following command shows the runtime directory specifically:: jupyter --runtime-dir Summary ------- :envvar:`JUPYTER_CONFIG_DIR` for config file location :envvar:`JUPYTER_CONFIG_PATH` for config file locations :envvar:`JUPYTER_PATH` for datafile directory locations :envvar:`JUPYTER_DATA_DIR` for data file location :envvar:`JUPYTER_RUNTIME_DIR` for runtime file location .. seealso:: :mod:`jupyter_core.paths` The Python API to locate these directories. :ref:`jupyter_command` Locate these directories from the command line.