{"id":15467796,"url":"https://github.com/bluss/pyproject-local-kernel","last_synced_at":"2025-06-14T15:04:29.831Z","repository":{"id":228669374,"uuid":"774600439","full_name":"bluss/pyproject-local-kernel","owner":"bluss","description":"Python Jupyter kernel provisioner using pyproject environment manangers like Uv, Rye, PDM, Poetry, Hatch etc.","archived":false,"fork":false,"pushed_at":"2024-11-24T11:50:51.000Z","size":1673,"stargazers_count":37,"open_issues_count":2,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-06-13T00:06:01.567Z","etag":null,"topics":["jupyter","uv","virtualenv"],"latest_commit_sha":null,"homepage":"https://bluss.github.io/pyproject-local-kernel/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bluss.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-03-19T20:46:51.000Z","updated_at":"2025-04-29T10:56:23.000Z","dependencies_parsed_at":"2024-08-16T17:08:32.940Z","dependency_job_id":"fe4c3846-5e98-429d-a8d4-20cb29086342","html_url":"https://github.com/bluss/pyproject-local-kernel","commit_stats":{"total_commits":302,"total_committers":6,"mean_commits":"50.333333333333336","dds":0.04966887417218546,"last_synced_commit":"ac7ade13176e274da7c8e4fbfbd67a92a4943b84"},"previous_names":["bluss/pyproject-local-kernel"],"tags_count":22,"template":false,"template_full_name":null,"purl":"pkg:github/bluss/pyproject-local-kernel","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bluss%2Fpyproject-local-kernel","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bluss%2Fpyproject-local-kernel/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bluss%2Fpyproject-local-kernel/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bluss%2Fpyproject-local-kernel/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bluss","download_url":"https://codeload.github.com/bluss/pyproject-local-kernel/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bluss%2Fpyproject-local-kernel/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259835382,"owners_count":22918975,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["jupyter","uv","virtualenv"],"created_at":"2024-10-02T01:26:34.649Z","updated_at":"2025-06-14T15:04:29.809Z","avatar_url":"https://github.com/bluss.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\n# Pyproject Local Jupyter Kernel\n\n\u003cp class=\"web_hidden\"\u003e\n\n[Website][] - [PyPI][] [![PyPI - Python Version](https://img.shields.io/pypi/v/pyproject-local-kernel)][PyPi]\n\n\u003c/p\u003e\n\nSeparate dependencies for Jupyter notebooks - each notebook\nproject can have its own dependencies!\n\n[Website]: https://bluss.github.io/pyproject-local-kernel/\n[PyPi]: https://pypi.org/project/pyproject-local-kernel/\n\nInstead of installing a myriad of Jupyter kernelspecs, one per project, with\nthis solution there is only one [kernel provisioner][kp] that enables the\nenvironment for the project the notebook file resides in. This approach should\nbe more portable, usable to anyone who checks out your project structure from\ngit, and easier to use.\n\nPyproject Local supports **Uv, Poetry, Hatch, Rye, and PDM**\nand reads `pyproject.toml` to figure out which kind of project it is.\nOr it can use a custom command or a bare virtual environment directly.\n\n[kp]: https://jupyter-client.readthedocs.io/en/latest/provisioning.html\n\n![screenshot of notebook launcher](https://raw.githubusercontent.com/bluss/pyproject-local-kernel/main/docs/images/pyproject-local.png)\n\n## Quick Start (JupyterLab)\n\n1. Install pyproject-local-kernel in your Jupyterlab environment and restart\n   Jupyterlab\n2. Create a new directory for the notebook project\n3. Create a new notebook and select the **Pyproject Local** kernel\n4. In the *“fallback”* environment that appears - because it is an empty\n   project - create a new project.\n\n  (Example for Uv:)\n\n  `!uv init \u0026\u0026 uv add ipykernel`\n\n5. Use the restart button in JupyterLab to restart the kernel after these changes.\n6. Dependencies will quickly sync and you are good to go!\n7. Use more `add` commands to add further dependencies.\n\n\nSee the examples directory for how to setup Jupyterlab and notebook projects\nseparately. JupyterLab and the notebook are installed in separate environments.\n\n\nDo you want to use pyproject-local-kernel in other environments, like with\npapermill, **VSCodium or VS Code**, or or other ways? See our [FAQ][] for more\ninformation.\n\n[FAQ]: FAQ.md\n\n## User Experience\n\nIf started in an empty directory or where a project is not correctly set up,\nthe Pyproject Local will fail to start normally, but it will start a fallback\nkernel so that you can fix the project.\n\nIt will show a message like this - with some details about the error.\n\n```diff\n! Error: Could not find `ipykernel` in environment.\n! Add `ipykernel` as a dependency in your project and update the virtual environment.\n! The detected project type is: Unknown\n!\n! This is a fallback - pyproject-local-kernel failed to start.\n! The purpose of the fallback is to let you run shell commands to fix the\n! environment - when you are done, restart the kernel and try again!\n```\n\nRemember that you can also use Jupyterlab's embedded terminal to help setting\nup a project.\n\n***If `pyproject.toml` is Missing***\n\nIf the Pyproject Local kernel is selected in a project where there is no `pyproject.toml`,\nthen starting the kernel fails. On first run it should show an error message in JupyterLab.\n\nIf this happens, create a new `pyproject.toml` with the editor or use\none of the project init commands to create a new project.\n\n***If the `ipykernel` is Missing***\n\nThe notebook project needs to install `ipykernel` as a dependency.\n\nEdit the `pyproject.toml` to include `ipykernel` in dependencies:\n\n```toml\ndependencies = [\n    \"ipykernel\u003e=6.29\",\n    # .. more dependencies\n]\n```\n\nsync the changes to the project using sync command for the project\nmanager you use, then restart the Pyproject local kernel in Jupyterlab.\n\n## Configuration\n\nConfiguration is optional and is read from `pyproject.toml`. Only the\n`pyproject.toml` closest to the notebook is read. Defaults are based on\n“sniffing” the `pyproject.toml` to detect which project manager is in use.\n\n### `python-cmd`\n\nThe key `tool.pyproject-local-kernel.python-cmd` should be a command that runs\npython from the environment you want to use for the project.\n\nIf this is set then it overrides the default command. There is further\nexplanation in [the FAQ](FAQ.md#how-does-the-python-cmd-configuration-work).\n\n**Default:** *Depends on project manager*\u003cbr\u003e\n**Type:** `list[str] | str`\u003cbr\u003e\n**Example:**\n\n```toml\n[tool.pyproject-local-kernel]\npython-cmd = [\"uv\", \"run\", \"--with\", \"ipykernel\", \"python\"]\n```\n\n### `use-venv`\n\nPath to virtual environment that should be used, relative to the\n`pyproject.toml` file. Can also be an absolute path.\n\nIf this is set then it overrides the default command - the virtualenv is used\ndirectly without invoking any project manager. Remember to explicitly install\nor sync required dependencies.\n\n**Default:** Not set\u003cbr\u003e\n**Type:** `str`\u003cbr\u003e\n**Example:**\n\n```toml\n[tool.pyproject-local-kernel]\nuse-venv = \".venv\"\n```\n\n### `sanity-check`\n\nIf `true`, then run a check for `ipykernel` being installed in the project\nbefore starting the kernel process.\n\n**Default:** true\u003cbr\u003e\n**Type:** `bool`\u003cbr\u003e\n**Example:**\n\n```toml\n[tool.pyproject-local-kernel]\nsanity-check = true\n```\n\n\n### `PyprojectKernelProvisioner`\n\nThe kernel provisioner is configurable in the same way as other Jupyter\nobjects, with the following settings. They can be set in your\n`jupyter_lab_config.py` settings file.\nWhen possible, prefer to use settings in `pyproject.toml` instead, to keep them\nclose to the project.\n\n```python\n#------------------------------------------------------------------------------\n# PyprojectKernelProvisioner(LocalProvisioner) configuration\n#------------------------------------------------------------------------------\n## Enable sanity check for 'ipykernel' package in environment\n#  Default: True\n# c.PyprojectKernelProvisioner.sanity_check = True\n\n## Default setting for use-venv for projects using the 'use-venv' kernel\n#  Default: '.venv'\n# c.PyprojectKernelProvisioner.use_venv = '.venv'\n```\n\n\n## About Particular Project Managers\n\nThe project manager command, be it rye, uv, pdm, etc needs to be\navailable on the path where Jupyterlab runs. Either install the project\nmanager in the Jupyterlab environment, or install the project manager\nuser-wide (using something like pipx, uv tool, rye tools, brew, or\nother method to install it.)\n\n***Uv***\n\n- Uv is detected if the pyproject.toml contains `tool.uv`. It is also the\n  default fallback if no project manager is detected from a pyproject file.\n\n- The command used is `uv run --with ipykernel python` which means that it ensures\n  `ipykernel` is used even if it's not already in the project(!). However, note that\n  it uses an [ephemeral virtual environment][eph] for ipykernel in that case.\n  Add ipykernel to the project to avoid this.\n\n[eph]: https://docs.astral.sh/uv/reference/cli/\n\n***Rye***\n\n- Rye is detected if the pyproject.toml contains `tool.rye.managed = true`\n  which Rye sets by default for its new projects.\n\n***PDM***\n\n- PDM is detected if pyproject.toml contains `tool.pdm`\n\n***Hatch***\n\n- Hatch is detected if pyproject.toml contains `tool.hatch.envs`\n\n- By default it calls out to `hatch env find`, to find the default virtualenv,\n  and runs from there. `hatch run` should not be used directly because\n  it's not compatible with how kernel interrupts work (as of this writing).\n\n- It's best to create the hatch project, add ipykernel as dependency and sync\n  dependencies in a terminal before starting (it does not work so well with\n  shell commands in a notebook).\n\n***Poetry***\n\n- Poetry is detected if pyproject.toml contains `tool.poetry.name`\n\n- Some commands are interactive by default and don't work in a notebook,\n  but they have an `-n` switch to make them non-interactive.\n\n## Project Status\n\nAdditional interest and maintainer help is welcomed.\n\n## Links\n\n* \u003chttps://github.com/astral-sh/uv\u003e\n* \u003chttps://github.com/renan-r-santos/pixi-kernel\u003e\n* \u003chttps://github.com/goerz/python-localvenv-kernel\u003e\n* \u003chttps://github.com/pathbird/poetry-kernel\u003e\n\n## License\n\n`pyproject-local-kernel` is open source. See the LICENSE.md file in the source\ndistribution for more information.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbluss%2Fpyproject-local-kernel","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbluss%2Fpyproject-local-kernel","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbluss%2Fpyproject-local-kernel/lists"}