Install & Compatibility
Where this runs
tested against v5.9.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.058s · 19MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.9s · import 0.048s · 19MB
17MB installed
● package 17MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
jupyter_data_dir
✓ from jupyter_core.paths import jupyter_data_dir
jupyter_config_dir
✓ from jupyter_core.paths import jupyter_config_dir
jupyter_path
✓ from jupyter_core.paths import jupyter_path
✗ import jupyter_core.paths as jp; jp.paths()
The jupyter_path function is typically imported directly, not accessed via a module alias with an incorrect method name.
JupyterApp
✓ from jupyter_core.application import JupyterApp
run_sync
✓ from jupyter_core.utils import run_sync
Jupyter-core doesn't provide typical end-user functionality but offers core utilities. This quickstart demonstrates how to access standard Jupyter path information programmatically and shows the basic import of `JupyterApp`, which serves as a base for custom Jupyter applications.
import os
from jupyter_core.paths import jupyter_data_dir, jupyter_config_dir, jupyter_runtime_dir, jupyter_path
from jupyter_core.application import JupyterApp
print(f"Jupyter Data Directory: {jupyter_data_dir()}")
print(f"Jupyter Config Directory: {jupyter_config_dir()}")
print(f"Jupyter Runtime Directory: {jupyter_runtime_dir()}")
print("\nJupyter Search Paths (example of core configuration paths):")
# jupyter_path() returns a dictionary, typically with keys like 'data_path', 'config_path', 'runtime_path'
for path_type, paths in jupyter_path().items():
if paths:
print(f" {path_type.replace('_path', ' Path').replace('_', ' ').title()}:")
for path in paths:
print(f" - {path}")
# JupyterApp is a base class, usually subclassed for actual applications.
# This demonstrates its availability for inheritance.
class MyJupyterCoreApp(JupyterApp):
name = "my-core-app"
description = "A simple example of subclassing JupyterApp"
def initialize(self, argv=None):
super().initialize(argv)
self.log.info(f"MyJupyterCoreApp initialized. Config file: {self.config_file}")
def start(self):
self.log.info("MyJupyterCoreApp started.")
if __name__ == '__main__':
# Instantiate a dummy app to show it loads, but won't run a full loop without more setup
try:
app = MyJupyterCoreApp(argv=[]).initialize()
print("\nSuccessfully initialized a basic JupyterApp instance.")
except Exception as e:
print(f"\nCould not initialize MyJupyterCoreApp (expected for this minimal example): {e}")
jupyter --version
Debug
Known issues
breakingJupyter-core 5.9.0 and later require Python 3.10 or newer. Support for Python 3.7 was dropped in version 5.0.fixEnsure your Python environment is 3.10 or higher before upgrading to jupyter-core 5.9.x. For older versions, ensure Python 3.8+.
affects: >=5.0.0, >=5.9.0
deprecatedThe JUPYTER_PLATFORM_DIRS environment variable was introduced in v5.0 to opt-in to using more appropriate platform-specific directories. It raises a deprecation warning if not set. In future versions (v6 and v7), this behavior will become opt-out, then the environment variable checks and old directory logic will be entirely removed.fixSet JUPYTER_PLATFORM_DIRS in your environment to explicitly opt-in to the new behavior to suppress warnings and prepare for future versions.
affects: >=5.0.0
gotchaVersion 5.9.0 introduced a regression affecting Windows users (specifically a TypeError in filterwarnings()), which was fixed in 5.9.1. Similarly, 5.8.0 had a regression related to SYSTEM_CONFIG_PATH assumptions that was fixed in 5.8.1.fixAlways upgrade to the latest patch release (e.g., 5.9.1 or higher for 5.9.x stream, 5.8.1 or higher for 5.8.x stream) to avoid known regressions.
affects: 5.9.0, 5.8.0
breakingIn version 5.9.0, the dependency on `pywin32` for Windows was removed to unblock installation on free-threaded Python. While generally a positive change, existing setups that might have implicitly relied on `pywin32` being present through `jupyter-core` might need adjustments if other components still require it.fixVerify `pywin32` is explicitly installed if other components in your Jupyter ecosystem still have a direct requirement for it on Windows.
affects: >=5.9.0
gotchaStarting with version 5.0, Jupyter-core prioritizes environment-level configuration paths over user-level paths when running in a virtual environment. The `JUPYTER_PREFER_ENV_PATH` environment variable can be set to opt-out of this behavior if user-level paths should take precedence.fixIf your environment relies on a specific path priority, explicitly set `JUPYTER_PREFER_ENV_PATH` to '0' to prefer user directories or remove it to prefer environment directories.
affects: >=5.0.0
breakingVersion 5.8.0 included a security fix for CVE-2025-30167 / GHSA-33p9-3p43-82vq on Windows. This is a critical update for all Windows users.fixUpgrade to jupyter-core 5.8.0 or a later version immediately, especially if deploying on Windows.
affects: <5.8.0
breakingThe `jupyter_core.paths.jupyter_path()` function returns a list of directory paths, not a dictionary. Attempting to call the `.items()` method on its return value will result in an `AttributeError`.fixTo iterate over the paths, iterate directly over the list returned by `jupyter_core.paths.jupyter_path()`. If the intention is to retrieve different types of Jupyter paths categorized by type, separate functions like `jupyter_core.paths.jupyter_config_path()` and `jupyter_core.paths.jupyter_data_dir()` should be used and their outputs processed accordingly.
affects: >=4.0.0
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'jupyter_core'
The `jupyter_core` package is not installed in the active Python environment or is not accessible to the Jupyter installation.
fixEnsure `jupyter-core` is installed in your environment. If using pip, run `pip install jupyter-core`. If using conda, run `conda install jupyter-core`. If it's already installed, try upgrading it: `pip install --upgrade jupyter-core` or `conda update jupyter-core`.
Error executing Jupyter command 'notebook': [Errno 2] No such file or directory
The `jupyter` command or the `jupyter-notebook` executable is not found in the system's PATH, or the Jupyter installation itself is corrupted or incomplete.
fixEnsure Jupyter is correctly installed and its executables are in your system's PATH. Try reinstalling Jupyter: `pip uninstall jupyter jupyter_core notebook` then `pip install jupyter notebook`, or `conda uninstall jupyter_core notebook` then `conda install jupyter_core notebook`. You might also try running `python -m notebook` directly.
PermissionError: [Errno 13] Permission denied: '/usr/local/share/jupyter' (or similar path)
The Jupyter application, often when attempting to create or write configuration or runtime files, lacks the necessary file system permissions for the specified directory.
fixAdjust file permissions for the affected directory (e.g., `~/.jupyter`, `/usr/local/share/jupyter`, or `~/.local/share/jupyter`). On Linux/macOS, you might use `sudo chmod -R 775 /usr/local/share/jupyter` or `sudo chown -R $(whoami) ~/.jupyter` as appropriate for your setup, though care should be taken with `sudo` and broad permissions. Running `jupyter notebook --generate-config` might also create necessary directories with correct permissions.
ImportError: DLL load failed: The specified module could not be found. (related to jupyter_core.paths and pywin32 on Windows)
On Windows, this error typically occurs when the `pywin32` package, which `jupyter_core` uses for secure file operations, is either not installed correctly or is incompatible with the Python environment.
fixReinstall or upgrade the `pywin32` package: `pip uninstall pywin32` then `pip install pywin32`. Ensure your Python environment and `pywin32` installation match your system's architecture (32-bit or 64-bit). Sometimes, reinstalling Jupyter entirely can also resolve underlying dependency issues.
ERROR: jupyter-server X.X.X has requirement jupyter-core>=Y.Y.Y, but you'll have jupyter-core Z.Z.Z which is incompatible.
There is a version incompatibility between `jupyter-core` and another core Jupyter package (like `jupyter-server` or `jupyter-client`) in your environment.
fixUpgrade all related Jupyter packages to compatible versions. The safest way is often to perform a full upgrade: `pip install --upgrade jupyter jupyterlab jupyter_core jupyter_client jupyter_server traitlets nbformat`. If using conda, use `conda update --all` in the relevant environment or `conda install jupyter jupyterlab jupyter_core jupyter_client jupyter_server traitlets nbformat` to explicitly set up compatible versions.
Upgrade
Version history
5.9.1latest on PyPI · released Oct 16, 2025
Audit
Dependencies
platformdirsrequiredFor determining appropriate platform-specific directories.
traitletsrequiredJupyter's configuration system uses traitlets for flexible configuration.
argcompleteoptionalProvides shell tab completion for Jupyter command-line applications.