Tutorial: Doing Python development with Pixi#

In this tutorial, we will show you how to create a simple Python package with pixi.

Why is this useful?#

Pixi builds upon the conda ecosystem, which allows you to create a Python environment with all the dependencies you need. Unlike PyPI, the conda ecosystem is cross-language and also offers packages written in Rust, R, C, C++ and many other languages.

By building a Python package with pixi, you can:

manage Python packages and packages written in other languages in the same workspace
build both conda and Python packages with the same tool

In this tutorial we will focus on point 1.

Let's get started#

First, we create a simple Python package with a pyproject.toml and a single Python file. The package will be called rich_example, so we will create the following structure

├── src # (1)!
│   └── rich_example
│       └── __init__.py
└── pyproject.toml

This project uses a src-layout, but pixi supports both flat- and src-layouts.

The Python package has a single function main. Calling that, will print a table containing the name, age and city of three people.

src/rich_example/__init__.py

from rich.console import Console
from rich.table import Table


def main() -> None:
    console = Console()

    table = Table()

    table.add_column("Name")
    table.add_column("Age")
    table.add_column("City")

    table.add_row("John Doe", "30", "New York")
    table.add_row("Jane Smith", "25", "Los Angeles")
    table.add_row("Tim de Jager", "35", "Utrecht")

    console.print(table)

The metadata of the Python package is defined in pyproject.toml.

pyproject.toml

[project]
dependencies = ["rich"]                               # (1)!
name = "rich_example"
requires-python = ">= 3.11"
scripts = { rich-example-main = "rich_example:main" } # (2)!
version = "0.1.0"

[build-system] # (3)!
build-backend = "hatchling.build"
requires = ["hatchling"]

We use the rich package to print the table in the terminal.
By specifying a script, the executable rich-example-main will be available in the environment. When being called it will in return call the main function of the rich_example module.
One can choose multiple backends to build a Python package, we choose hatchling which works well without additional configuration.

Adding a `pixi.toml`#

What we have in the moment, constitutes a full Python package. It could be uploaded to PyPI as-is.

However, we still need a tool to manage our environments and if we want other pixi projects to depend on our tool, we need to include more information. We will do exactly that by creating a pixi.toml.

Note

The pixi manifest can be in its own pixi.toml file or integrated in pyproject.toml In this tutorial, we will use pixi.toml. If you want everything integrated in pyproject.toml just copy the content of pixi.toml in this tutorial to your pyproject.toml and append tool.pixi to each table.

The file structure will then look like this:

├── src
│   └── rich_example
│       └── __init__.py
├── pixi.toml
└── pyproject.toml

This is the content of the pixi.toml:

pixi.toml

[workspace] # (1)!
channels = ["https://prefix.dev/conda-forge"]
platforms = ["win-64", "linux-64", "osx-arm64", "osx-64"]
preview = ["pixi-build"]

[dependencies] # (2)!
rich_example = { path = "." }

[tasks] # (3)!
start = "rich-example-main"

[package] # (4)!
name = "rich_example"
version = "0.1.0"

[build-system] # (5)!
build-backend = { name = "pixi-build-python", version = "*" }
channels = [
  "https://prefix.dev/pixi-build-backends",
  "https://prefix.dev/conda-forge",
]

[host-dependencies] # (6)!
hatchling = "==1.26.3"

[run-dependencies] # (7)!
rich = ">=13.9.4,<14"

In workspace information is set that is shared across all packages in the workspace.
In dependencies you specify all of your pixi packages. Here, this includes only our own package that is defined further below under package
We define a task that runs the rich-example-main executable we defined earlier. You can learn more about tasks in this section
In package we define the actual pixi package. This information will be used when other pixi packages or workspaces depend on our package or when we upload it to a conda channel.
The same way, Python uses build backends to build a Python package, pixi uses build backends to build pixi packages. pixi-build-python creates a pixi package out of a Python package.
In host-dependencies, we add Python dependencies that are necessary to build the Python package. By adding them here as well, the dependencies will come from the conda channel rather than PyPI.
In run-dependencies, we add the Python dependencies needed during runtime.

When we now run pixi run start, we get the following output:

┏━━━━━━━━━━━━━━┳━━━━━┳━━━━━━━━━━━━━┓
┃ Name         ┃ Age ┃ City        ┃
┡━━━━━━━━━━━━━━╇━━━━━╇━━━━━━━━━━━━━┩
│ John Doe     │ 30  │ New York    │
│ Jane Smith   │ 25  │ Los Angeles │
│ Tim de Jager │ 35  │ Utrecht     │
└──────────────┴─────┴─────────────┘

Conclusion#

In this tutorial, we created a pixi package based on Python. It can be used as-is, to upload to a conda channel or to PyPI. In another tutorial we will learn how to add multiple pixi packages to the same workspace and let one pixi package use another.

Thanks for reading! Happy Coding 🚀

Any questions? Feel free to reach out or share this tutorial on X, join our Discord, send us an e-mail or follow our GitHub.

Tutorial: Doing Python development with Pixi#

Why is this useful?#

Let's get started#

Adding a pixi.toml#

Conclusion#

Adding a `pixi.toml`#