Where apps hide your files

Jupyter's config, data and kernel folders

Updated 2026-10-28 · 5 min read

Jupyter splits its files across config, data (which holds kernels) and runtime folders. The defaults on a Mac are below, and one command shows exactly which ones your install uses.

The locations

~/.jupyter                  config (settings files, JupyterLab settings)
~/Library/Jupyter           data (kernels, extensions)
~/Library/Jupyter/runtime   runtime (connection files for running servers)

These are the defaults in the current jupyter_core library, which every Jupyter app uses to decide its folders. Its source code sends the data folder on macOS to ~/Library/Jupyter, and running jupyter --paths on the Mac used for this guide printed exactly the three paths above.

Jupyter's documentation page on directories lists ~/Library/Application Support/Jupyter instead. That is the layout you get only when the JUPYTER_PLATFORM_DIRS environment variable is set to 1: then config, data and runtime all move under ~/Library/Application Support/Jupyter. If you followed a guide that set that variable, look there.

Ask Jupyter instead of guessing

jupyter --paths

This prints every config, data and runtime folder in search order, including the ones inside the active virtual or conda environment. For a single answer there are jupyter --config-dir, jupyter --data-dir and jupyter --runtime-dir. Adding --debug to jupyter --paths also explains which rules produced the list. A folder appears only after something writes to it, so on a fresh install some of these will not exist yet.

Config files

The ~/.jupyter folder is empty or missing until you create something. Typical files, by name:

File	Used by
jupyter_server_config.py	Jupyter Server, which runs JupyterLab and Notebook 7.
jupyter_notebook_config.py	The Notebook app (in Notebook 6 and earlier it also held the server settings).
jupyter_lab_config.py	JupyterLab specifics.
lab/user-settings/	Settings you change in JupyterLab's Settings Editor, stored as JSON.
lab/workspaces/	Saved JupyterLab workspace layouts.

Generate a starting file with jupyter server --generate-config, which writes it into the config folder. If a file already exists, the command asks before overwriting it, so answer no if you want to keep yours. A password you set with jupyter server password is stored as a hash in jupyter_server_config.json in the same folder, so treat the folder as private and keep it out of public dotfiles repositories. jupyter lab path prints JupyterLab's own folders.

Kernels

A kernel is a small folder holding a kernel.json that says which program to launch. See what is registered:

jupyter kernelspec list

That prints each kernel name with its folder, which is the quickest way to find where a given kernel lives. Jupyter looks in these places:

• folders named in JUPYTER_PATH, if you set it, first
• your user data folder's kernels subfolder: ~/Library/Jupyter/kernels by default
• the Python environment's own share/jupyter/kernels
• system-wide folders: /usr/local/share/jupyter/kernels and /usr/share/jupyter/kernels

Inside an activated virtual or conda environment, the environment's folder is searched before your user folder; outside one, your user folder comes first. The folder names are the kernel names, so python3 is usually the default Python kernel. Because a kernel points to a specific Python, a kernel created from one virtual environment keeps working only while that environment exists.

To register an environment as a kernel for your user, run python -m ipykernel install --user --name myenv from inside it. This writes a kernel.json into ~/Library/Jupyter/kernels/myenv and does not move your environment. To remove a kernel the supported way, use jupyter kernelspec uninstall myenv.

Environment variables that move things

Variable	Effect
JUPYTER_CONFIG_DIR	Use a different config folder.
JUPYTER_DATA_DIR	Use a different user data folder, kernels included.
JUPYTER_PATH	Extra data folders, searched first.
JUPYTER_RUNTIME_DIR	Use a different runtime folder.
JUPYTER_PLATFORM_DIRS	Set to 1 to use ~/Library/Application Support/Jupyter.

Inside an environment, jupyter --paths shows extra entries because each environment has its own etc/jupyter and share/jupyter folders, not because the variables changed.

Reading a kernel folder

Open any folder that jupyter kernelspec list printed. Inside is kernel.json (the launch command, display name and language) and often a few logo images. The launch command begins with the full path to a Python interpreter. If a kernel will not start after you deleted or moved a virtual environment, that path is the first thing to check, and the fix is to reinstall the kernel from the environment that exists now.

Old kernels from a Python you have since removed cost almost no space, but they clutter the kernel picker, and jupyter kernelspec uninstall <name> clears them cleanly.

Related folders

IPython keeps its own profile in ~/.ipython, with startup scripts and command history. Your notebooks (.ipynb files) are wherever you saved them, usually the folder where you launched Jupyter, not in any of the folders above.

Backups and a new Mac

Back up your notebooks and a list of packages (pip freeze, or conda env export) before the config. Kernels are cheap to recreate with ipykernel install. Config files are small and worth copying, once you have checked them for passwords and paths that only exist on the old Mac.

Why a normal search misses it

.jupyter is hidden, and ~/Library is left out of Spotlight and Finder searches, so a search for "kernel" finds nothing useful.

Finding it again

Type kernel.json into Everywhere to list every kernel definition across your user folder, environments and Homebrew folders at once, or jupyter_server_config for your config. Press ⌘↵ to reveal a result in Finder. It matches file names only, so it will not say which Python a kernel launches.

Common questions

Where is the Jupyter config directory on a Mac?

In ~/.jupyter by default. Run jupyter --config-dir to confirm the path your install uses.

Where are Jupyter kernels stored on macOS?

Your own kernels are in ~/Library/Jupyter/kernels by default, and environments keep theirs in share/jupyter/kernels. jupyter kernelspec list shows the exact folder for each kernel.

Why does the Jupyter documentation say Application Support?

That path applies when JUPYTER_PLATFORM_DIRS=1 is set. Without it, current Jupyter versions use ~/Library/Jupyter for data on a Mac, which jupyter --paths confirms.

How do I remove a Jupyter kernel?

Run jupyter kernelspec uninstall <name>, which removes the kernel's folder. It does not delete the Python environment it pointed to.