Metadata-Version: 2.4
Name: pixi-kernel
Version: 0.7.1
Summary: Jupyter kernels using Pixi for reproducible notebooks
Project-URL: Documentation, https://github.com/renan-r-santos/pixi-kernel
Project-URL: Homepage, https://github.com/renan-r-santos/pixi-kernel
Project-URL: Repository, https://github.com/renan-r-santos/pixi-kernel
Author-email: Renan Rodrigues dos Santos <renan.engmec@gmail.com>
License: MIT
License-File: LICENSE
Keywords: jupyter,jupyterlab,jupyterlab-extension,kernel,pixi
Classifier: Development Status :: 5 - Production/Stable
Classifier: Framework :: Jupyter
Classifier: Framework :: Jupyter :: JupyterLab
Classifier: Framework :: Jupyter :: JupyterLab :: 4
Classifier: Framework :: Jupyter :: JupyterLab :: Extensions
Classifier: Framework :: Jupyter :: JupyterLab :: Extensions :: Prebuilt
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Typing :: Typed
Requires-Python: <4.0,>=3.10
Requires-Dist: ipykernel>=6
Requires-Dist: jupyter-client>=7
Requires-Dist: jupyter-server>=2.4
Requires-Dist: msgspec>=0.18
Requires-Dist: returns>=0.23
Requires-Dist: tomli>=2; python_version < '3.11'
Description-Content-Type: text/markdown

# Pixi kernel

[![image](https://img.shields.io/pypi/v/pixi-kernel)](https://pypi.python.org/pypi/pixi-kernel)
[![image](https://img.shields.io/pypi/l/pixi-kernel)](https://pypi.python.org/pypi/pixi-kernel)
[![image](https://img.shields.io/pypi/pyversions/pixi-kernel)](https://pypi.python.org/pypi/pixi-kernel)
[![Actions status](https://github.com/renan-r-santos/pixi-kernel/actions/workflows/ci.yml/badge.svg)](https://github.com/renan-r-santos/pixi-kernel/actions)
[![codecov](https://codecov.io/gh/renan-r-santos/pixi-kernel/graph/badge.svg?token=7PCsXpsYSH)](https://codecov.io/gh/renan-r-santos/pixi-kernel)
[![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)
[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)

Per-directory Pixi environments with multi-language Jupyter kernels.

<!--- TODO: add theme selector when supported on PyPI https://github.com/pypi/warehouse/issues/11251 -->

![JupyterLab launcher screen showing Pixi kernel](https://raw.githubusercontent.com/renan-r-santos/pixi-kernel/main/assets/launch-light.png)

Pixi kernel supports Jupyterlab 4, Python 3.9+ and Pixi 0.39.0+ using `pyproject.toml` and
`pixi.toml` configurations.

**Disclaimer**: _This project is not affiliated with Pixi, and not an official Pixi plugin._

## Quick Start

This assumes you want a Python kernel. For other languages, check the [Kernel
support](#kernel-support) table and replace `ipykernel` with the desired kernel package.

1. Install Pixi and `pixi-kernel` alongside JupyterLab using your favorite package manager.
2. Restart JupyterLab.
3. Create a new directory and initialize a Pixi project with `pixi init` and `pixi add ipykernel`.
4. Select the Python Pixi kernel and you are good to go.

See the [Pixi docs](https://pixi.sh/latest/) for more information on how to use Pixi.

## Configuration

### Custom Pixi binary location

By default, `pixi-kernel` will try to find the Pixi binary in this order:

1. Use `shutil.which("pixi")` to find Pixi in your PATH
2. Check for a configuration file stored at:
   - Linux/macOS: `$HOME/.config/pixi-kernel/config.toml`
   - Windows: `$Env:USERPROFILE\.config\pixi-kernel\config.toml`
3. Check the default Pixi installation location:
   - Linux/macOS: `$HOME/.pixi/bin/pixi`
   - Windows: `$Env:USERPROFILE\.pixi\bin\pixi.exe`

If you have Pixi installed in a non-standard location, you can create a configuration file to
specify its path:

```toml
pixi-path = "/path/to/your/pixi"
```

## Kernel support

Pixi kernel supports the following kernels:

| Language | Kernel         | Package name                                       |
| -------- | -------------- | -------------------------------------------------- |
| Python   | IPython Kernel | [ipykernel](https://github.com/ipython/ipykernel)  |
| R        | IR Kernel      | [r-irkernel](https://github.com/IRkernel/IRkernel) |
| R        | Ark R Kernel   | [ark](https://github.com/posit-dev/ark)            |

## Pixi environments

Pixi kernel supports multiple Pixi environments in a single Pixi project. To select a specific
environment, use JupyterLab property inspector, save your notebook and restart your kernel.

![JupyterLab property inspector showing Pixi environment selector](https://raw.githubusercontent.com/renan-r-santos/pixi-kernel/main/assets/env-selector-light.png)

If an environment cannot be determined, Pixi kernel will fallback to the value in the
`PIXI_KERNEL_DEFAULT_ENVIRONMENT` environment variable, if specified. Otherwise, the `default` Pixi
environment will be used.

## JupyterHub deployments with limited permissions

If you're using pixi-kernel on JupyterHub and cannot access the environment where JupyterLab is
installed, you can use the following workaround:

1. Install `pixi-kernel` locally: `pip install pixi-kernel --user`
2. Install Pixi
3. Restart your JupyterLab server

See https://github.com/renan-r-santos/pixi-kernel/issues/62 and
https://github.com/renan-r-santos/pixi-kernel/issues/51 for more information.

## Limitations

Pixi kernel only works with the default environment in VSCode.

## Related

- [Pyproject Local Jupyter Kernel](https://github.com/bluss/pyproject-local-kernel)
- [Poetry-kernel](https://github.com/pathbird/poetry-kernel)
- [Python Local .venv Kernel](https://github.com/goerz/python-localvenv-kernel)
