Jupyter Core

Warnings

• breaking Jupyter-core 5.9.0 and later require Python 3.10 or newer. Support for Python 3.7 was dropped in version 5.0.
  Fix: Ensure your Python environment is 3.10 or higher before upgrading to jupyter-core 5.9.x. For older versions, ensure Python 3.8+.
• deprecated The 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.
  Fix: Set JUPYTER_PLATFORM_DIRS in your environment to explicitly opt-in to the new behavior to suppress warnings and prepare for future versions.
• gotcha Version 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.
  Fix: Always 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.
• breaking In 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.
  Fix: Verify `pywin32` is explicitly installed if other components in your Jupyter ecosystem still have a direct requirement for it on Windows.
• gotcha Starting 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.
  Fix: If 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.
• breaking Version 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.
  Fix: Upgrade to jupyter-core 5.8.0 or a later version immediately, especially if deploying on Windows.

Install

• pip install jupyter-core Install latest version

Imports

• 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

  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

Quickstart

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}")