Pre-Proposal: Project-Local Kernels in Jupyter

[mgab]

Summary

Enhance Jupyter to support project-local kernels, allowing the Jupyter server to detect and load kernels defined within a project directory (e.g. via local .jupyter_kernels/ or kernel.json), instead of relying only on global or user-scoped registrations.

This improves reproducibility and collaboration across languages (Python, R, Julia, etc.), while keeping kernel management explicit and language-agnostic.

Motivation

Jupyter’s current model assumes kernels are installed globally or per-user. This supports one common workflow, but not another that has become increasingly important:

1. Global / reusable environments

• A few environments are set up once (e.g. "data-science" Python, "Julia-1.10") and reused across many projects.
• Jupyter supports this well with global/user kernel.json files.

2. Project-local environments

• Each project declares and manages its own isolated runtime and dependencies (pyproject.toml, Project.toml, renv.lock, etc.).
• Favored for collaboration and reproducibility, but Jupyter requires users to manually create the environment, install the kernel machinery (e.g. ipykernel), and register it globally.
• This is repetitive, error-prone, and results in cluttered kernel lists.

Modern language ecosystems increasingly encourage per-project environments by default. Jupyter should align with this reality, making project kernels as easy as global ones.

Existing Alternatives and Related Work

• VS Code Jupyter extension
  • Detects virtual environments and kernels automatically, without requiring global registration.
  • Provides a smoother per-project workflow and demonstrates technical feasibility.
• nb_conda_kernels
  • Makes Conda environments available as Jupyter kernels.
  • Useful, but limited to Conda/Python.
• [pyproject-local-kernel](https://github.com/bluss/pyproject-local-kernel)
  • Searches for pyproject.toml, creates a virtualenv, installs ipykernel, and registers a kernel.
  • Python-specific and “magical”: implicitly manages environments, with no per-project control over ipykernel or its dependencies.
• Status quo (manual ipykernel install)
  • Requires per-user, per-project setup; weak reproducibility; global kernel clutter.

Proposed Approach

• Discovery mechanism
  • When Jupyter runs in a project directory, search for .jupyter_kernels/<name>/kernel.json or a single kernel.json at project root.
  • These kernels are scoped to the project session and do not pollute global kernel lists.
• Language-agnostic format
  • Use Jupyter’s existing kernel spec format.
  • Language-specific tools (Poetry, renv, Julia, etc.) may generate kernel specs, but Jupyter itself remains neutral.

Benefits

• Reproducibility: Kernel definitions live with the project.
• Collaboration: Teammates get the right kernel after restoring dependencies, no extra steps.
• Cleaner UX: Project kernels don’t clutter global lists.
• Language-agnostic: Works across ecosystems.
• Aligns with existing expectations (e.g. VS Code users).

[mgab]

I assumed this proposal qualified as a JET because it'd affec Jupyter Server behavior and user experience across all languages, but happy to redirect it somewhere else (e.g. jupyter core?) if that'd be more appropriate.

[krassowski]

This is a good pre-proposal IMO. Linking to a previous discussion jupyterlab/jupyterlab#16641. Also CC @bluss who was interested in this last year.

.jupyter_kernels

I would say we could just reuse .jupyter/ which is used by JupyterLab Desktop and jupyter-ai.

[minrk]

I think this makes good sense for how folks work these days, thanks for the proposal!

We've had security issues related to executable information without explicit user input based on loading config files from the working directory, is that going to lead to a similar issue here? Do we need some sort of trust or confirmation mechanism before accepting kernels from the working directory? I kind of hope not, but this seems somewhat similar to loading config files from the CWD. In general, the idea is supposed to be that opening a notebook (which includes starting a kernel) doesn't load untrusted code.

And for 'project' kernels, how to we resolve the project directory when a notebook might be in a sub-directory or the Jupyter server might be in a parent? Walk up until we see one, etc.?

[mgab]

I would say we could just reuse .jupyter/ which is used by JupyterLab Desktop and jupyter-ai.

Makes sense to me 👌

---

We've had security issues related to executable information without explicit user input based on loading config files from the working directory, is that going to lead to a similar issue here? Do we need some sort of trust or confirmation mechanism before accepting kernels from the working directory? I kind of hope not, but this seems somewhat similar to loading config files from the CWD. In general, the idea is supposed to be that opening a notebook (which includes starting a kernel) doesn't load untrusted code.

Oh, that's a good point! The approach I can think of is precisely VSCode, which asks for confirmation on whether the workspace (i.e. directory) can be trusted and remembers the decision for the user. In this case it might be more complex because the workspace is less clearly defined, so we might want to ask whether one can trust the kernel (perhaps identifying it with path and name?).

I'll give it a thought, but any suggestion or consideration is more than welcome 🤔

---

And for 'project' kernels, how to we resolve the project directory when a notebook might be in a sub-directory or the Jupyter server might be in a parent? Walk up until we see one, etc.?

I was thinking on walking up from the notebook folder until the root directory where the server was started.

A follow up question might be what happens if multiple .jupyter/ directories are found: one option might be to stay with the first one (e.g. what git does), but here I'd suggest to list them all (disambiguating them with the path if they have the same name).

Does that seem reasonable?

[bluss]

Thank you for writing about this. I want to say a lot more, but I want to clear up one misconception from the text first (unless I misread it)

pyproject-local-kernel
Searches for pyproject.toml, creates a virtualenv, installs ipykernel, and registers a kernel.
Python-specific and “magical”: implicitly manages environments, with no per-project control over ipykernel or its dependencies.

By default it uses uv. It wouldn't be considered very magical, it just sets up the environment as uv would do it. ipykernel and its dependencies are defined by pyproject.toml so I don't understand the comment here - dependencies on ipykernel version and dependencies are explicit in that file. There is control per project - the project is defined by pyproject.toml.

Another similar project is pixi-kernel, by the way.