{"id":13625846,"url":"https://github.com/pathbird/poetry-kernel","last_synced_at":"2025-10-21T19:46:18.139Z","repository":{"id":42622084,"uuid":"400047282","full_name":"pathbird/poetry-kernel","owner":"pathbird","description":"Python Jupyter kernel using Poetry for reproducible notebooks","archived":false,"fork":false,"pushed_at":"2023-08-04T22:49:11.000Z","size":587,"stargazers_count":247,"open_issues_count":6,"forks_count":7,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-03-13T14:38:30.226Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pathbird.png","metadata":{"files":{"readme":"README.md","changelog":null,"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}},"created_at":"2021-08-26T05:08:28.000Z","updated_at":"2025-01-10T12:16:05.000Z","dependencies_parsed_at":"2024-01-07T06:00:11.366Z","dependency_job_id":"ddc3d16c-c49a-48be-8e1b-55611f50b03e","html_url":"https://github.com/pathbird/poetry-kernel","commit_stats":{"total_commits":14,"total_committers":4,"mean_commits":3.5,"dds":0.2857142857142857,"last_synced_commit":"9d2988904d5ec5a9d127a5d8d9b109c3861b20a7"},"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pathbird%2Fpoetry-kernel","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pathbird%2Fpoetry-kernel/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pathbird%2Fpoetry-kernel/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pathbird%2Fpoetry-kernel/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pathbird","download_url":"https://codeload.github.com/pathbird/poetry-kernel/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249228273,"owners_count":21233852,"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":[],"created_at":"2024-08-01T21:02:03.692Z","updated_at":"2025-10-21T19:46:13.091Z","avatar_url":"https://github.com/pathbird.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"# Poetry Kernel\n\nUse per-directory Poetry environments to run Jupyter kernels. No need to install\na Jupyter kernel per Python virtual environment!\n\nThe idea behind this project is to allow you to capture the exact state of your\nenvironment. This means you can email your work to your peers, and they'll have\n_exactly_ the same set of packages that you do! Reproducibility!\n\n## Why not virtual environments (venvs)?\n\nVirtual environments were (and are) an important advancement to Python's package\nmanagement story, but they have a few shortcomings:\n\n- They are not great for reproducibility. Usually, you'll create a new virtual\n  environment using a `requirements.txt` which includes all the direct\n  dependencies (numpy, pandas, etc.), but not transient dependencies (pandas\n  depends on pytz for timezone support, for example). And usually, even the\n  direct dependencies are specified only as minimum (or semver) ranges (e.g.,\n  `numpy\u003e=1.21`) which can make it hard or impossible to accurately recreate the\n  `venv` later.\n- With Jupyter, they usually require that the kernels be installed globally.\n  This means you'll need need to have a separate kernelspec for every venv you\n  want to use with Jupyter.\n\nPoetry uses venvs transparently under the hood by constructing them from the\n`pyproject.toml` and `poetry.lock` files. The `poetry.lock` file records the\nexact state of dependencies (and transient dependencies) and can be used to more\naccurately reproduce the environment.\n\nAdditionally, Poetry Kernel means you only have to install one kernelspec. It\nthen uses the `pyproject.toml` file from the directory of the notebook (or any\nparent directory) to choose which environment to run the notebook in.\n\n## Shameless plug\n\nThe reason we created this package was to make sure that the code environments\ncreated for running student code on Pathbird exactly match your development\nenvironment. Interested in developing interactive, engaging, inquiry-based\nlessons for your students?\n[Check out Pathbird for more information!](https://pathbird.com/)\n\n# Usage\n\n1. [Install Poetry](https://python-poetry.org/docs/#installation) if not yet\n   installed.\n1. Install this package:\n   ```sh\n   # NOTE: Do **NOT** install this package in your Poetry project, it should be\n   # installed at the system or user level.\n   pip3 install --user poetry-kernel\n   ```\n1. Initialize a Poetry project (only required if you do not have an existing\n   Poetry project ready to use):\n   ```sh\n   poetry init -n\n   ```\n1. **IMPORTANT:** Add `ipykernel` to your project's dependencies:\n   ```sh\n   # In the directory of your Poetry project\n   poetry add ipykernel\n   ```\n1. Start a \"Poetry\" Jupyter kernel and see it in action!\n   ![Jupyter launcher screenshot](.static/jupyter-screenshot.png)\n\n# Troubleshooting\n\n## Kernel isn't starting (\"No Kernel\" message)\n\n**Pro-tip:** Check the output of the terminal window where you launched Jupyter.\nIt will usually explain why the kernel is failing to start.\n\n1. Make sure that you are launching a notebook in a directory/folder that\n   contains a Poetry project (`pyproject.toml` and `poetry.lock` files). You can\n   turn a directory into a Poetry project by running:\n\n```sh\npoetry init -n\n```\n\n2. Make sure that you've installed `ipykernel` into your project:\n\n```sh\npoetry add ipykernel\n```\n\n3. Make sure the Poetry project is installed! This is especially important for\n   projects that you have downloaded from others (**warning:** installing a\n   Poetry project could run arbitrary code on your computer, make sure you trust\n   your download first!):\n\n   ```sh\n   poetry install\n   ```\n\n4. Still can't figure it out? Open an issue!\n\n## A package I added won't import properly\n\nIf you added the package **after** starting the kernel, you might need to\nrestart the kernel for it to see the new package.\n\n# FAQ\n\n[See FAQ.md.](FAQ.md)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpathbird%2Fpoetry-kernel","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpathbird%2Fpoetry-kernel","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpathbird%2Fpoetry-kernel/lists"}