Using Pixi

Pixi manages Artisan’s environments, dependencies, and tasks. This page covers what you need for day-to-day development. For general Pixi documentation, see the official getting started guide.

Running commands in an environment¶

Artisan defines three environments. Each bundles the dependencies needed for a specific workflow.

# Run a command in the default environment
pixi run python script.py

# Run a command in a named environment
pixi run -e dev pytest
pixi run -e docs docs-build

All environments share a single solve group, so package versions are consistent across them.

Opening an interactive shell¶

pixi run is best for one-off commands. For interactive work — debugging, exploring data, running multiple commands — open a shell instead:

pixi shell                          # Default environment
pixi shell -e dev                   # Dev environment (pytest, ruff, ipython)
pixi shell -e docs                  # Docs environment (jupyter-book, node)

Inside a Pixi shell, commands run directly without the pixi run prefix:

$ pixi shell -e dev
(artisan-dev) $ pytest tests/artisan/storage/
(artisan-dev) $ ruff check src/
(artisan-dev) $ exit                # Return to your regular shell

You can have multiple shells open in different terminals — each can use a different environment.

Working across multiple projects with workspaces¶

If you work across multiple Pixi projects, workspaces let you run tasks in one project from another without changing directories.

# Register a workspace member (name comes from pyproject.toml)
cd /path/to/repo
pixi workspace register

# Or set the name explicitly
pixi workspace register --name custom-name

# Run tasks or open a shell from anywhere
pixi run -w workspace-name task-name
pixi shell -w workspace-name

Adding new dependencies¶

Artisan uses both conda-forge (for Python, system libraries) and PyPI (for Python-only packages). Use --pypi for pure-Python packages and bare pixi add for everything else.

# Add a conda-forge package to the default feature
pixi add numpy

# Add a PyPI package
pixi add --pypi requests

# Add to a specific feature (dev or docs)
pixi add --feature dev --pypi icecream
pixi add --feature docs nodejs

# Pin a version
pixi add "numpy>=1.24,<2"
pixi add --pypi "requests>=2.31"

After adding a dependency, pixi.lock updates automatically. Commit both pyproject.toml and pixi.lock together.

Using a local copy of a dependency¶

If you need to edit a dependency’s source code — to debug an issue, develop a feature, or test a fix — you can point Pixi at a local clone instead of the published package.

Open pyproject.toml and add a path dependency override in the [tool.pixi.pypi-dependencies] section:

[tool.pixi.pypi-dependencies]
some-package = { path = "/path/to/your/local-clone", editable = true }

With editable = true, Python picks up your local changes immediately — no reinstall needed. This is the same concept as pip install -e . but managed through Pixi.

When you’re done, remove the override and run pixi install to restore the locked version.

Task reference¶

Tasks are shortcuts defined in pyproject.toml. They save you from remembering flags and command sequences.

Default environment¶

Dev environment¶

Docs environment¶

Cross-references¶

• Installation — First-time setup and IDE configuration

• Tooling Decisions — Why Artisan uses Pixi

• Pixi documentation — Full reference for all Pixi commands