Improve logic for locating the Pixi binary (#63)

Author: renan-r-santos

.github/workflows/ci.yml

@@ -12,7 +12,7 @@ jobs:
       fail-fast: false
       matrix:
         os: [ubuntu-latest, macos-latest, windows-latest]
-        pixi-version: ['0.39.0', '0.48.2']
+        pixi-version: ['0.39.0', '0.50.2']
     runs-on: ${{ matrix.os }}
     steps:
       - name: Checkout repo

README.md

@@ -27,10 +27,31 @@ support](#kernel-support) table and replace `ipykernel` with the desired kernel
 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. Restart the kernel and you are good to go.
+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:
@@ -60,9 +81,11 @@ If you're using pixi-kernel on JupyterHub and cannot access the environment wher
 installed, you can use the following workaround:
 
 1. Install `pixi-kernel` locally: `pip install pixi-kernel --user`
-2. Restart your JupyterLab server
+2. Install Pixi
+3. Restart your JupyterLab server
 
-See https://github.com/renan-r-santos/pixi-kernel/issues/51 for more information.
+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
 

package.json

@@ -1,6 +1,6 @@
 {
     "name": "pixi-kernel",
-    "version": "0.6.4",
+    "version": "0.6.5",
     "description": "Jupyter kernels using Pixi for reproducible notebooks.",
     "keywords": [
         "kernel",
@@ -54,27 +54,27 @@
         "watch:labextension": "jupyter labextension watch ."
     },
     "dependencies": {
-        "@jupyterlab/application": "^4.4.3",
-        "@jupyterlab/coreutils": "^6.4.3",
-        "@jupyterlab/notebook": "^4.4.3",
-        "@jupyterlab/services": "^7.4.3",
+        "@jupyterlab/application": "^4.4.5",
+        "@jupyterlab/coreutils": "^6.4.5",
+        "@jupyterlab/notebook": "^4.4.5",
+        "@jupyterlab/services": "^7.4.5",
         "@rjsf/utils": "^5.24.12",
         "react": "^18.3.1"
     },
     "devDependencies": {
         "@eslint/eslintrc": "^3.3.1",
-        "@eslint/js": "^9.29.0",
-        "@jupyterlab/builder": "^4.4.3",
+        "@eslint/js": "^9.32.0",
+        "@jupyterlab/builder": "^4.4.5",
         "@types/json-schema": "^7.0.15",
         "@types/react": "^18.3.12",
         "@types/react-addons-linked-state-mixin": "^0.14.27",
-        "@typescript-eslint/eslint-plugin": "^8.34.1",
-        "@typescript-eslint/parser": "^8.34.1",
-        "eslint": "^9.29.0",
-        "eslint-config-prettier": "^10.1.5",
-        "eslint-plugin-prettier": "^5.5.0",
+        "@typescript-eslint/eslint-plugin": "^8.38.0",
+        "@typescript-eslint/parser": "^8.38.0",
+        "eslint": "^9.32.0",
+        "eslint-config-prettier": "^10.1.8",
+        "eslint-plugin-prettier": "^5.5.3",
         "npm-run-all2": "^8.0.4",
-        "prettier": "^3.5.3",
+        "prettier": "^3.6.2",
         "rimraf": "^6.0.1",
         "source-map-loader": "^5.0.0",
         "typescript": "5.5.4"

pixi_kernel/compatibility.py

@@ -1,10 +1,19 @@
 import shutil
+import sys
+from pathlib import Path
+from typing import Any
 
 from returns.result import Failure, Result, Success
 
 from .async_subprocess import subprocess_exec
 
-MINIMUM_PIXI_VERSION = (0, 30, 0)
+if sys.version_info >= (3, 11):
+    import tomllib
+else:
+    import tomli as tomllib
+
+
+MINIMUM_PIXI_VERSION = (0, 39, 0)
 
 
 PIXI_NOT_FOUND = """Pixi was not detected in your system.
@@ -34,11 +43,53 @@
 """
 
 
+def get_config_file() -> Path:
+    return Path.home() / ".config" / "pixi-kernel" / "config.toml"
+
+
+def get_default_pixi_path() -> Path:
+    if sys.platform == "win32":
+        return Path.home() / ".pixi" / "bin" / "pixi.exe"
+    else:
+        return Path.home() / ".pixi" / "bin" / "pixi"
+
+
+def find_pixi_binary() -> Result[str, None]:
+    # 1. Check if the Pixi binary is available in the system PATH
+    pixi_path = shutil.which("pixi")
+    if pixi_path is not None:
+        return Success(pixi_path)
+
+    # 2. Check if a config file exists and read the Pixi path from it
+    config_file = get_config_file()
+    if config_file.is_file():
+        try:
+            content = Path(config_file).read_text()
+            config = tomllib.loads(content)
+            pixi_path = config.get("pixi-path")
+            if pixi_path is not None and Path(pixi_path).is_file():
+                return Success(pixi_path)
+        except (OSError, tomllib.TOMLDecodeError):
+            pass
+
+    # 3. Check if the default installation path exists
+    # https://pixi.sh/latest/installation/#installer-script-options
+    default_pixi_path = get_default_pixi_path()
+    if default_pixi_path.is_file():
+        return Success(str(default_pixi_path))
+
+    return Failure(None)
+
+
 async def has_compatible_pixi() -> Result[None, str]:
-    if shutil.which("pixi") is None:
+    result = find_pixi_binary()
+
+    if isinstance(result, Failure):
         return Failure(PIXI_NOT_FOUND)
+    else:
+        pixi_path = result.unwrap()
 
-    returncode, stdout, stderr = await subprocess_exec("pixi", "--version")
+    returncode, stdout, stderr = await subprocess_exec(pixi_path, "--version")
     if returncode != 0 or not stdout.startswith("pixi "):
         return Failure(PIXI_VERSION_ERROR)
 
@@ -50,3 +101,11 @@ async def has_compatible_pixi() -> Result[None, str]:
         return Failure(PIXI_OUTDATED.format(minimum_version=minimum_version))
 
     return Success(None)
+
+
+async def run_pixi(*args: str, **kwargs: Any) -> tuple[int, str, str]:
+    # It is safe to unwrap as `has_compatible_pixi()` would already have checked for a compatible
+    # Pixi binary.
+    pixi = find_pixi_binary().unwrap()
+
+    return await subprocess_exec(pixi, *args, **kwargs)

pixi_kernel/env.py

@@ -3,7 +3,7 @@
 
 from pydantic import ValidationError
 
-from .async_subprocess import subprocess_exec
+from .compatibility import run_pixi
 from .types import PixiInfo
 
 DEFAULT_ENVIRONMENT = "default"
@@ -15,7 +15,7 @@ async def envs_from_path(path: Path) -> list[str]:
     env = os.environ.copy()
     env.pop("PIXI_IN_SHELL", None)
 
-    returncode, stdout, stderr = await subprocess_exec("pixi", "info", "--json", cwd=path, env=env)
+    returncode, stdout, stderr = await run_pixi("info", "--json", cwd=path, env=env)
     if returncode != 0:
         return [DEFAULT_ENVIRONMENT]
 

pixi_kernel/readiness.py

@@ -5,8 +5,7 @@
 from pydantic import ValidationError
 from returns.result import Failure, Result, Success
 
-from .async_subprocess import subprocess_exec
-from .compatibility import has_compatible_pixi
+from .compatibility import has_compatible_pixi, run_pixi
 from .types import Environment, PixiInfo
 
 PIXI_KERNEL_NOT_FOUND = """To run the {kernel_name} kernel, you need to add the {required_package}
@@ -41,7 +40,7 @@ async def verify_env_readiness(
         return result
 
     # Ensure there is a Pixi project in the current working directory or any of its parents
-    returncode, stdout, stderr = await subprocess_exec("pixi", "info", "--json", cwd=cwd, env=env)
+    returncode, stdout, stderr = await run_pixi("info", "--json", cwd=cwd, env=env)
 
     logger.info(f"pixi info stderr: {stderr}")
     logger.info(f"pixi info stdout: {stdout}")
@@ -56,14 +55,7 @@ async def verify_env_readiness(
     if pixi_info.project is None:
         # Attempt to get a good error message by running `pixi project version get`. Maybe there's
         # a typo in the toml file (parsing error) or there is no project at all.
-        returncode, stdout, stderr = await subprocess_exec(
-            "pixi",
-            "project",
-            "version",
-            "get",
-            cwd=cwd,
-            env=env,
-        )
+        returncode, stdout, stderr = await run_pixi("project", "version", "get", cwd=cwd, env=env)
         return Failure(stderr)
 
     # Find the Pixi environment and check if the required kernel package is a dependency
@@ -77,9 +69,7 @@ async def verify_env_readiness(
     dependencies = pixi_environment.dependencies + pixi_environment.pypi_dependencies
     if required_package not in dependencies:
         # Check transitive dependencies
-        returncode, stdout, stderr = await subprocess_exec(
-            "pixi", "list", "--json", cwd=cwd, env=env
-        )
+        returncode, stdout, stderr = await run_pixi("list", "--json", cwd=cwd, env=env)
 
         logger.info(f"pixi list stderr: {stderr}")
         logger.info(f"pixi list stdout: {stdout}")
@@ -99,13 +89,8 @@ async def verify_env_readiness(
             return Failure(f"Failed to parse 'pixi list' output: {stdout}\n{exception}")
 
     # Make sure the environment can be solved and is up-to-date
-    returncode, stdout, stderr = await subprocess_exec(
-        "pixi",
-        "install",
-        "--environment",
-        environment_name,
-        cwd=cwd,
-        env=env,
+    returncode, stdout, stderr = await run_pixi(
+        "install", "--environment", environment_name, cwd=cwd, env=env
     )
     if returncode != 0:
         return Failure(f"Failed to run 'pixi install --environment {environment_name}': {stderr}")

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "pixi-kernel"
-version = "0.6.4"
+version = "0.6.5"
 description = "Jupyter kernels using Pixi for reproducible notebooks"
 license = { text = "MIT" }
 authors = [
@@ -35,9 +35,10 @@ requires-python = ">=3.9,<4.0"
 dependencies = [
     "ipykernel>=6",
     "jupyter-client>=7",
-    "jupyter_server>=2.4.0,<3",
-    "pydantic>=2,<3",
-    "returns>=0.23,<0.24",      # 0.24 drops Python 3.9 support
+    "jupyter_server>=2.4.0",
+    "pydantic>=2",
+    "returns>=0.23",
+    "tomli>=2; python_version<'3.11'",
 ]
 
 [project.urls]
@@ -47,14 +48,15 @@ Repository = "https://github.com/renan-r-santos/pixi-kernel"
 
 [tool.uv]
 dev-dependencies = [
-    "jupyter-kernel-test>=0.7,<0.8",
-    "jupyterlab>=4,<5",
-    "mypy>=1,<2",
-    "pytest>=8,<9",
-    "pytest-asyncio>=1,<2",
-    "pytest-cov>=6,<7",
-    "ruff>=0.12,<0.13",
-    "tox-uv>=1,<2",
+    "jupyter-kernel-test>=0.7",
+    "jupyterlab>=4",
+    "msgspec[toml]>=0.19.0",
+    "mypy>=1",
+    "pytest>=8",
+    "pytest-asyncio>=1",
+    "pytest-cov>=6",
+    "ruff>=0.12",
+    "tox-uv>=1",
 ]
 
 [project.entry-points."jupyter_client.kernel_provisioners"]