Quick Start

Create your first Pixi workspace and run your first task

Quick Start Guide

This guide will walk you through creating your first Pixi workspace, adding dependencies, and running tasks. You’ll have a working project in under 5 minutes!

Make sure you have installed Pixi before continuing.

Create Your First Workspace

A Pixi workspace is a directory with a pixi.toml manifest file that defines your project’s dependencies, tasks, and environments.

1. Initialize a new workspace

   Create a new workspace called my_workspace:

   pixi init my_workspace
   cd my_workspace
   

   This creates a new directory with the following structure:

   my_workspace/
   ├── .gitattributes
   ├── .gitignore
   └── pixi.toml
   
2. Explore the manifest

   The pixi.toml file is your workspace’s manifest:

   [workspace]
   authors = ["Your Name <[e-mail]>"]
   channels = ["conda-forge"]
   name = "my_workspace"
   platforms = ["linux-64"]  # Your current platform
   version = "0.1.0"
   
   [tasks]
   
   [dependencies]
   

   Install the Even Better TOML extension in VS Code for autocompletion based on Pixi’s JSON schema!

Add Dependencies

Let’s add some Python packages to the workspace.

1. Add Python and NumPy

   pixi add python numpy
   

   This command:

   • Adds dependencies to pixi.toml
   • Solves all dependencies
   • Creates/updates pixi.lock with exact versions
   • Installs packages into the environment at .pixi/envs/default

   Your pixi.toml now includes:

   [dependencies]
   python = ">=3.13.1,<3.14"
   numpy = ">=2.2.6,<3"
   
2. Add more packages

   Add pytest for testing:

   pixi add pytest
   

   You can also specify exact versions:

   pixi add pandas==2.2.0
   

Understanding the Lock File

Pixi automatically created a pixi.lock file containing exact versions of all dependencies:

version: 6
environments:
  default:
    channels:
    - url: https://prefix.dev/conda-forge/
    packages:
      linux-64:
      - conda: https://prefix.dev/conda-forge/linux-64/python-3.13.1-...
      - conda: https://prefix.dev/conda-forge/linux-64/numpy-2.2.6-...

This ensures reproducible environments across machines and over time.

Run Commands in Your Environment

Now let’s use the packages we installed.

1. Run a command directly

   Use pixi run to execute commands in the environment:

   pixi run python --version
   

   Python 3.13.1 | packaged by conda-forge
   

   Try using NumPy:

   pixi run python -c "import numpy; print(numpy.__version__)"
   

   2.2.6
   
2. Use the shell

   Start an interactive shell in the environment:

   pixi shell
   

   Your prompt will change to indicate you’re in the Pixi environment. Now you can run commands directly:

   python --version
   python -c "import numpy; print('NumPy works!')"
   exit
   

   Type exit to leave the shell.

Create and Run Tasks

Tasks are reusable commands defined in your manifest. They’re perfect for common operations like testing, building, or running your application.

1. Create a Python script

   Create a file called hello.py:

   # hello.py
   import numpy as np
   
   def main():
       arr = np.array([1, 2, 3, 4, 5])
       print(f"Array: {arr}")
       print(f"Mean: {arr.mean()}")
       print(f"Sum: {arr.sum()}")
   
   if __name__ == "__main__":
       main()
   
2. Add a task to run the script

   pixi task add start "python hello.py"
   

   This adds the following to your pixi.toml:

   [tasks]
   start = "python hello.py"
   
3. Run the task

   pixi run start
   

   Output:

   ✨ Pixi task (start): python hello.py
   Array: [1 2 3 4 5]
   Mean: 3.0
   Sum: 15
   

Add More Complex Tasks

Tasks can have dependencies and arguments for more complex workflows.

1. Add a test task

   Create a simple test file test_hello.py:

   # test_hello.py
   import numpy as np
   
   def test_numpy_array():
       arr = np.array([1, 2, 3])
       assert arr.sum() == 6
       assert arr.mean() == 2.0
   

   Add a test task:

   pixi task add test "pytest -v"
   
2. Create a task with dependencies

   Add this to your pixi.toml manually:

   [tasks]
   start = "python hello.py"
   test = "pytest -v"
   
   [tasks.hello]
   cmd = "echo Hello from Pixi!"
   
   [tasks.run-all]
   depends-on = ["hello", "start", "test"]
   

   Now running pixi run run-all will execute all three tasks in order:

   pixi run run-all
   

   ✨ Pixi task (hello): echo Hello from Pixi!
   Hello from Pixi!
   ✨ Pixi task (start): python hello.py
   Array: [1 2 3 4 5]
   Mean: 3.0
   Sum: 15
   ✨ Pixi task (test): pytest -v
   ===== test session starts =====
   collected 1 item
   
   test_hello.py::test_numpy_array PASSED
   

Working with PyPI Packages

Pixi seamlessly integrates conda packages with PyPI packages.

1. Add a PyPI package

   Use the --pypi flag to install from PyPI:

   pixi add --pypi httpx
   

   This adds to pixi.toml:

   [pypi-dependencies]
   httpx = ">=0.28.1,<0.29"
   
2. Use the PyPI package

   pixi run python -c "import httpx; print(httpx.__version__)"
   

   Pixi ensures there are no conflicts between conda and PyPI packages.

Complete Example Workflow

Here’s a complete example putting it all together:

pixi.toml

[workspace]
name = "data-analysis"
channels = ["conda-forge"]
platforms = ["linux-64", "osx-64", "osx-arm64", "win-64"]
version = "0.1.0"

[dependencies]
python = ">=3.11"
numpy = ">=1.24"
pandas = ">=2.0"
matplotlib = ">=3.7"
pytest = ">=7.4"

[pypi-dependencies]
seaborn = ">=0.12"

[tasks]
analyze = "python analyze.py"
test = "pytest tests/"
visualize = "python plot.py"

[tasks.full-pipeline]
depends-on = ["analyze", "test", "visualize"]

Run the complete pipeline:

pixi run full-pipeline

Next Steps

Congratulations! You’ve learned the basics of Pixi. Here’s what to explore next:

Multiple Environments

Learn how to manage development, testing, and production environments

Advanced Tasks

Discover powerful task features like arguments and templates

Global Tools

Install CLI tools system-wide with Pixi

Multi-Platform Support

Configure projects for Linux, macOS, and Windows

Common Workflows

Starting an Existing Project

If you clone a repository with a pixi.toml:

git clone <repository>
cd <repository>
pixi install  # Creates environment from pixi.lock
pixi run start

Adding Platform-Specific Dependencies

pixi add --platform linux-64 pkg-config
pixi add --platform win-64 win-specific-package

Updating Dependencies

pixi update           # Update all dependencies
pixi update numpy     # Update specific package
pixi upgrade numpy    # Upgrade to latest, even if pinned

Cleaning Up

pixi clean            # Remove the environment
pixi clean cache      # Clean download cache

Tips for Success

Commit pixi.lock: Always commit your lock file to version control to ensure reproducible environments.

Use pixi.toml schema: Configure your IDE to use the JSON schema for autocompletion and validation.

Global tools: Use pixi global install for CLI tools you want available everywhere, not just in projects.

Don’t mix conda and pip: Always use pixi add --pypi for PyPI packages instead of running pip install directly. This ensures Pixi can manage dependencies properly.