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!
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.
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
Explore the manifest
The pixi.toml file is your workspace’s manifest: [ workspace ] authors = [ "Your Name <your.email@example.com>" ] 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.
Add Python and 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"
Add more packages
Add pytest for testing: You can also specify exact versions: 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.
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__)"
Use the shell
Start an interactive shell in the environment: 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.
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()
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"
Run the task
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.
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"
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 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.
Add a PyPI package
Use the --pypi flag to install from PyPI: This adds to pixi.toml: [ pypi-dependencies ] httpx = ">=0.28.1,<0.29"
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
analyze.py
plot.py
[ 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:
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 < repositor y > cd < repositor y > pixi install # Creates environment from pixi.lock pixi run start
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.