qkernel

A CLI tool for executing Quarto (.qmd) code cells through a Jupyter kernel.

Features

• Execute Quarto cells from the command line with live output
• Persistent kernel sessions - start a kernel once, run cells across multiple invocations
• Automatic virtual environment detection - uses .venv in your project automatically
• Cell selection - run specific cells by index or label
• Image saving - automatically saves generated images to cache directory
• Animated progress - shows live spinner and timing for each cell

Installation

With uv (recommended)

uv tool install qkernel

With pip

pip install qkernel

Requirements

• Python 3.10+
• ipykernel must be installed in the target Python environment

Usage

Running Cells

# Run all cells in a file
qkernel run notebook.qmd

# Run specific cells by index (0-based)
qkernel run notebook.qmd --cells 0,2,5

# Run specific cells by label
qkernel run notebook.qmd --cells setup,analysis,plot

# Mix indices and labels
qkernel run notebook.qmd --cells 0,setup,2

# Set execution timeout (in seconds)
qkernel run notebook.qmd --timeout 600

Persistent Kernel Sessions

For faster iteration, start a kernel that persists across runs:

# Start a background kernel
qkernel start

# Run cells (uses the persistent kernel)
qkernel run notebook.qmd --cells setup
qkernel run notebook.qmd --cells analysis  # Variables from setup are available

# Check kernel status
qkernel status

# Restart the kernel (clears state)
qkernel restart

# Stop the kernel when done
qkernel stop

Verbose Mode

Enable debug logging with -v:

qkernel -v run notebook.qmd

Python Environment Resolution

qkernel automatically detects which Python to use for the kernel, following this order:

1. QUARTO_PYTHON - Environment variable (path to Python executable or venv directory)
2. VIRTUAL_ENV - Activated virtual environment
3. .venv - Virtual environment in current directory or any parent directory
4. System Python - Fallback

This means if you have a .venv in your project root, qkernel will use it automatically even when running from a subdirectory.

# Explicit Python
QUARTO_PYTHON=/path/to/python qkernel run notebook.qmd

# Uses activated venv
source .venv/bin/activate
qkernel run notebook.qmd

# Auto-detects .venv in project
cd /project/src/deep/folder
qkernel run ../../../notebook.qmd  # Uses /project/.venv

Output Format

qkernel shows clean, informative output with timing:

Kernel started (/path/to/python)
● ━━ [0] setup ━━━━━━━━━━━━━━━━━━━━━━━━━━ ✓ 23ms
    Loading data...
    Done!
● ━━ [1] analysis ━━━━━━━━━━━━━━━━━━━━━━━ ✓ 1205ms
    Processing 1000 rows
    Results: [1, 2, 3, 4, 5]
● ━━ [2] plot ━━━━━━━━━━━━━━━━━━━━━━━━━━━ ✓ 89ms
    [Image: ~/.cache/qkernel/notebook/plot/output.png]
Kernel stopped

══════════════════════════════════════════════════
Executed 3 cell(s) • 1 image(s) saved
  → /Users/you/.cache/qkernel/notebook/plot/output.png

In interactive terminals, a spinner animates while cells are running.

Image Caching

Images generated by cells are saved to ~/.cache/qkernel/<filename>/<cell_label>/:

~/.cache/qkernel/
└── notebook/
    ├── plot/
    │   └── output.png
    └── visualization/
        ├── output_0.png
        └── output_1.png

The cache is cleared before each run to ensure fresh output.

Cell Labels

qkernel recognizes cell labels from Quarto's YAML-style comments:

```{python}
#| label: setup
import pandas as pd
data = pd.read_csv("data.csv")
```

```{python}
#| label: analysis
results = data.groupby("category").sum()
print(results)
```

Use these labels to run specific cells: qkernel run file.qmd --cells setup,analysis

Development

# Install with dev dependencies
uv pip install -e ".[dev]"

# Run tests
pytest tests/ -v

# Run with timeout
pytest tests/ -v --timeout=60

License

MIT