{"id":526,"library":"jupyter-core","title":"Jupyter Core","description":"Jupyter-core is the foundational package that provides core common functionality for Jupyter projects. It includes base application classes, configuration management, and path utilities upon which other Jupyter components (like Jupyter Notebook, JupyterLab, and Jupyter Server) rely. Currently at version 5.9.1, it frequently receives patch releases for bug fixes and security updates, with minor and major versions introducing significant changes like Python version requirements and directory structure adjustments.","status":"active","version":"5.9.1","language":"python","source_language":"en","source_url":"https://github.com/jupyter/jupyter_core","tags":["jupyter","core","utility","paths","application","configuration"],"install":[{"cmd":"pip install jupyter-core","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"For determining appropriate platform-specific directories.","package":"platformdirs","optional":false},{"reason":"Jupyter's configuration system uses traitlets for flexible configuration.","package":"traitlets","optional":false},{"reason":"Provides shell tab completion for Jupyter command-line applications.","package":"argcomplete","optional":true}],"imports":[{"symbol":"jupyter_data_dir","correct":"from jupyter_core.paths import jupyter_data_dir"},{"symbol":"jupyter_config_dir","correct":"from jupyter_core.paths import jupyter_config_dir"},{"note":"The jupyter_path function is typically imported directly, not accessed via a module alias with an incorrect method name.","wrong":"import jupyter_core.paths as jp; jp.paths()","symbol":"jupyter_path","correct":"from jupyter_core.paths import jupyter_path"},{"symbol":"JupyterApp","correct":"from jupyter_core.application import JupyterApp"},{"symbol":"run_sync","correct":"from jupyter_core.utils import run_sync"}],"quickstart":{"code":"import os\nfrom jupyter_core.paths import jupyter_data_dir, jupyter_config_dir, jupyter_runtime_dir, jupyter_path\nfrom jupyter_core.application import JupyterApp\n\nprint(f\"Jupyter Data Directory: {jupyter_data_dir()}\")\nprint(f\"Jupyter Config Directory: {jupyter_config_dir()}\")\nprint(f\"Jupyter Runtime Directory: {jupyter_runtime_dir()}\")\n\nprint(\"\\nJupyter Search Paths (example of core configuration paths):\")\n# jupyter_path() returns a dictionary, typically with keys like 'data_path', 'config_path', 'runtime_path'\nfor path_type, paths in jupyter_path().items():\n    if paths:\n        print(f\"  {path_type.replace('_path', ' Path').replace('_', ' ').title()}:\")\n        for path in paths:\n            print(f\"    - {path}\")\n\n# JupyterApp is a base class, usually subclassed for actual applications.\n# This demonstrates its availability for inheritance.\nclass MyJupyterCoreApp(JupyterApp):\n    name = \"my-core-app\"\n    description = \"A simple example of subclassing JupyterApp\"\n\n    def initialize(self, argv=None):\n        super().initialize(argv)\n        self.log.info(f\"MyJupyterCoreApp initialized. Config file: {self.config_file}\")\n\n    def start(self):\n        self.log.info(\"MyJupyterCoreApp started.\")\n\nif __name__ == '__main__':\n    # Instantiate a dummy app to show it loads, but won't run a full loop without more setup\n    try:\n        app = MyJupyterCoreApp(argv=[]).initialize()\n        print(\"\\nSuccessfully initialized a basic JupyterApp instance.\")\n    except Exception as e:\n        print(f\"\\nCould not initialize MyJupyterCoreApp (expected for this minimal example): {e}\")\n","lang":"python","description":"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."},"warnings":[{"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+.","message":"Jupyter-core 5.9.0 and later require Python 3.10 or newer. Support for Python 3.7 was dropped in version 5.0.","severity":"breaking","affected_versions":">=5.0.0, >=5.9.0"},{"fix":"Set JUPYTER_PLATFORM_DIRS in your environment to explicitly opt-in to the new behavior to suppress warnings and prepare for future versions.","message":"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.","severity":"deprecated","affected_versions":">=5.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"5.9.0, 5.8.0"},{"fix":"Verify `pywin32` is explicitly installed if other components in your Jupyter ecosystem still have a direct requirement for it on Windows.","message":"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.","severity":"breaking","affected_versions":">=5.9.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=5.0.0"},{"fix":"Upgrade to jupyter-core 5.8.0 or a later version immediately, especially if deploying on Windows.","message":"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.","severity":"breaking","affected_versions":"<5.8.0"},{"fix":"To 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.","message":"The `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`.","severity":"breaking","affected_versions":">=4.0.0"}],"env_vars":null,"last_verified":"2026-05-12T14:40:06.829Z","next_check":"2026-06-26T00:00:00.000Z","problems":[{"fix":"Ensure `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`.","cause":"The `jupyter_core` package is not installed in the active Python environment or is not accessible to the Jupyter installation.","error":"ModuleNotFoundError: No module named 'jupyter_core'"},{"fix":"Ensure 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.","cause":"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.","error":"Error executing Jupyter command 'notebook': [Errno 2] No such file or directory"},{"fix":"Adjust 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.","cause":"The Jupyter application, often when attempting to create or write configuration or runtime files, lacks the necessary file system permissions for the specified directory.","error":"PermissionError: [Errno 13] Permission denied: '/usr/local/share/jupyter' (or similar path)"},{"fix":"Reinstall 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.","cause":"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.","error":"ImportError: DLL load failed: The specified module could not be found. (related to jupyter_core.paths and pywin32 on Windows)"},{"fix":"Upgrade 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.","cause":"There is a version incompatibility between `jupyter-core` and another core Jupyter package (like `jupyter-server` or `jupyter-client`) in your environment.","error":"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."}],"ecosystem":"pypi","meta_description":null,"install_score":100,"install_tag":"verified","quickstart_score":0,"quickstart_tag":"stale","pypi_latest":null,"install_checks":{"last_tested":"2026-05-12","tag":"verified","tag_description":"installs cleanly on critical runtimes, fast import, recently tested","results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.04,"mem_mb":2.1,"disk_size":"19.0M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.04,"mem_mb":2.1,"disk_size":"19M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.1,"mem_mb":2.4,"disk_size":"21.0M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.08,"mem_mb":2.4,"disk_size":"21M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.07,"mem_mb":2.1,"disk_size":"12.8M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.07,"mem_mb":2.1,"disk_size":"13M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.04,"mem_mb":2.1,"disk_size":"12.5M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.06,"mem_mb":1.9,"disk_size":"13M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.17,"mem_mb":5,"disk_size":"18.4M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.1,"mem_mb":5.1,"disk_size":"19M"}]},"quickstart_checks":{"last_tested":"2026-04-23","tag":"stale","tag_description":"widespread failures or data too old to trust","results":[{"runtime":"python:3.10-alpine","exit_code":1},{"runtime":"python:3.10-slim","exit_code":1},{"runtime":"python:3.11-alpine","exit_code":1},{"runtime":"python:3.11-slim","exit_code":1},{"runtime":"python:3.12-alpine","exit_code":1},{"runtime":"python:3.12-slim","exit_code":1},{"runtime":"python:3.13-alpine","exit_code":1},{"runtime":"python:3.13-slim","exit_code":1},{"runtime":"python:3.9-alpine","exit_code":1},{"runtime":"python:3.9-slim","exit_code":1}]}}