{"id":15551357,"url":"https://github.com/robertrosca/vip-ipykernel","last_synced_at":"2025-04-23T20:47:26.268Z","repository":{"id":43886569,"uuid":"313240982","full_name":"RobertRosca/vip-ipykernel","owner":"RobertRosca","description":"Venv in Parent IPykernel - an ipython kernel for Jupyter that runs out the closest venv","archived":false,"fork":false,"pushed_at":"2023-03-28T09:06:19.000Z","size":619,"stargazers_count":5,"open_issues_count":3,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-17T23:06:27.705Z","etag":null,"topics":["ipython","jupyter","jupyter-kernels","jupyter-notebook","jupyterlab"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/RobertRosca.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null}},"created_at":"2020-11-16T08:49:04.000Z","updated_at":"2023-04-13T17:18:49.000Z","dependencies_parsed_at":"2023-02-09T10:01:44.037Z","dependency_job_id":null,"html_url":"https://github.com/RobertRosca/vip-ipykernel","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RobertRosca%2Fvip-ipykernel","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RobertRosca%2Fvip-ipykernel/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RobertRosca%2Fvip-ipykernel/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RobertRosca%2Fvip-ipykernel/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/RobertRosca","download_url":"https://codeload.github.com/RobertRosca/vip-ipykernel/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250513584,"owners_count":21443201,"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":["ipython","jupyter","jupyter-kernels","jupyter-notebook","jupyterlab"],"created_at":"2024-10-02T14:04:29.967Z","updated_at":"2025-04-23T20:47:26.253Z","avatar_url":"https://github.com/RobertRosca.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/RobertRosca/vip-ipykernel/main/.github/vip-ipykernel-logo.png\" alt=\"ViP-IPykernel\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/RobertRosca/vip-ipykernel/projects/1\" target=\"_blank\"\u003e\n      \u003cimg src=\"https://img.shields.io/badge/repo%20status-active-brightgreen?style=flat-square\" alt=\"Lifecycle\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://github.com/RobertRosca/vip-ipykernel/releases\" target=\"_blank\"\u003e\n      \u003cimg src=\"https://img.shields.io/github/release-date/RobertRosca/vip-ipykernel?style=flat-square\" alt=\"GitHub Release Date\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://github.com/robertrosca/vip-ipykernel/releases/latest\" target=\"_blank\"\u003e\n      \u003cimg src=\"https://img.shields.io/github/release/robertrosca/vip-ipykernel.svg?style=flat-square\" alt=\"Release\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://pypi.org/project/vip-ipykernel\" target=\"_blank\"\u003e\n      \u003cimg src=\"https://img.shields.io/pypi/v/vip-ipykernel?style=flat-square\" alt=\"PyPI\"\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp\u003e \u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/RobertRosca/vip-ipykernel/actions?query=workflow%3ATests\" target=\"_blank\"\u003e\n      \u003cimg src=\"https://img.shields.io/github/workflow/status/RobertRosca/vip-ipykernel/Tests/main?label=Tests\u0026style=flat-square\" alt=\"GitHub Workflow Status (main)\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://codecov.io/gh/RobertRosca/vip-ipykernel\" target=\"_blank\"\u003e\n      \u003cimg src=\"https://img.shields.io/codecov/c/github/RobertRosca/vip-ipykernel?style=flat-square\" alt=\"Codecov\"\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp\u003e \u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n    \u003ca href=\"https://dev.to/robertrosca/vip-ipykernel-start-jupyter-kernels-in-the-closest-virtual-environment-3af0\"\u003e \u003cimg alt=\"DEV\" src=\"https://img.shields.io/badge/DEV-article-7986f8?style=flat-square\"\u003e \u003c/a\u003e\n    \u003ca href=\"https://towardsdatascience.com/vip-ipykernel-start-jupyter-kernels-in-the-closest-virtual-environment-4d8877712559\"\u003e \u003cimg alt=\"Medium\" src=\"https://img.shields.io/badge/medium-article-000000?style=flat-square\"\u003e \u003c/a\u003e\n \u003c/p\u003e\n\nVenv in Parent IPykernel - an IPython kernel for Jupyter that runs out the closest venv\n\n- [Overview](#overview)\n- [How it Works](#how-it-works)\n- [Caveats and Gotchas](#caveats-and-gotchas)\n  - [VSCode Jupyter Notebook Integration](#vscode-jupyter-notebook-integration)\n  - [Venv Names](#venv-names)\n- [Acknowledgements](#acknowledgements)\n- [Todo](#todo)\n\n## Overview\n\nCheck the [medium](https://towardsdatascience.com/vip-ipykernel-start-jupyter-kernels-in-the-closest-virtual-environment-4d8877712559)\nor [dev.to](https://dev.to/robertrosca/vip-ipykernel-start-jupyter-kernels-in-the-closest-virtual-environment-3af0)\narticles to read more about the background behind this project.\n\nDo you use `venv`'s for all of your environments? Do you run Jupyter out of a\nsystem/user installed location or via JupyterHub? Are you bored of making a\nkernel for every single venv? Then this is the package for you!\n\nvip-ipykernel overwrites the default `python3` kernel and replaces it with one\nwhich will traverse directories upwards until it finds a `.venv` directory, if\nit finds one then it will start the kernel with python out of that directory, if\nit does not find a venv then it will carry on with the default python3.\n\nNOTE: Your venv **must have ipykernel installed in it**, as this 'kernel' just\nsearches for and launches ipykernel out of the local venv. If ipykernel is not\navailable inside the venv then it will fail to start.\n\nThis only needs to be installed once, you can do this with `pip install\nvip-ipykernel --user` to install it into your local user environment.\n\nOnce the package is installed, run `python3 -m vip_ipykernel.kernelspec --user`\nto install the kernel, now when you run a notebook with the default `python3`\nkernel it will instead use the venv in a parent directory.\n\nIf you want to revert the changes, run `python3 -m ipykernel install --user`,\nthis will re-install the default `python3` kernel.\n\nAlternatively, if you don't want to overwrite the default kernel, then you can\npass a name (`python3 -m vip_ipykernel.kernelspec --user --name venv-kernel`) to\nso that the kernel appears separately in the list of kernels and the default\nbehaviour is not modified.\n\n## How it Works\n\nThe standard python3 kernel is:\n\n```\n{\n \"argv\": [\n  \"/usr/bin/python3\",\n  \"-m\",\n  \"ipykernel_launcher\",\n  \"-f\",\n  \"{connection_file}\"\n ],\n \"display_name\": \"Python 3\",\n \"language\": \"python\"\n}\n```\n\nThis just says \"Run using `python3` to run `ipykernel_launcher` with an argument\n`-f {connection_file}`\". When you install the vip ipykernel this is replace by:\n\n```\n{\n \"argv\": [\n  \"/usr/bin/python3\",\n  \"-m\",\n  \"vip_ipykernel_launcher\",\n  \"-m\",\n  \"ipykernel_launcher\",\n  \"-f\",\n  \"{connection_file}\"\n ],\n \"display_name\": \"Python 3\",\n \"language\": \"python\"\n}\n```\n\nWhich will instead run the `vip_ipykernel.vip_ipykernel_launcher` module,\npassing it the arguments `-m ipykernel_launcher -f {connection_file}`. The\nmodule runs a function `venv_search` which looks in the current directory, and\nupwards to any parent directories, until it finds a `.venv` or `venv` directory\ncontaining `bin/python3`.\n\nIf it finds a venv with python3 in it, it passes the arguments `-m\nipykernel_launcher -f {connection_file}` to that python executable, which starts\nand connects the kernel from that venv to your current session, in the same way\nthat a kernel installed for that specific venv would.\n\nIf it does not find a venv, then it will default to the system python executable\nand behave like the standard `python3` kernel.\n\n## Caveats and Gotchas\n\n### VSCode Jupyter Notebook Integration\n\nVSCode manages kernels for its notebooks with its own system, so it will not use\nthe vip-ipykernel.\n\n### Venv Names\n\nCurrently only venv's named `.venv` or `venv` are searched for, if your venv has\na different name it won't be found, and if you have multiple venv's available\nthen the first one (sorted alphanumerically, so `.venv` takes priority over\n`venv`) will be used.\n\n## Acknowledgements\n\nThe kernel implementation and tests are largely copy-and-paste'd directly from\nthe [ipykernel project](https://github.com/ipython/ipykernel) with some minor\nmodifications made to search for a venv and launch python out of it if possible.\n\nThank you to Thomas Kluyver (@takluyver) for the review of the initial code in\nthe first PR: https://github.com/RobertRosca/vip-ipykernel/pull/1\n\n## Todo\n\n- [ ] Expand tests to different versions of ipykernel/jupyter_core\n- [ ] Look at ways to show kernel errors\n- [ ] Support for other environments:\n  - [ ] Poetry-created venvs (`poetry env info --path`)\n  - [ ] Pipenv-created venvs\n  - [ ] Pyenv-created venvs\n  - [ ] Conda-created environments\n  - [ ] User-configured venvs\n  - [ ] Reading from vscode configuration?\n  - [ ] etc...\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frobertrosca%2Fvip-ipykernel","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frobertrosca%2Fvip-ipykernel","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frobertrosca%2Fvip-ipykernel/lists"}