# Pixi > Pixi Documentation β€” Next-gen package manager for reproducible development setups Pixi is a fast, modern, and reproducible package management tool for developers of all backgrounds. Pixi is a cross-platform package manager and project management tool that creates reproducible environments using conda and PyPI packages. To use Pixi, start by running `pixi init my_project` to create a new project with a `pixi.toml` manifest file, then add dependencies using `pixi add package1 package2 ...` for conda packages or `pixi add --pypi python_package ...` for PyPI packages. Pixi automatically generates a lockfile (`pixi.lock`) to ensure reproducible environments across different systems. You can define and run tasks using `pixi task add task_name "command arg1 arg2"` and `pixi run task_name`, and work within the project's virtual environment using `pixi run` for single commands or `pixi shell` for an interactive session. The tool combines dependency management, task running, and environment isolation in a single workflow, making it easy to share consistent development environments with others. See other documentation sections for further details on how to use the software. # Getting Started documentation # Pixi Pixi is a **fast, modern, and reproducible** package management tool for developers of all backgrounds. ## Highlights - [πŸ”„ **Reproducibility**](workspace/lockfile/)\ Isolated, easily recreated environments with lockfiles built-in - [πŸ› οΈ **Tasks**](workspace/advanced_tasks/)\ Manage complex pipelines effortlessly. - [🌐 **Multi Platform**](workspace/multi_platform_configuration/)\ Works on Linux, macOS, Windows, and more. - [🧩 **Multiple Environments**](workspace/multi_environment/)\ Compose multiple environments in one manifest. - [🐍 **Python**](python/tutorial/)\ Support for `pyproject.toml` and PyPI through uv. - [πŸ’Ύ **Disk Efficient**](workspace/environment/#de-duplication) Environments share files through hard links or reflinks, so packages are stored only once. - [🌍 **Global Tools**](global_tools/introduction/) Install global tools, safely isolated. Replacing `apt`, `homebrew`, `winget`. ______________________________________________________________________ ## Quick Demo Project setup is a breeze with Pixi. ```shell pixi init hello-world cd hello-world pixi add python pixi run python -c 'print("Hello World!")' ``` Install your favorite tools with a single command. ```shell pixi global install gh nvim ipython btop ripgrep ``` ______________________________________________________________________ ## How Tools Compare to Pixi | Builtin Core Features | Pixi | Conda | Pip | Poetry | uv | | --------------------------- | ---- | ----- | --- | ------ | --- | | Installs Python | βœ… | βœ… | ❌ | ❌ | βœ… | | Supports Multiple Languages | βœ… | βœ… | ❌ | ❌ | ❌ | | Lockfiles | βœ… | ❌ | ❌ | βœ… | βœ… | | Task runner | βœ… | ❌ | ❌ | ❌ | ❌ | | Workspace Management | βœ… | ❌ | ❌ | βœ… | βœ… | ______________________________________________________________________ ## Available Software Pixi defaults to the **biggest Conda package repository**, [conda-forge](https://conda-forge.org/), which contains over **30,000 packages**. - **Python**: [`python`](https://prefix.dev/channels/conda-forge/packages/python), [`scikit-learn`](https://prefix.dev/channels/conda-forge/packages/scikit-learn), [`pytorch`](https://prefix.dev/channels/conda-forge/packages/pytorch) - **C/C++**: [`clang`](https://prefix.dev/channels/conda-forge/packages/clang), [`boost`](https://prefix.dev/channels/conda-forge/packages/libboost-devel), [`opencv`](https://prefix.dev/channels/conda-forge/packages/opencv), [`ninja`](https://prefix.dev/channels/conda-forge/packages/ninja) - **Java**: [`openjdk`](https://prefix.dev/channels/conda-forge/packages/openjdk), [`gradle`](https://prefix.dev/channels/conda-forge/packages/gradle), [`maven`](https://prefix.dev/channels/conda-forge/packages/maven) - **Rust**: [`rust`](https://prefix.dev/channels/conda-forge/packages/rust), [`cargo-edit`](https://prefix.dev/channels/conda-forge/packages/cargo-edit), [`cargo-insta`](https://prefix.dev/channels/conda-forge/packages/cargo-insta) - **Node.js**: [`nodejs`](https://prefix.dev/channels/conda-forge/packages/nodejs), [`bun`](https://prefix.dev/channels/conda-forge/packages/bun), [`pnpm`](https://prefix.dev/channels/conda-forge/packages/pnpm), [`eslint`](https://prefix.dev/channels/conda-forge/packages/eslint) - **Cli Tools**: [`git`](https://prefix.dev/channels/conda-forge/packages/git), [`gh`](https://prefix.dev/channels/conda-forge/packages/gh), [`ripgrep`](https://prefix.dev/channels/conda-forge/packages/ripgrep), [`make`](https://prefix.dev/channels/conda-forge/packages/make) And browse the thousands more on [prefix.dev](https://prefix.dev/), or host [your own channels](https://prefix.dev/channels/) ______________________________________________________________________ ## Installation To install `pixi`, run: ```bash curl -fsSL https://pixi.sh/install.sh | sh ``` [Download installer](https://github.com/prefix-dev/pixi/releases/latest/download/pixi-x86_64-pc-windows-msvc.msi) Or run: ```powershell powershell -ExecutionPolicy ByPass -c "irm -useb https://pixi.sh/install.ps1 | iex" ``` Now restart your terminal or shell! The installation needs to become effective by restarting your terminal or sourcing your shell. Don't trust our link? Check the script! You can check the installation `sh` script: [download](https://pixi.sh/install.sh) and the `ps1`: [download](https://pixi.sh/install.ps1). The scripts are open source and available on [GitHub](https://github.com/prefix-dev/pixi/tree/main/install). [**See all installation options β†’**](installation/) ______________________________________________________________________ ## Getting Started 1. **Initialize a workspace:** ```text pixi init hello-world cd hello-world ``` 1. **Add dependencies into the default environment:** ```text pixi add cowpy python ``` 1. **Create your script:** hello.py ```py from cowpy.cow import Cowacter message = Cowacter().milk("Hello Pixi fans!") print(message) ``` 1. **Add a task:** ```text pixi task add start python hello.py ``` 1. **Run the task:** ```text pixi run start ``` ```text ✨ Pixi task (start): python hello.py __________________ < Hello Pixi fans! > ------------------ \ ^__^ \ (oo)\_______ (__)\ )\/\ ||----w | || || ``` 1. **Enter the shell into the environment:** ```text pixi shell python hello.py exit ``` More details on how to use Pixi with Python can be found in the [Python tutorial](python/tutorial/). 1. **Initialize a workspace:** `pixi init pixi-rust cd pixi-rust` 1. **Add dependencies:** ```text pixi add rust ``` 1. **Create your workspace:** ```text pixi run cargo init ``` 1. **Add a task:** ```text pixi task add start cargo run ``` 1. **Run the task:** ```text pixi run start ``` ```text ✨ Pixi task (start): cargo run Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.02s Running `target/debug/pixi-rust` Hello, world! ``` This is more of an example to show off how easy it is to use Pixi with Rust. Not a recommended way to build Rust projects. More details on how to use Pixi with Rust can be found in the [Rust tutorial](tutorials/rust/). 1. **Initialize a workspace:** ```text pixi init pixi-node cd pixi-node ``` 1. **Add dependencies:** ```text pixi add nodejs ``` 1. **Create your script:** hello.js ```js console.log("Hello Pixi fans!"); ``` 1. **Add a task:** ```text pixi task add start "node hello.js" ``` 1. **Run the task:** ```text pixi run start ``` ```text ✨ Pixi task (start): node hello.js Hello Pixi fans! ``` 1. **Initialize a workspace:** ```text pixi init pixi-ros2 -c https://prefix.dev/conda-forge -c "https://prefix.dev/robostack-humble" cd pixi-ros2 ``` 1. **Add dependencies:** ```text pixi add ros-humble-desktop ``` This might take a minute Depending on your internet connection, this will take a while to install, as it will download the entire ROS2 desktop package. 1. **Start Rviz** ```text pixi run rviz2 ``` More details on how to use Pixi with ROS2 can be found in the [ROS2 tutorial](tutorials/ros2/). 1. Install all your favorite tools with a single command: ```shell pixi global install terraform ansible k9s make ``` 1. Use them everywhere: ```shell ansible --version terraform --version k9s version make --version ``` ______________________________________________________________________ ## What Developers Say "Pixi is my tool of choice for Python environment management. It has significantly reduced boilerplate by offering seamless support for both PyPI and conda-forge indexes - a critical requirement in my workflow." **Guillaume Lemaitre** – [scikit-learn](https://scikit-learn.org) "I can’t stress enough how much I love using Pixi global as a package manager for my daily CLI tools. With the global manifest, even sharing my setup across machines is trivial!" **Matthew Feickert** – [University of Wisconsin–Madison](https://www.wisc.edu/) "We are changing how we manage ROS dependencies on Windows. We will be using Pixi to install and manage dependencies from conda. I'm pretty excited about how much easier it will be for users going forward." **Michael Carroll** – [Project Lead ROS](https://www.ros.org/) ______________________________________________________________________ ## Useful Links - [GitHub](https://github.com/prefix-dev/pixi): Pixi source code, feel free to leave a star! - [Discord](https://discord.gg/kKV8ZxyzY4): Join our community and ask questions. - [Prefix.dev](https://prefix.dev/): The company behind Pixi, building the future of package management. - [conda-forge](https://conda-forge.org/): Community-driven collection of recipes for the conda package manager. - [Rattler](https://github.com/conda/rattler): Everything conda but built in Rust. Backend of Pixi. - [rattler-build](https://rattler.build): A blazing fast build system for conda packages. To install `pixi` you can run the following command in your terminal: ```bash curl -fsSL https://pixi.sh/install.sh | sh ``` If your system doesn't have `curl`, you can use `wget`: ```bash wget -qO- https://pixi.sh/install.sh | sh ``` What does this do? The above invocation will automatically download the latest version of `pixi`, extract it, and move the `pixi` binary to `~/.pixi/bin`. The script will also extend the `PATH` environment variable in the startup script of your shell to include `~/.pixi/bin`. This allows you to invoke `pixi` from anywhere. [Download installer](https://github.com/prefix-dev/pixi/releases/latest/download/pixi-x86_64-pc-windows-msvc.msi) Or run: ```powershell powershell -ExecutionPolicy Bypass -c "irm -useb https://pixi.sh/install.ps1 | iex" ``` What does this do? The above invocation will automatically download the latest version of `pixi`, extract it, and move the `pixi` binary to `%UserProfile%\.pixi\bin`. The command will also add `%UserProfile%\.pixi\bin` to your `PATH` environment variable, allowing you to invoke `pixi` from anywhere. Now restart your terminal or shell to make the installation take effect. Don't trust our link? Check the script! You can check the installation `sh` script: [download](https://pixi.sh/install.sh) and the `ps1`: [download](https://pixi.sh/install.ps1). The scripts are open source and available on [GitHub](https://github.com/prefix-dev/pixi/tree/main/install). Don't forget to add autocompletion! After installing Pixi, you can enable autocompletion for your shell. See the [Autocompletion](#autocompletion) section below for instructions. ## Update Updating is as simple as installing, rerunning the installation script gets you the latest version. ```shell pixi self-update ``` Or get a specific Pixi version using: ```shell pixi self-update --version x.y.z ``` Note If you've used a package manager like `brew`, `mamba`, `conda`, `paru` etc. to install `pixi` you must use the built-in update mechanism. e.g. `brew upgrade pixi`. ## Alternative Installation Methods Although we recommend installing Pixi through the above method we also provide additional installation methods. ### Homebrew Pixi is available via homebrew. To install Pixi via homebrew simply run: ```shell brew install pixi ``` ### Windows Installer We provide an `msi` installer on [our GitHub releases page](https://github.com/prefix-dev/pixi/releases/latest). The installer will download Pixi and add it to the `PATH`. ### Winget ```text winget install prefix-dev.pixi ``` ### Scoop ```text scoop install main/pixi ``` ### Download From GitHub Releases Pixi is a single executable and can be run without any external dependencies. That means you can manually download the suitable archive for your architecture and operating system from our [GitHub releases](https://github.com/prefix-dev/pixi/releases), unpack it and then use it as is. If you want `pixi` itself or the executables installed via `pixi global` to be available in your `PATH`, you have to add them manually. The executables are located in [PIXI_HOME](../reference/environment_variables/)/bin. ### Install From Source pixi is 100% written in Rust, and therefore it can be installed, built and tested with cargo. To start using Pixi from a source build run: ```shell cargo install --locked --git https://github.com/prefix-dev/pixi.git pixi ``` We don't publish to `crates.io` anymore, so you need to install it from the repository. The reason for this is that we depend on some unpublished crates which disallows us to publish to `crates.io`. or when you want to make changes use: ```shell cargo build cargo test ``` If you have any issues building because of the dependency on `rattler` check out its [compile steps](https://github.com/conda/rattler/tree/main#give-it-a-try). ## Installer Script Options The installation script has several options that can be manipulated through environment variables. | Variable | Description | Default Value | | --------------------- | ------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | | `PIXI_VERSION` | The version of Pixi getting installed, can be used to up- or down-grade. | `latest` | | `PIXI_HOME` | The location of the pixi home folder containing global environments and configs. | `$HOME/.pixi` | | `PIXI_BIN_DIR` | The location where the standalone pixi binary should be installed. | `$PIXI_HOME/bin` | | `PIXI_ARCH` | The architecture the Pixi version was built for. | `uname -m` | | `PIXI_NO_PATH_UPDATE` | If set the `$PATH` will not be updated to add `pixi` to it. | | | `PIXI_DOWNLOAD_URL` | Overrides the download URL for the Pixi binary (useful for mirrors or custom builds). | GitHub releases, e.g. [linux-64](https://github.com/prefix-dev/pixi/releases/latest/download/pixi-x86_64-unknown-linux-musl.tar.gz) | | `NETRC` | Path to a custom `.netrc` file for authentication with private repositories. | | | `TMP_DIR` | The temporary directory the script uses to download to and unpack the binary from. | `/tmp` | For example, on Apple Silicon, you can force the installation of the x86 version: ```shell curl -fsSL https://pixi.sh/install.sh | PIXI_ARCH=x86_64 bash ``` Or set the version ```shell curl -fsSL https://pixi.sh/install.sh | PIXI_VERSION=v0.18.0 bash ``` To make a "drop-in" installation of pixi directly in the user `$PATH`: ```shell curl -fsSL https://pixi.sh/install.sh | PIXI_BIN_DIR=/usr/local/bin PIXI_NO_PATH_UPDATE=1 bash ``` #### Using `.netrc` for Authentication If you need to download Pixi from a private repository that requires authentication, you can use a `.netrc` file instead of hardcoding credentials in the `PIXI_DOWNLOAD_URL`. The install script automatically uses `.netrc` for authentication with `curl` and `wget`. By default, it looks for `~/.netrc`. You can specify a custom location using the `NETRC` environment variable: ```shell # Use the default ~/.netrc file curl -fsSL https://pixi.sh/install.sh | PIXI_DOWNLOAD_URL=https://private.example.com/pixi-latest.tar.gz bash ``` ```shell # Use a custom .netrc file curl -fsSL https://pixi.sh/install.sh | NETRC=/path/to/custom/.netrc PIXI_DOWNLOAD_URL=https://private.example.com/pixi-latest.tar.gz bash ``` Your `.netrc` file should contain credentials in the following format: ```text machine private.example.com login your-username password your-token-or-password ``` Security Recommendation Using `.netrc` is more secure than embedding credentials directly in the `PIXI_DOWNLOAD_URL` (e.g., `https://user:pass@example.com/file`), as it keeps credentials separate from the URL and prevents them from appearing in logs or process listings. Security Note The install script automatically masks any credentials embedded in the download URL when displaying messages, replacing them with `***:***@` to prevent credentials from appearing in logs or console output. The installation script has several options that can be manipulated through environment variables. | Environment variable | Description | Default Value | | --------------------- | ------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | | `PIXI_VERSION` | The version of Pixi getting installed, can be used to up- or down-grade. | `latest` | | `PIXI_HOME` | The location of the installation. | `$Env:USERPROFILE\.pixi` | | `PIXI_NO_PATH_UPDATE` | If set, the `$PATH` will not be updated to add `pixi` to it. | `false` | | `PIXI_DOWNLOAD_URL` | Overrides the download URL for the Pixi binary (useful for mirrors or custom builds). | GitHub releases, e.g. [win-64](https://github.com/prefix-dev/pixi/releases/latest/download/pixi-x86_64-pc-windows-msvc.zip) | For example, set the version: ```powershell $env:PIXI_VERSION='v0.18.0'; powershell -ExecutionPolicy Bypass -Command "iwr -useb https://pixi.sh/install.ps1 | iex" ``` #### Authentication for Private Repositories If you need to download Pixi from a private repository that requires authentication, you can embed credentials in the `PIXI_DOWNLOAD_URL`. The install script will automatically mask credentials in its output for security. ```powershell $env:PIXI_DOWNLOAD_URL='https://username:token@private.example.com/pixi-latest.zip'; powershell -ExecutionPolicy Bypass -Command "iwr -useb https://pixi.sh/install.ps1 | iex" ``` Security Note The PowerShell install script automatically masks any credentials embedded in the download URL when displaying messages, replacing them with `***:***@` to prevent credentials from appearing in logs or console output. ## Autocompletion To get autocompletion follow the instructions for your shell. Afterwards, restart the shell or source the shell config file. Add the following to the end of `~/.bashrc`: ~/.bashrc ```bash eval "$(pixi completion --shell bash)" ``` Add the following to the end of `~/.zshrc`: ~/.zshrc ```zsh autoload -Uz compinit && compinit # redundant with Oh My Zsh eval "$(pixi completion --shell zsh)" ``` Add the following to the end of `Microsoft.PowerShell_profile.ps1`. You can check the location of this file by querying the `$PROFILE` variable in PowerShell. Typically the path is `~\Documents\PowerShell\Microsoft.PowerShell_profile.ps1` or `~/.config/powershell/Microsoft.PowerShell_profile.ps1` on -Nix. ```pwsh (& pixi completion --shell powershell) | Out-String | Invoke-Expression ``` Add the following to the end of `~/.config/fish/config.fish`: ~/.config/fish/config.fish ```fish pixi completion --shell fish | source ``` Add the following to your Nushell config file (find it by running `$nu.config-path` in Nushell): ```text mkdir $"($nu.data-dir)/vendor/autoload" pixi completion --shell nushell | save --force $"($nu.data-dir)/vendor/autoload/pixi-completions.nu" ``` Add the following to the end of `~/.elvish/rc.elv`: ~/.elvish/rc.elv ```text eval (pixi completion --shell elvish | slurp) ``` ## Uninstall Before un-installation you might want to delete any files pixi managed. 1. Remove any cached data: ```shell pixi clean cache ``` 1. Remove the environments from your pixi workspaces: ```shell cd path/to/workspace && pixi clean ``` 1. Remove the `pixi` and its global environments ```shell rm -r ~/.pixi ``` 1. Remove the pixi binary from your `PATH`: - For Linux and macOS, remove `~/.pixi/bin` from your `PATH` in your shell configuration file (e.g., `~/.bashrc`, `~/.zshrc`). - For Windows, remove `%UserProfile%\.pixi\bin` from your `PATH` environment variable. # Basic usage of Pixi Pixi can do a lot of things, but it is designed to be simple to use. Let's go through the basic usage of Pixi. ## Managing workspaces - [`pixi init`](../reference/cli/pixi/init/) - create a new Pixi manifest in the current directory - [`pixi add`](../reference/cli/pixi/add/) - add a dependency to your manifest - [`pixi remove`](../reference/cli/pixi/remove/) - remove a dependency from your manifest - [`pixi update`](../reference/cli/pixi/update/) - update dependencies in your manifest - [`pixi upgrade`](../reference/cli/pixi/upgrade/) - upgrade the dependencies in your manifest to the latest versions, even if you pinned them to a specific version - [`pixi lock`](../reference/cli/pixi/lock/) - create or update the lockfile for your manifest - [`pixi info`](../reference/cli/pixi/info/) - show information about your workspace - [`pixi run`](../reference/cli/pixi/run/) - run a task defined in your manifest or any command in the current environment - [`pixi shell`](../reference/cli/pixi/shell/) - start a shell in the current environment - [`pixi list`](../reference/cli/pixi/list/) - list all dependencies in the current environment - [`pixi tree`](../reference/cli/pixi/tree/) - show a tree of dependencies in the current environment - [`pixi clean`](../reference/cli/pixi/clean/) - remove the environment from your machine ## Managing global installations Pixi can manage global installations of tools in global environments. It installs the environments in a central location, so you can use them from anywhere. - [`pixi global install`](../reference/cli/pixi/global/install/) - install a package into it's own environment in the global space. - [`pixi global uninstall`](../reference/cli/pixi/global/uninstall/) - uninstall an environment from the global space. - [`pixi global add`](../reference/cli/pixi/global/add/) - add a package to an existing global environment. - [`pixi global sync`](../reference/cli/pixi/global/sync/) - sync the globally installed environments with the global manifest, describing all the environments you want to install. - [`pixi global edit`](../reference/cli/pixi/global/edit/) - edit the global manifest. - [`pixi global update`](../reference/cli/pixi/global/update/) - update the global environments - [`pixi global list`](../reference/cli/pixi/global/list/) - list all the global environments More information: [Global Tools](../global_tools/introduction/) ## Running one-off commands Pixi can run one-off commands in a specific environment. - [`pixi exec`](../reference/cli/pixi/exec/) - run a command in a temporary environment. - [`pixi exec --spec`](../reference/cli/pixi/exec/#arg---spec) - run a command in a temporary environment, with a specific specification. For example: ```bash > pixi exec python -VV Python 3.13.5 | packaged by conda-forge | (main, Jun 16 2025, 08:24:05) [Clang 18.1.8 ] > pixi exec --spec "python=3.12" python -VV Python 3.12.11 | packaged by conda-forge | (main, Jun 4 2025, 14:38:53) [Clang 18.1.8 ] ``` ## Multiple Environments Pixi workspaces allow you to manage multiple environments. An environment is build out of one or multiple features. - [`pixi add --feature`](../reference/cli/pixi/add/#arg---feature) - add a package to a feature - [`pixi task add --feature`](../reference/cli/pixi/task/add/#arg---feature) - add a task to a specific feature - [`pixi workspace environment add`](../reference/cli/pixi/workspace/environment/add/) - add an environment to the workspace - [`pixi run --environment`](../reference/cli/pixi/run/#arg---environment) - run a command in a specific environment - [`pixi shell --environment`](../reference/cli/pixi/shell/#arg---environment) - activate a specific environment - [`pixi list --environment`](../reference/cli/pixi/list/#arg---environment) - list the dependencies in a specific environment More information: [Multiple Environments](../workspace/multi_environment/) ## Tasks Pixi can run cross-platform tasks using it's built-in task runner. This can be a predefined task or any normal executable. - [`pixi run`](../reference/cli/pixi/run/) - Run a task or command - [`pixi task add`](../reference/cli/pixi/task/add/) - Add a new task to the manifest Tasks can have other tasks as dependencies. Here is an example of a more complex task use case pixi.toml ```toml [tasks] build = "make build" # using the toml table view [tasks.test] cmd = "pytest" depends-on = ["build"] ``` More information: [Tasks](../workspace/advanced_tasks/) ## Multi platform support Pixi supports multiple platforms out of the box. You can specify which platforms your workspace supports and Pixi will ensure that the dependencies are compatible with those platforms. - [`pixi add --platform`](../reference/cli/pixi/add/#arg---platform) - add a package only to a specific platform - [`pixi workspace platform add`](../reference/cli/pixi/workspace/platform/add/) - add a platform that you want to support to the workspace More information: [Multi platform support](../workspace/multi_platform_configuration/) ## Utilities Pixi comes with a set of utilities to help you debug or manage your setup. - [`pixi info`](../reference/cli/pixi/info/) - Show information about the current workspace, and the global setup. - [`pixi config`](../reference/cli/pixi/config/) - Show or edit the Pixi configuration. - [`pixi tree`](../reference/cli/pixi/tree/) - Show a tree of dependencies in the current environment. - [`pixi list`](../reference/cli/pixi/list/) - List all dependencies in the current environment. - [`pixi clean`](../reference/cli/pixi/clean/) - Remove the workspace environments from your machine. - `pixi help` - Show help for Pixi commands. - `pixi help ` - Show help for a specific Pixi command. - [`pixi auth`](../reference/cli/pixi/auth/) - Manage authentication for conda channels. - [`pixi search`](../reference/cli/pixi/search/) - Search for packages in the configured channels. - [`pixi completion`](../reference/cli/pixi/completion/) - Generate shell completion scripts for Pixi commands. ## Going further There is still much more that Pixi has to offer. Check out the topics on the sidebar on the left to learn more. And don't forget to [join our Discord](https://discord.gg/kKV8ZxyzY4) to join our community of Pixi enthusiasts! # Making a Pixi workspace Pixi's biggest strength is its ability to create reproducible, powerful, and flexible workspaces. A workspace lives in a directory on your system, and is a collection of environments that can be used to develop one or many projects in that directory. Let's go over the common steps to create a simple Pixi workspace. ## Creating a Pixi workspace To create a new Pixi workspace, you can use the `pixi init` command: ```shell pixi init my_workspace ``` This command creates a new directory called `my_workspace` with the following structure: ```shell my_workspace β”œβ”€β”€ .gitattributes β”œβ”€β”€ .gitignore └── pixi.toml ``` The `pixi.toml` file is the manifest of your Pixi workspace. It contains all the information about your workspace, such as its channels, platforms, dependencies, tasks, and more. The file created by `pixi init` is a minimal manifest that looks like this: pixi.toml ```toml [workspace] authors = ["Jane Doe "] channels = ["conda-forge"] name = "my_workspace" platforms = ["osx-arm64"] version = "0.1.0" [tasks] [dependencies] ``` Do you want autocompletion of the manifest file? As `pixi.toml` has a JSON schema, it is possible to use IDEs like VSCode to edit the field with autocompletion. Install the [Even Better TOML VSCode extension](https://marketplace.visualstudio.com/items?itemName=tamasfe.even-better-toml) to get the best experience. Or use the integrated schema support in PyCharm. ## Managing dependencies After creating the workspace, you can start adding dependencies. Pixi uses the `pixi add` command to add dependencies to a workspace. This command will, by default, add the [**conda**](https://prefix.dev/blog/what-is-a-conda-package) dependency to the `pixi.toml`, solve the dependencies, write the [lock file](../workspace/lockfile/), and install the package into an environment. For example, let's add `numpy` and `pytest` to the workspace. ```shell pixi add numpy pytest ``` This results in these lines being added: pixi.toml ```toml [dependencies] numpy = ">=2.2.6,<3" pytest = ">=8.3.5,<9" ``` You can also specify the version of the dependency you want to add. ```shell pixi add numpy==2.2.6 pytest==8.3.5 ``` ### PyPI dependencies Pixi normally uses `conda` packages for dependencies, but you can also add dependencies from [PyPI](https://pypi.org). Pixi will make sure it doesn't try to install the same package from both sources, and avoid conflicts between them. If you want to add them to your workspace you can do that with the `--pypi` flag: ```shell pixi add --pypi httpx ``` This will add the `httpx` package from PyPI to the workspace: pixi.toml ```toml [pypi-dependencies] httpx = ">=0.28.1,<0.29" ``` To learn more about the differences between `conda` and PyPI, see [our Conda & PyPI concept documentation](../concepts/conda_pypi/). ## Lock file Pixi will always create a lock file when the dependencies are solved. This file will contain all the exact versions of the workspace's dependencies (and their dependencies). This results in a reproducible environment, which you can share with others, and use for testing and deployment. The lockfile is called `pixi.lock` and it is created in the root of the workspace. To learn more about lock files, see [our detailed lock file documentation](../workspace/lockfile/). pixi.lock ```yaml version: 6 environments: default: channels: - url: https://prefix.dev/conda-forge/ indexes: - https://pypi.org/simple packages: osx-arm64: - conda: https://prefix.dev/conda-forge/osx-arm64/bzip2-1.0.8-h99b78c6_7.conda - pypi: ... packages: - conda: https://prefix.dev/conda-forge/osx-arm64/bzip2-1.0.8-h99b78c6_7.conda sha256: adfa71f158cbd872a36394c56c3568e6034aa55c623634b37a4836bd036e6b91 md5: fc6948412dbbbe9a4c9ddbbcfe0a79ab depends: - __osx >=11.0 license: bzip2-1.0.6 license_family: BSD size: 122909 timestamp: 1720974522888 - pypi: ... ``` ## Managing tasks Pixi has a built-in cross-platform task runner which allows you to define tasks in the manifest. Think of tasks as commands (or chains of commands) which you may want to repeat many times over the course of developing a project (for example, running the tests). This is a great way to share tasks with others and to ensure that the same tasks are run in the same environment on different machines. The tasks are defined in the `pixi.toml` file under the `[tasks]` section. You can add one to your workspace by running the `pixi task add` command. ```shell pixi task add hello "echo Hello, World!" ``` This will add the following lines to the `pixi.toml` file: pixi.toml ```toml [tasks] hello = "echo Hello, World!" ``` You can then run the task using the `pixi run` command: ```shell pixi run hello ``` This will execute the command `echo Hello, World!` in the workspace's default environment. Do you want to use more powerful features? Tasks can be much more powerful, for example: ```toml [tasks.name-of-powerful-task] cmd = "echo This task can do much more! Like have {{ arguments }} and {{ "minijinja" | capitalize }} templates." # List of tasks that must be run before this one. depends-on = ["other-task"] # Working directory relative to the root of the workspace cwd = "current/working/directory" # List of arguments for the task args = [{ arg = "arguments", default = "default arguments" }] # Run the command if the input files have changed input = ["src"] # Run the command if the output files are missing output = ["output.txt"] # Set environment variables for the task env = { MY_ENV_VAR = "value" } ``` More information about tasks can be found in the [Tasks](../workspace/advanced_tasks/) section of the documentation. ## Environments Pixi always creates an environment for your workspace (the "default" environment), which contains your `dependencies` and in which your tasks are run. You can also include [multiple environments](../workspace/multi_environment/) in one workspace. These environments are [located](../reference/pixi_configuration/#detached-environments "Find out how to move this location if required") in the `.pixi/envs` directory in the root of your workspace. Using these environments is as simple as running the `pixi run` or `pixi shell` command. `pixi run` will execute the remaining input as a command (or a task if the input matches the name of a defined task) in the environment, while `pixi shell` will spawn a new shell session in the environment. Both commands "activate" the environment β€” learn more at [our environment activation documentation](../workspace/environment/#activation). ```shell pixi run python -VV # or: pixi shell python -VV exit ``` # Tutorials documentation We support the use of the `pyproject.toml` as our manifest file in pixi. This allows the user to keep one file with all configuration. The `pyproject.toml` file is a standard for Python projects. We don't advise to use the `pyproject.toml` file for anything else than python projects, the `pixi.toml` is better suited for other types of projects. ## Initial setup of the `pyproject.toml` file When you already have a `pyproject.toml` file in your project, you can run `pixi init` in that folder. Pixi will automatically - Add a `[tool.pixi.workspace]` section to the file, with the platform and channel information required by pixi; - Add the current project as an editable pypi dependency; - Add some defaults to the `.gitignore` and `.gitattributes` files. If you do not have an existing `pyproject.toml` file , you can run `pixi init --format pyproject` in your project folder. In that case, Pixi will create a `pyproject.toml` manifest from scratch with some sane defaults. ## Python dependency The `pyproject.toml` file supports the `requires_python` field. Pixi understands that field and automatically adds the version to the dependencies. This is an example of a `pyproject.toml` file with the `requires_python` field, which will be used as the python dependency: pyproject.toml ```toml [project] name = "my_project" requires-python = ">=3.9" [tool.pixi.workspace] channels = ["conda-forge"] platforms = ["linux-64", "osx-arm64", "osx-64", "win-64"] ``` Which is equivalent to: equivalent pixi.toml ```toml [workspace] name = "my_project" channels = ["conda-forge"] platforms = ["linux-64", "osx-arm64", "osx-64", "win-64"] [dependencies] python = ">=3.9" ``` ## Dependency section The `pyproject.toml` file supports the `dependencies` field. Pixi understands that field and automatically adds the dependencies to the workspace as `[pypi-dependencies]`. This is an example of a `pyproject.toml` file with the `dependencies` field: pyproject.toml ```toml [project] name = "my_project" requires-python = ">=3.9" dependencies = [ "numpy", "pandas", "matplotlib", ] [tool.pixi.workspace] channels = ["conda-forge"] platforms = ["linux-64", "osx-arm64", "osx-64", "win-64"] ``` Which is equivalent to: equivalent pixi.toml ```toml [workspace] name = "my_project" channels = ["conda-forge"] platforms = ["linux-64", "osx-arm64", "osx-64", "win-64"] [pypi-dependencies] numpy = "*" pandas = "*" matplotlib = "*" [dependencies] python = ">=3.9" ``` You can overwrite these with conda dependencies by adding them to the `dependencies` field: pyproject.toml ```toml [project] name = "my_project" requires-python = ">=3.9" dependencies = [ "numpy", "pandas", "matplotlib", ] [tool.pixi.workspace] channels = ["conda-forge"] platforms = ["linux-64", "osx-arm64", "osx-64", "win-64"] [tool.pixi.dependencies] numpy = "*" pandas = "*" matplotlib = "*" ``` This would result in the conda dependencies being installed and the pypi dependencies being ignored. As Pixi takes the conda dependencies over the pypi dependencies. ## Optional dependencies If your python project includes groups of optional dependencies, Pixi will automatically interpret them as [Pixi features](../../reference/pixi_manifest/#the-feature-table) of the same name with the associated `pypi-dependencies`. You can add them to Pixi environments manually, or use `pixi init` to setup the workspace, which will create one environment per feature. Self-references to other groups of optional dependencies are also handled. For instance, imagine you have a project folder with a `pyproject.toml` file similar to: pyproject.toml ```toml [project] name = "my_project" dependencies = ["package1"] [project.optional-dependencies] test = ["pytest"] all = ["package2","my_project[test]"] ``` Running `pixi init` in that project folder will transform the `pyproject.toml` file into: pyproject.toml ```toml [project] name = "my_project" dependencies = ["package1"] [project.optional-dependencies] test = ["pytest"] all = ["package2","my_project[test]"] [tool.pixi.workspace] channels = ["conda-forge"] platforms = ["linux-64"] # if executed on linux [tool.pixi.environments] default = {features = [], solve-group = "default"} test = {features = ["test"], solve-group = "default"} all = {features = ["all"], solve-group = "default"} ``` In this example, three environments will be created by Pixi: - **default** with 'package1' as pypi dependency - **test** with 'package1' and 'pytest' as pypi dependencies - **all** with 'package1', 'package2' and 'pytest' as pypi dependencies All environments will be solved together, as indicated by the common `solve-group`, and added to the lock file. You can edit the `[tool.pixi.environments]` section manually to adapt it to your use case (e.g. if you do not need a particular environment). ## Dependency groups If your python project includes dependency groups, Pixi will automatically interpret them as [Pixi features](../../reference/pixi_manifest/#the-feature-table) of the same name with the associated `pypi-dependencies`. You can add them to Pixi environments manually, or use `pixi init` to setup the workspace, which will create one environment per dependency group. For instance, imagine you have a project folder with a `pyproject.toml` file similar to: ```toml [project] name = "my_project" dependencies = ["package1"] [dependency-groups] test = ["pytest"] docs = ["sphinx"] dev = [{include-group = "test"}, {include-group = "docs"}] ``` Running `pixi init` in that project folder will transform the `pyproject.toml` file into: ```toml [project] name = "my_project" dependencies = ["package1"] [dependency-groups] test = ["pytest"] docs = ["sphinx"] dev = [{include-group = "test"}, {include-group = "docs"}] [tool.pixi.workspace] channels = ["conda-forge"] platforms = ["linux-64"] # if executed on linux [tool.pixi.environments] default = {features = [], solve-group = "default"} test = {features = ["test"], solve-group = "default"} docs = {features = ["docs"], solve-group = "default"} dev = {features = ["dev"], solve-group = "default"} ``` In this example, four environments will be created by pixi: - **default** with 'package1' as pypi dependency - **test** with 'package1' and 'pytest' as pypi dependencies - **docs** with 'package1', 'sphinx' as pypi dependencies - **dev** with 'package1', 'sphinx' and 'pytest' as pypi dependencies All environments will be solved together, as indicated by the common `solve-group`, and added to the lock file. You can edit the `[tool.pixi.environments]` section manually to adapt it to your use case (e.g. if you do not need a particular environment). ## Example As the `pyproject.toml` file supports the full Pixi spec with `[tool.pixi]` prepended an example would look like this: pyproject.toml ```toml [project] name = "my_project" requires-python = ">=3.9" dependencies = [ "numpy", "pandas", "matplotlib", "ruff", ] [tool.pixi.workspace] channels = ["conda-forge"] platforms = ["linux-64", "osx-arm64", "osx-64", "win-64"] [tool.pixi.dependencies] compilers = "*" cmake = "*" [tool.pixi.tasks] start = "python my_project/main.py" lint = "ruff lint" [tool.pixi.system-requirements] cuda = "11.0" [tool.pixi.feature.test.dependencies] pytest = "*" [tool.pixi.feature.test.tasks] test = "pytest" [tool.pixi.environments] test = ["test"] ``` ## Build-system section The `pyproject.toml` file normally contains a `[build-system]` section. Pixi will use this section to build and install the project if it is added as a pypi path dependency. If the `pyproject.toml` file does not contain any `[build-system]` section, Pixi will fall back to [uv](https://github.com/astral-sh/uv)'s default, which is equivalent to the below: pyproject.toml ```toml [build-system] requires = ["setuptools >= 40.8.0"] build-backend = "setuptools.build_meta:__legacy__" ``` Including a `[build-system]` section is **highly recommended**. If you are not sure of the [build-backend](https://packaging.python.org/en/latest/tutorials/packaging-projects/#choosing-build-backend) you want to use, including the `[build-system]` section below in your `pyproject.toml` is a good starting point. `pixi init --format pyproject` defaults to `hatchling`. The advantages of `hatchling` over `setuptools` are outlined on its [website](https://hatch.pypa.io/latest/why/#build-backend). pyproject.toml ```toml [build-system] build-backend = "hatchling.build" requires = ["hatchling"] ``` ## Development dependencies with `[tool.uv.sources]` Because pixi is using `uv` for building its `pypi-dependencies`, one can use the `tool.uv.sources` section to specify sources for any pypi-dependencies referenced from the main pixi manifest. ### Why is this useful? When you are setting up a monorepo of some sort and you want to be able for source dependencies to reference each other, you need to use the `[tool.uv.sources]` section to specify the sources for those dependencies. This is because `uv` handles both the resolution of PyPI dependencies and the building of any source dependencies. ### Example Given a source tree: ```text . β”œβ”€β”€ main_project β”‚ └── pyproject.toml (references a) β”œβ”€β”€ a β”‚ └── pyproject.toml (has a dependency on b) └── b └── pyproject.toml ``` Concretely what this looks like in the `pyproject.toml` for `main_project`: ```toml [tool.pixi.pypi-dependencies] a = { path = "../a" } ``` Then the `pyproject.toml` for `a` should contain a `[tool.uv.sources]` section. ```toml [project] name = "a" # other fields dependencies = ["flask", "b"] [tool.uv.sources] # Override the default source for flask with main git branch flask = { git = "github.com/pallets/flask", branch = "main" } # Reference to b b = { path = "../b" } ``` More information about what is allowed in this sections is available in the [uv docs](https://docs.astral.sh/uv/concepts/projects/dependencies/#dependency-sources) Note The main `pixi.toml` or `pyproject.toml` is parsed directly by pixi and not processed by `uv`. This means that you **cannot** use the `[tool.uv.sources]` section in the main `pixi.toml` or `pyproject.toml`. This is a limitation we are aware of, feel free to open an issue if you would like support for [this](https://github.com/prefix-dev/pixi/issues/new/choose). ## Overview This guide explains how to integrate PyTorch with `pixi`, it supports multiple ways of installing PyTorch. - Install PyTorch using `conda-forge` Conda channel (Recommended) - Install PyTorch using `pypi`, using our `uv`'s integration. (Most versions available) - Install PyTorch using `pytorch` Conda channel (Legacy) With these options you can choose the best way to install PyTorch based on your requirements. ## System requirements In the context of PyTorch, [**system requirements**](../../workspace/system_requirements/) help Pixi understand whether it can install and use CUDA-related packages. These requirements ensure compatibility during dependency resolution. The key mechanism here is the use of virtual packages like \_\_cuda. Virtual packages signal the available system capabilities (e.g., CUDA version). By specifying `system-requirements.cuda = "12"`, you are telling Pixi that CUDA version 12 is available and can be used during resolution. For example: - If a package depends on `__cuda >= 12`, Pixi will resolve the correct version. - If a package depends on `__cuda` without version constraints, any available CUDA version can be used. Without setting the appropriate `system-requirements.cuda`, Pixi will default to installing the **CPU-only** versions of PyTorch and its dependencies. A more in-depth explanation of system requirements can be found [here](../../workspace/system_requirements/). ## Installing from Conda-forge You can install PyTorch using the `conda-forge` channel. These are the conda-forge community maintained builds of PyTorch. You can make direct use of the Nvidia provided packages to make sure the packages can work together. Bare minimum conda-forge pytorch with cuda installation ```toml [workspace] channels = ["https://prefix.dev/conda-forge"] name = "pytorch-conda-forge" platforms = ["linux-64", "win-64"] [system-requirements] cuda = "12.0" [dependencies] pytorch-gpu = "*" ``` Bare minimum conda-forge pytorch with cuda installation ```toml [project] name = "pytorch-conda-forge" [tool.pixi.workspace] channels = ["https://prefix.dev/conda-forge"] platforms = ["linux-64"] [tool.pixi.system-requirements] cuda = "12.0" [tool.pixi.dependencies] pytorch-gpu = "*" ``` To deliberately install a specific version of the `cuda` packages you can depend on the `cuda-version` package which will then be interpreted by the other packages during resolution. The `cuda-version` package constraints the version of the `__cuda` virtual package and `cudatoolkit` package. This ensures that the correct version of the `cudatoolkit` package is installed and the tree of dependencies is resolved correctly. Add cuda version to the conda-forge pytorch installation ```toml [dependencies] pytorch-gpu = "*" cuda-version = "12.6.*" ``` Add cuda version to the conda-forge pytorch installation ```toml [tool.pixi.dependencies] pytorch-gpu = "*" cuda-version = "12.6.*" ``` With `conda-forge` you can also install the `cpu` version of PyTorch. A common use-case is having two environments, one for CUDA machines and one for non-CUDA machines. Adding a cpu environment ```toml [workspace] channels = ["https://prefix.dev/conda-forge"] name = "pytorch-conda-forge" platforms = ["linux-64"] [feature.gpu.system-requirements] cuda = "12.0" [feature.gpu.dependencies] cuda-version = "12.6.*" pytorch-gpu = "*" [feature.cpu.dependencies] pytorch-cpu = "*" [environments] cpu = ["cpu"] default = ["gpu"] ``` Split into environments and add a CPU environment ```toml [project] name = "pytorch-conda-forge" [tool.pixi.workspace] channels = ["https://prefix.dev/conda-forge"] platforms = ["linux-64"] [tool.pixi.feature.gpu.system-requirements] cuda = "12.0" [tool.pixi.feature.gpu.dependencies] cuda-version = "12.6.*" pytorch-gpu = "*" [tool.pixi.feature.cpu.dependencies] pytorch-cpu = "*" [tool.pixi.environments] cpu = ["cpu"] default = ["gpu"] ``` Running these environments then can be done with the `pixi run` command. ```shell pixi run --environment cpu python -c "import torch; print(torch.cuda.is_available())" pixi run -e gpu python -c "import torch; print(torch.cuda.is_available())" ``` Now you should be able to extend that with your dependencies and tasks. Here are some links to notable packages: - [pytorch](https://prefix.dev/channels/conda-forge/packages/pytorch) - [pytorch-cpu](https://prefix.dev/channels/conda-forge/packages/pytorch-cpu) - [pytorch-gpu](https://prefix.dev/channels/conda-forge/packages/pytorch-gpu) - [torchvision](https://prefix.dev/channels/conda-forge/packages/torchvision) - [torchaudio](https://prefix.dev/channels/conda-forge/packages/torchaudio) - [cuda-version](https://prefix.dev/channels/conda-forge/packages/cuda-version) ## Installing from PyPi Thanks to the integration with `uv` we can also install PyTorch from `pypi`. Mixing `[dependencies]` and `[pypi-dependencies]` When using this approach for the `torch` package, you should also install the packages that depend on `torch` from `pypi`. Thus, not mix the PyPI packages with Conda packages if there are dependencies from the Conda packages to the PyPI ones. The reason for this is that our resolving is a two step process, first resolve the Conda packages and then the PyPI packages. Thus this can not succeed if we require a Conda package to depend on a PyPI package. ### Pytorch index PyTorch packages are provided through a custom index, these are similar to Conda channels, which are maintained by the PyTorch team. To install PyTorch from the PyTorch index, you need to add the indexes to manifest. Best to do this per dependency to force the index to be used. - CPU only: - CUDA 11.8: - CUDA 12.1: - CUDA 12.4: - ROCm6: Install PyTorch from pypi ```toml [workspace] channels = ["https://prefix.dev/conda-forge"] name = "pytorch-pypi" platforms = ["osx-arm64", "linux-64", "win-64"] [dependencies] # We need a python version that is compatible with pytorch python = ">=3.11,<3.13" [pypi-dependencies] torch = { version = ">=2.5.1", index = "https://download.pytorch.org/whl/cu124" } torchvision = { version = ">=0.20.1", index = "https://download.pytorch.org/whl/cu124" } [target.osx.pypi-dependencies] # OSX has no CUDA support so use the CPU here torch = { version = ">=2.5.1", index = "https://download.pytorch.org/whl/cpu" } torchvision = { version = ">=0.20.1", index = "https://download.pytorch.org/whl/cpu" } ``` Install PyTorch from pypi ```toml [project] name = "pytorch-pypi" # We need a python version that is compatible with pytorch requires-python = ">= 3.11,<3.13" [tool.pixi.workspace] channels = ["https://prefix.dev/conda-forge"] platforms = ["osx-arm64", "linux-64", "win-64"] [tool.pixi.pypi-dependencies] torch = { version = ">=2.5.1", index = "https://download.pytorch.org/whl/cu124" } torchvision = { version = ">=0.20.1", index = "https://download.pytorch.org/whl/cu124" } [tool.pixi.target.osx.pypi-dependencies] # OSX has no CUDA support so use the CPU here torch = { version = ">=2.5.1", index = "https://download.pytorch.org/whl/cpu" } torchvision = { version = ">=0.20.1", index = "https://download.pytorch.org/whl/cpu" } ``` You can tell Pixi to use multiple environments for the multiple versions of PyTorch, either `cpu` or `gpu`. Use multiple environments for the pypi pytorch installation ```toml [workspace] channels = ["https://prefix.dev/conda-forge"] name = "pytorch-pypi-envs" platforms = ["linux-64", "win-64"] [dependencies] # We need a python version that is compatible with pytorch python = ">=3.11,<3.13" [feature.gpu] system-requirements = { cuda = "12.0" } [feature.gpu.pypi-dependencies] torch = { version = ">=2.5.1", index = "https://download.pytorch.org/whl/cu124" } torchvision = { version = ">=0.20.1", index = "https://download.pytorch.org/whl/cu124" } [feature.cpu.pypi-dependencies] torch = { version = ">=2.5.1", index = "https://download.pytorch.org/whl/cpu" } torchvision = { version = ">=0.20.1", index = "https://download.pytorch.org/whl/cpu" } [environments] gpu = { features = ["gpu"] } # Make CPU the default environment default = { features = ["cpu"] } ``` Use multiple environments for the pypi pytorch installation ```toml [project] name = "pytorch-pypi-envs" # We need a python version that is compatible with pytorch requires-python = ">= 3.11,<3.13" [tool.pixi.workspace] channels = ["https://prefix.dev/conda-forge"] platforms = ["linux-64", "win-64"] [tool.pixi.feature.gpu] system-requirements = { cuda = "12.0" } [tool.pixi.feature.gpu.pypi-dependencies] torch = { version = ">=2.5.1", index = "https://download.pytorch.org/whl/cu124" } torchvision = { version = ">=0.20.1", index = "https://download.pytorch.org/whl/cu124" } [tool.pixi.feature.cpu.pypi-dependencies] torch = { version = ">=2.5.1", index = "https://download.pytorch.org/whl/cpu" } torchvision = { version = ">=0.20.1", index = "https://download.pytorch.org/whl/cpu" } [tool.pixi.environments] gpu = { features = ["gpu"] } # Make CPU the default environment default = { features = ["cpu"] } ``` Running these environments then can be done with the `pixi run` command. ```shell pixi run --environment cpu python -c "import torch; print(torch.__version__); print(torch.cuda.is_available())" pixi run -e gpu python -c "import torch; print(torch.__version__); print(torch.cuda.is_available())" ``` ### Mixing MacOS and CUDA with `pypi-dependencies` When using pypi-dependencies, Pixi creates a β€œsolve” environment to resolve the PyPI dependencies. This process involves installing the Conda dependencies first and then resolving the PyPI packages within that environment. This can become problematic if you’re on a macOS machine and trying to resolve the CUDA version of PyTorch for Linux or Windows. Since macOS doesn’t support the Conda dependencies for CUDA, it can't install the solve environment, preventing proper resolution. **Current Status:** The Pixi maintainers are aware of this limitation and are actively working on a solution to enable cross-platform dependency resolution for such cases. In the meantime, you may need to run the resolution process on a machine that supports CUDA, such as a Linux or Windows host. ## Installing from PyTorch channel Warning This depends on the [non-free](https://www.anaconda.com/blog/is-conda-free) `main` channel from Anaconda and mixing it with `conda-forge` can lead to conflicts. Note This is the [legacy](https://dev-discuss.pytorch.org/t/pytorch-deprecation-of-conda-nightly-builds/2590) way of installing pytorch, this will not be updated to later versions as pytorch has discontinued their channel. Install PyTorch from the PyTorch channel ```toml [workspace] name = "pytorch-from-pytorch-channel" # `main` is not free! It's a paid channel for organizations over 200 people. channels = ["main", "nvidia", "pytorch"] platforms = ["osx-arm64", "linux-64", "win-64"] [feature.gpu.system-requirements] cuda = "12.0" [dependencies] pytorch = "*" [environments] gpu = ["gpu"] ``` Install PyTorch from the PyTorch channel ```toml [project] name = "pytorch-from-pytorch-channel" requires-python = ">= 3.11, < 3.13" version = "0.1.0" [tool.pixi.workspace] # `main` is not free! It's a paid channel for organizations over 200 people. channels = ["main", "nvidia", "pytorch"] platforms = ["osx-arm64", "linux-64", "win-64"] [tool.pixi.feature.gpu.system-requirements] cuda = "12.0" [tool.pixi.dependencies] pytorch = "*" [tool.pixi.environments] gpu = ["gpu"] ``` ## Troubleshooting When you had trouble figuring out why your PyTorch installation is not working, please share your solution or tips with the community by creating a **PR** to this documentation. #### Testing the `pytorch` installation You can verify your PyTorch installation with this command: ```shell pixi run python -c "import torch; print(torch.__version__); print(torch.cuda.is_available())" ``` #### Checking the CUDA version of your machine To check which CUDA version Pixi detects on your machine, run: ```text pixi info ``` Example output: ```text ... Virtual packages: __unix=0=0 : __linux=6.5.9=0 : __cuda=12.5=0 ... ``` If `__cuda` is missing, you can verify your system’s CUDA version using NVIDIA tools: ```shell nvidia-smi ``` To check the version of the CUDA toolkit installed in your environment: ```shell pixi run nvcc --version ``` #### Reasons for broken installations Broken installations often result from mixing incompatible channels or package sources: 1. **Mixing Conda Channels** Using both `conda-forge` and the legacy `pytorch` channel can cause conflicts. Choose one channel and stick with it to avoid issues in the environment. 1. **Mixing Conda and PyPI Packages** If you install PyTorch from pypi, all packages that depend on torch must also come from PyPI. Mixing Conda and PyPI packages within the same dependency chain leads to conflicts. To summarize: - Pick one Conda channel (conda-forge or pytorch) to fetch `pytorch` from, and avoid mixing. - For PyPI installations, ensure all related packages come from PyPI. #### GPU version of `pytorch` not installing: 1. Using [conda-Forge](#installing-from-conda-forge) - Ensure `system-requirements.cuda` is set to inform Pixi to install CUDA-enabled packages. - Use the `cuda-version` package to pin the desired CUDA version. 1. Using [PyPI](#installing-from-pypi) - Use the appropriate PyPI index to fetch the correct CUDA-enabled wheels. #### Resolution Failures If you see an error like this: **ABI tag mismatch** ```text β”œβ”€β–Ά failed to resolve pypi dependencies ╰─▢ Because only the following versions of torch are available: torch<=2.5.1 torch==2.5.1+cpu and torch==2.5.1 has no wheels with a matching Python ABI tag, we can conclude that torch>=2.5.1,<2.5.1+cpu cannot be used. And because torch==2.5.1+cpu has no wheels with a matching platform tag and you require torch>=2.5.1, we can conclude that your requirements are unsatisfiable. ``` This happens when the Python ABI tag (Application Binary Interface) doesn’t match the available PyPI wheels. Solution: - Check your Python version and ensure it’s compatible with the PyPI wheels for `torch`. The ABI tag is based on the Python version is embedded in the wheel filename, e.g. `cp312` for Python 3.12. - If needed, lower the `requires-python` or `python` version in your configuration. - For example, as of now, PyTorch doesn’t fully support Python 3.13; use Python 3.12 or earlier. **Platform tag mismatch** ```text β”œβ”€β–Ά failed to resolve pypi dependencies ╰─▢ Because only the following versions of torch are available: torch<=2.5.1 torch==2.5.1+cu124 and torch>=2.5.1 has no wheels with a matching platform tag, we can conclude that torch>=2.5.1,<2.5.1+cu124 cannot be used. And because you require torch>=2.5.1, we can conclude that your requirements are unsatisfiable. ``` This occurs when the platform tag doesn’t match the PyPI wheels available to be installed. Example Issue: `torch==2.5.1+cu124` (CUDA 12.4) was attempted on an `osx` machine, but this version is only available for `linux-64` and `win-64`. Solution: - Use the correct PyPI index for your platform: - CPU-only: Use the cpu index for all platforms. - CUDA versions: Use cu124 for linux-64 and win-64. Correct Indexes: - CPU: https://download.pytorch.org/whl/cpu - CUDA 12.4: https://download.pytorch.org/whl/cu124 This ensures PyTorch installations are compatible with your system’s platform and Python version. In this tutorial, we will show you how to create a simple Python project with Pixi. We will show some of the features that Pixi provides, that are currently not a part of `pdm`, `poetry` etc. ## Why is this useful? Pixi builds upon the conda ecosystem, which allows you to create a Python environment with all the dependencies you need. This is especially useful when you are working with multiple Python interpreters and bindings to C and C++ libraries. For example, GDAL from PyPI does not have binary C dependencies, but the conda package does. On the other hand, some packages are only available through PyPI, which `pixi` can also install for you. Best of both worlds, let's give it a go! ## `pixi.toml` and `pyproject.toml` We support two manifest formats: `pyproject.toml` and `pixi.toml`. In this tutorial, we will use the `pyproject.toml` format because it is the most common format for Python projects. ## Let's get started Let's start out by creating a new project that uses a `pyproject.toml` file. ```shell pixi init pixi-py --format pyproject ``` This creates a project directory with the following structure: ```shell pixi-py β”œβ”€β”€ pyproject.toml └── src └── pixi_py └── __init__.py ``` The `pyproject.toml` for the project looks like this: ```toml [project] dependencies = [] name = "pixi-py" requires-python = ">= 3.11" version = "0.1.0" [build-system] build-backend = "hatchling.build" requires = ["hatchling"] [tool.pixi.workspace] channels = ["conda-forge"] platforms = ["osx-arm64"] [tool.pixi.pypi-dependencies] pixi_py = { path = ".", editable = true } [tool.pixi.tasks] ``` This project uses a src-layout, but Pixi supports both [flat- and src-layouts](https://packaging.python.org/en/latest/discussions/src-layout-vs-flat-layout/#src-layout-vs-flat-layout). ### What's in the `pyproject.toml`? Okay, so let's have a look at what sections have been added and how we can modify the `pyproject.toml`. These first entries were added to the `pyproject.toml` file: ```toml # Main pixi entry [tool.pixi.workspace] channels = ["conda-forge"] # This is your machine platform by default platforms = ["osx-arm64"] ``` The `channels` and `platforms` are added to the `[tool.pixi.workspace]` section. Channels like `conda-forge` manage packages similar to PyPI but allow for different packages across languages. The keyword `platforms` determines which platforms the workspace supports. The `pixi_py` package itself is added as an `editable` dependency. This means that the package is installed in editable mode, so you can make changes to the package and see the changes reflected in the environment, without having to re-install it. ```toml # Editable installs [tool.pixi.pypi-dependencies] pixi-py = { path = ".", editable = true } ``` In pixi, unlike other package managers, this is explicitly stated in the `pyproject.toml` file. The main reason being so that you can choose which environment this package should be included in. ### Managing both Conda and PyPI dependencies Our projects usually depend on other packages. ```shell cd pixi-py # Move into the project directory pixi add black ``` This will add the `black` package as a Conda package to the `pyproject.toml` file. Which will result in the following addition to the `pyproject.toml`: ```toml [tool.pixi.dependencies] black = ">=25.1.0,<26" # (1)! ``` 1. Or the latest version that is available on the [conda-forge](https://prefix.dev/channels/conda-forge/packages/black) channel. But we can also be strict about the version that should be used. ```shell pixi add black=25 ``` resulting in: ```toml [tool.pixi.dependencies] black = "25.*" ``` Sometimes there are packages that aren't available on conda channels but are published on PyPI. ```shell pixi add black --pypi ``` which results in the addition to the `dependencies` key in the `pyproject.toml` ```toml dependencies = ["black"] ``` When using the `pypi-dependencies` you can make use of the `optional-dependencies` that other packages make available as extras. For example, `flask` makes the `async` dependencies option, which can be added with the `--pypi` keyword: ```shell pixi add "flask[async]==3.1.0" --pypi ``` which updates the `dependencies` entry to ```toml dependencies = ["black", "flask[async]==3.1.0"] ``` Extras in `pixi.toml` This tutorial focuses on the use of the `pyproject.toml`, but in case you're curious, the `pixi.toml` would contain the following entry after the installation of a PyPI package including an optional dependency: ```toml [pypi-dependencies] flask = { version = "==3.1.0", extras = ["async"] } ``` ### Installation: `pixi install` Pixi always ensures the environment is up-to-date with the `pyproject.toml` file before running something in it. If you want to do it manually anyway, you can run: ```shell pixi install ``` We now have a new directory called `.pixi` in the workspace root. The environment is a Conda environment with all the Conda and PyPI dependencies installed into it. The environment is always a result of the `pixi.lock` file, which is generated from the `pyproject.toml` file. This file contains the exact versions of the dependencies that were installed into the environment across platforms. ## What's in the environment? Using `pixi list`, you can see what's in the environment, this is essentially a nicer view on the lock file (`pixi.lock`): ```shell Package Version Build Size Kind Source asgiref 3.8.1 68.5 KiB pypi asgiref-3.8.1-py3-none-any.whl black 24.10.0 py313h8f79df9_0 388.7 KiB conda black blinker 1.9.0 23.9 KiB pypi blinker-1.9.0-py3-none-any.whl bzip2 1.0.8 h99b78c6_7 120 KiB conda bzip2 ca-certificates 2024.12.14 hf0a4a13_0 153.4 KiB conda ca-certificates click 8.1.8 pyh707e725_0 82.7 KiB conda click flask 3.1.0 335.9 KiB pypi flask-3.1.0-py3-none-any.whl itsdangerous 2.2.0 45.8 KiB pypi itsdangerous-2.2.0-py3-none-any.whl jinja2 3.1.5 484.8 KiB pypi jinja2-3.1.5-py3-none-any.whl libexpat 2.6.4 h286801f_0 63.2 KiB conda libexpat libffi 3.4.2 h3422bc3_5 38.1 KiB conda libffi liblzma 5.6.3 h39f12f2_1 96.8 KiB conda liblzma libmpdec 4.0.0 h99b78c6_0 67.6 KiB conda libmpdec libsqlite 3.48.0 h3f77e49_1 832.8 KiB conda libsqlite libzlib 1.3.1 h8359307_2 45.3 KiB conda libzlib markupsafe 3.0.2 73 KiB pypi markupsafe-3.0.2-cp313-cp313-macosx_11_0_arm64.whl mypy_extensions 1.0.0 pyha770c72_1 10.6 KiB conda mypy_extensions ncurses 6.5 h5e97a16_3 778.3 KiB conda ncurses openssl 3.4.0 h81ee809_1 2.8 MiB conda openssl packaging 24.2 pyhd8ed1ab_2 58.8 KiB conda packaging pathspec 0.12.1 pyhd8ed1ab_1 40.1 KiB conda pathspec pixi_py 0.1.0 pypi (editable) platformdirs 4.3.6 pyhd8ed1ab_1 20 KiB conda platformdirs python 3.13.1 h4f43103_105_cp313 12.3 MiB conda python python_abi 3.13 5_cp313 6.2 KiB conda python_abi readline 8.2 h92ec313_1 244.5 KiB conda readline tk 8.6.13 h5083fa2_1 3 MiB conda tk tzdata 2025a h78e105d_0 120 KiB conda tzdata werkzeug 3.1.3 743 KiB pypi werkzeug-3.1.3-py3-none-any.whl ``` Here, you can see the different conda and Pypi packages listed. As you can see, the `pixi-py` package that we are working on is installed in editable mode. Every environment in Pixi is isolated but reuses files that are hard-linked from a central cache directory. This means that you can have multiple environments with the same packages but only have the individual files stored once on disk. Why does the environment have a Python interpreter? The Python interpreter is also installed into the environment. This is because the Python interpreter version is read from the `requires-python` field in the `pyproject.toml` file. This is used to determine the Python version to install into the environment. This way, Pixi automatically manages/bootstraps the Python interpreter for you, so no more `brew`, `apt` or other system install steps. How to use the Free-threaded interpreter? If you want to use a free-threaded Python interpreter, you can add the `python-freethreading` dependency with: ```text pixi add python-freethreading ``` This ensures that a free-threaded version of Python is installed into the environment. This might not work with other packages that are not thread-safe yet. You can read more about free-threaded Python [here](https://docs.python.org/3/howto/free-threading-python.html). ### Multiple environments Pixi can also create multiple environments, this works well together with the `dependency-groups` feature in the `pyproject.toml` file. Let's add a dependency-group, which Pixi calls a `feature`, named `test`. And add the `pytest` package to this group. ```shell pixi add --pypi --feature test pytest ``` This results in the package being added to the `dependency-groups` following the [PEP 735](https://peps.python.org/pep-0735/). ```toml [dependency-groups] test = ["pytest"] ``` After we have added the `dependency-groups` to the `pyproject.toml`, Pixi sees these as a [`feature`](../../reference/pixi_manifest/#the-feature-and-environments-tables), which can contain a collection of `dependencies`, `tasks`, `channels`, and more. ```shell pixi workspace environment add default --solve-group default --force pixi workspace environment add test --feature test --solve-group default ``` Which results in: ```toml [tool.pixi.environments] default = { solve-group = "default" } test = { features = ["test"], solve-group = "default" } ``` Solve Groups Solve groups are a way to group dependencies together. This is useful when you have multiple environments that share the same dependencies. For example, maybe `pytest` is a dependency that influences the dependencies of the `default` environment. By putting these in the same solve group, you ensure that the versions in `test` and `default` are exactly the same. Without specifying the environment name, Pixi will default to the `default` environment. If you want to install or run the `test` environment, you add `--environment test` to the command. ```shell pixi install --environment test pixi run --environment test pytest ``` ## Getting code to run Let's add some code to the `pixi_py` package. We will add a new function to the `src/pixi_py/__init__.py` file: ```python from rich import print def hello(): return "Hello, [bold magenta]World[/bold magenta]!", ":vampire:" def say_hello(): print(*hello()) ``` Now add the `rich` dependency from PyPI ```shell pixi add --pypi rich ``` Let's see if this works by running: ```shell pixi run python -c 'import pixi_py; pixi_py.say_hello()' ``` Which should output: ```shell Hello, World! πŸ§› ``` Slow? This might be slow the first time because Pixi installs the project, but it will be near instant the second time. Pixi runs the self installed Python interpreter. Then, we are importing the `pixi_py` package, which is installed in editable mode. The code calls the `say_hello` function that we just added. And it works! Cool! ## Testing this code Okay, so let's add a test for this function. Let's add a `tests/test_me.py` file in the root of the project. Giving us the following project structure: ```shell . β”œβ”€β”€ pixi.lock β”œβ”€β”€ src β”‚ └── pixi_py β”‚ └── __init__.py β”œβ”€β”€ pyproject.toml └── tests/test_me.py ``` ```python from pixi_py import hello def test_pixi_py(): assert hello() == ("Hello, [bold magenta]World[/bold magenta]!", ":vampire:") ``` Let's add an easy task for running the tests. ```shell pixi task add --feature test test "pytest" ``` So Pixi has a task system to make it easy to run commands. Similar to `npm` scripts or something you would specify in a `Justfile`. Pixi tasks Tasks are a cool Pixi feature that is powerful and runs in a cross-platform shell. You can do caching, dependencies and more. Read more about tasks in the [tasks](../../workspace/advanced_tasks/) section. ```shell pixi run test ``` results in the following output: ```shell ✨ Pixi task (test): pytest . ================================================================================================= test session starts ================================================================================================= platform darwin -- Python 3.12.2, pytest-8.1.1, pluggy-1.4.0 rootdir: /private/tmp/pixi-py configfile: pyproject.toml collected 1 item test_me.py . [100%] ================================================================================================== 1 passed in 0.00s ================================================================================================= ``` Why didn't I have to specify the environment? The `test` task was added to the `test` feature/environment. When you run the `test` task, Pixi automatically switches to the `test` environment, because that is the only one associated with the `test` feature. Neat! It seems to be working! ### Test vs Default environment Let's compare the output of the test and default environments. We add the `--explicit` flag to show the explicit dependencies in the environment. ```shell pixi list --explicit --environment test # vs. default environment pixi list --explicit ``` We see that the `test` environment has: ```shell package version build size kind source ... pytest 8.1.1 1.1 mib pypi pytest-8.1.1-py3-none-any.whl ... ``` However, the default environment is missing the `pytest` package. This way, you can finetune your environments to only have the packages that are needed. E.g. you could also have a `dev` environment that has `pytest` and `ruff` installed, but you could omit these from the `prod` environment. There is a [docker](https://github.com/prefix-dev/pixi/tree/main/examples/docker) example that shows how to set up a minimal `prod` environment and copy from there. ## Replacing PyPI packages with conda packages Last thing, Pixi provides the ability for `pypi` packages to depend on `conda` packages. Let's confirm this with: ```shell pixi list pygments ``` Note that it was installed as a `pypi` package: ```shell Package Version Build Size Kind Source pygments 2.17.2 4.1 MiB pypi pygments-2.17.2-py3-none-any.http.whl ``` This is a dependency of the `rich` package. As you can see by running: ```shell pixi tree --invert pygments ``` Let's explicitly add `pygments` to the `pyproject.toml` file. ```shell pixi add pygments ``` This will add the following to the `pyproject.toml` file: ```toml [tool.pixi.dependencies] pygments = "=2.19.1,<3" ``` We can now see that the `pygments` package is now installed as a conda package. ```shell pixi list pygments ``` Now results in: ```shell Package Version Build Size Kind Source pygments 2.19.1 pyhd8ed1ab_0 867.8 KiB conda pygments ``` This way, PyPI dependencies and conda dependencies can be mixed and matched to seamlessly interoperate. ```shell pixi run python -c 'import pixi_py; pixi_py.say_hello()' ``` And it still works! ## Conclusion In this tutorial, you've seen how easy it is to use a `pyproject.toml` to manage your Pixi dependencies and environments. We have also explored how to use PyPI and conda dependencies seamlessly together in the same workspace and install optional dependencies to manage Python packages. Hopefully, this provides a flexible and powerful way to manage your Python projects and a fertile base for further exploration with Pixi. Thanks for reading! Happy Coding πŸš€ Any questions? Feel free to reach out or share this tutorial on [X](https://twitter.com/prefix_dev), [join our Discord](https://discord.gg/kKV8ZxyzY4), send us an [e-mail](mailto:hi@prefix.dev) or follow our [GitHub](https://github.com/prefix-dev). In this tutorial we will show you how to import existing environments into a Pixi workspace. In case some words used in the tutorial don't make sense to you, you may get value from first reading some of our other tutorials, like [our first workspace walthrough](../../first_workspace/) and [our guide to multi-environment workspaces](../multi_environment/). ## `pixi import` Within any Pixi workspace, you can use [`pixi import`](https://pixi.sh/latest/reference/cli/pixi/import/) to import an environment from a given file. At the time of writing, we support two import file formats: `conda-env` and `pypi-txt`. Running `pixi import` without providing a `format` will try each format in turn until one succeeds, or return an error if all formats fail. If you don't already have a Pixi workspace, you can create one with [`pixi init`](https://pixi.sh/latest/reference/cli/pixi/init/). ### `conda-env` format The `conda-env` format is for files in the conda ecosystem (typically called `environment.yml`) following [the syntax specified in the conda docs](https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html#create-env-file-manually). Suppose our environment to import is specified in this file: environment.yml ```yaml name: simple-env channels: ["conda-forge"] dependencies: - python - pip: - httpx ``` We can then run `pixi import --format=conda-env environment.yml` to import the environment into our workspace. By default, since our `environment.yml` has a `name` field, this creates a `feature` of the same name (or uses the feature of that name if it already exists), and creates an `environment` containing that feature (with [`no-default-feature`](https://pixi.sh/latest/reference/pixi_manifest/#the-environments-table) set): pixi.toml ```toml [feature.simple-env] channels = ["conda-forge"] [feature.simple-env.dependencies] python = "*" [feature.simple-env.pypi-dependencies] httpx = "*" [environments] simple-env = { features = ["simple-env"], no-default-feature = true } ``` It is then possible to define tasks for the imported environment, run commands in that environment, and launch a [`pixi shell`](https://pixi.sh/latest/reference/cli/pixi/shell) in that environment β€” see the [getting started guide](../../getting_started/) for links to start learning about these topics! For files without a `name` field, or to override the default behavior, you can specify custom `--feature` and `--environment` names. This also allows importing into existing features and environments (including the `default` feature and environment). For example, given this other environment file to import: env2.yml ```yaml channels: ["conda-forge"] dependencies: - numpy ``` Running `pixi import --format=conda-env --feature=numpy --environment=simple-env env2.yml` will import the environment into a new feature called "numpy", and include that feature in the existing `simple-env` environment (effectively merging the environments from our two input files): pixi.toml ```toml [feature.simple-env] channels = ["conda-forge"] [feature.simple-env.dependencies] python = "*" [feature.simple-env.pypi-dependencies] httpx = "*" [feature.numpy] channels = ["conda-forge"] [feature.numpy.dependencies] numpy = "*" [environments] simple-env = { features = ["simple-env", "numpy"], no-default-feature = true } ``` It is also possible to specify platforms for the feature via the `--platform` argument. For example, `pixi import --format=conda-env --feature=unix --platform=linux-64 --platform=osx-arm64 environment.yml` adds the following to our workspace manifest: pixi.toml ```toml [feature.unix] platforms = ["linux-64", "osx-arm64"] channels = ["conda-forge"] [feature.unix.target.linux-64.dependencies] python = "*" [feature.unix.target.osx-arm64.dependencies] python = "*" [environments] unix = { features = ["unix"], no-default-feature = true } ``` ### `pypi-txt` format The `pypi-txt` format is for files in the PyPI ecosystem following [the requirements file format specification in the `pip` docs](https://pip.pypa.io/en/stable/reference/requirements-file-format/). Suppose our environment to import is specified in this file: requirements.txt ```yaml cowpy array-api-extra>=0.8 ``` We can then run `pixi import --format=pypi-txt --feature=my-feature1 requirements.txt` to import the environment into our workspace. It is necessary to specify a `feature` or `environment` name (or both) via the arguments of the same names. If only one of these names is provided, a matching name is used for the other field. Hence, the following lines are added to our workspace manifest: pixi.toml ```toml [feature.my-feature1.pypi-dependencies] cowpy = "*" array-api-extra = ">=0.8" [environments] my-feature1 = { features = ["my-feature1"], no-default-feature = true } ``` Any dependencies listed in the file are added as [`pypi-dependencies`](https://pixi.sh/latest/reference/pixi_manifest/#pypi-dependencies). An environment will be created with [`no-default-feature`](https://pixi.sh/latest/reference/pixi_manifest/#the-environments-table) set if the given environment name does not already exist. It is then possible to define tasks for that environment, run commands in that environment, and launch a [`pixi shell`](https://pixi.sh/latest/reference/cli/pixi/shell) in that environment β€” see the [getting started guide](../../getting_started/) for links to start learning about these topics! Just like the `conda-env` format, it is possible to import into existing features/environments (including the `default` feature/environment), and set specific platforms for the feature. See the previous section for details. ## `pixi init --import` It is also possible to combine the steps of `pixi init` and `pixi import` into one, via [`pixi init --import`](https://pixi.sh/latest/reference/cli/pixi/init/#arg---import). For example, `pixi init --import environment.yml` (using the same file from our example above) produces a manifest which looks like this: pixi.toml ```toml [workspace] authors = ["Lucas Colley "] channels = ["conda-forge"] name = "simple-env" platforms = ["osx-arm64"] version = "0.1.0" [tasks] [dependencies] python = "*" [pypi-dependencies] httpx = "*" ``` Unlike `pixi import`, this by default uses the `default` feature and environment. Thus, it achieves a very similar workspace to that obtained by running `pixi init` and `pixi import --feature=default environment.yml`. One difference is that `pixi init --import` will by default inherit its name from the given import file (if the file specifies the `name` field), rather than from its working directory. Supported formats At the time of writing, only the `conda-env` format is supported by `pixi init --import`. ## Conclusion For further details, please see the CLI reference documentation for [`pixi import`](https://pixi.sh/latest/reference/cli/pixi/import/) and [`pixi init --import`](https://pixi.sh/latest/reference/cli/pixi/init/#arg---import). If there are any questions, or you know how to improve this tutorial, feel free to reach out to us on [GitHub](https://github.com/prefix-dev/pixi). At the time of writing, there are plans for many potential extensions to our import capabilities β€” you can follow along with that work at the `import` [roadmap issue on GitHub](https://github.com/prefix-dev/pixi/issues/4192). In this tutorial we will show you how to use multiple environments in one Pixi workspace. ## Why Is This Useful? When developing a workspace you often need different tools, libraries or test environments. With Pixi you can define multiple environments in one workspace and switch between them easily. A developer often needs all the tools they can get, whereas your testing infrastructure might not require all those tools, and your production environment might require even less. Setting up different environments for these different use cases can be a hassle, but with Pixi it's easy. ## Glossary This tutorial possibly uses some new terms, here is a quick overview: #### **Feature** A feature defines a part of an environment, but are not useful without being part of an environment. You can define multiple features in one workspace. A feature can contain `tasks`, `dependencies`, `platforms`, `channels` and [more](../../reference/pixi_manifest/#the-feature-table). You can mix multiple features to create an environment. Features are defined by adding `[feature..*]` to a table in the manifest file. #### **Environment** An environment is a collection of features. Environments can actually be installed and activated to run tasks in. You can define multiple environments in one workspace. Defining environments is done by adding them to the `[environments]` table in the manifest file. #### **Default** Instead of specifying `[feature..dependencies]`, one can populate `[dependencies]` directly. These top level table, are added to the "default" feature, which is added to every environment, unless you specifically opt-out. ## Let's Get Started We'll simply start with a new workspace, you can skip this step if you already have a Pixi workspace. ```shell pixi init workspace cd workspace pixi add python ``` Now we have a new Pixi workspace with the following structure: ```text β”œβ”€β”€ .pixi β”‚Β Β  └── envs β”‚Β Β  └── default β”œβ”€β”€ pixi.lock └── pixi.toml ``` Note the `.pixi/envs/default` directory, this is where the default environment is stored. If no environment is specified, Pixi will create or use the `default` environment. ### Adding a feature Let's start adding a simple `test` feature to our workspace. We can do this through the command line, or by editing the `pixi.toml` file. Here we will use the command line, and add a `pytest` dependency to the `test` feature in our workspace. ```shell pixi add --feature test pytest ``` This will add the following to our `pixi.toml` file: ```toml [feature.test.dependencies] pytest = "*" ``` This table acts exactly the same as a normal `dependencies` table, but it is only used when the `test` feature is part of an environment. ### Adding an environment We will add the `test` environment to our workspace to add some testing tools. We can do this through the command line, or by editing the `pixi.toml` file. Here we will use the command line: ```shell pixi workspace environment add test --feature test ``` This will add the following to our `pixi.toml` file: ```toml [environments] test = ["test"] ``` ### Running a task We can now run a task in our new environment. ```shell pixi run --environment test pytest --version ``` This has created the test environment, and run the `pytest --version` command in it. You can see the environment will be added to the `.pixi/envs` directory. ```shell β”œβ”€β”€ .pixi β”‚Β Β  └── envs β”‚Β Β  β”œβ”€β”€ default β”‚Β Β  └── test ``` If you want to see the environment, you can use the `pixi list` command. ```shell pixi list --environment test ``` If you have special test commands that always fit with the test environment you can add them to the `test` feature. ```shell # Adding the 'test' task to the 'test' feature and setting it to run `pytest` pixi task add test --feature test pytest ``` This will add the following to our `pixi.toml` file: ```toml [feature.test.tasks] test = "pytest" ``` Now you don't have to specify the environment when running the test command. ```shell pixi run test ``` In this example similar to running `pixi run --environment test pytest` This works as long as there is only one of the environments that has the `test` task. ## Using multiple environments to test multiple versions of a package In this example we will use multiple environments to test a package against multiple versions of Python. This is a common use-case when developing a python library. This workflow can be translated to any setup where you want to have multiple environments to test against a different dependency setups. For this example we assume you have run the commands in the previous example, and have a workspace with a `test` environment. To allow python being flexible in the new environments we need to set it to a more flexible version e.g. `*`. ```shell pixi add "python=*" ``` We will start by setting up two features, `py311` and `py312`. ```shell pixi add --feature py311 python=3.11 pixi add --feature py312 python=3.12 ``` We'll add the `test` and Python features to the corresponding environments. ```shell pixi workspace environment add test-py311 --feature py311 --feature test pixi workspace environment add test-py312 --feature py312 --feature test ``` This should result in adding the following to the `pixi.toml`: ```toml [feature.py311.dependencies] python = "3.11.*" [feature.py312.dependencies] python = "3.12.*" [environments] test-py311 = ["py311", "test"] test-py312 = ["py312", "test"] ``` Now we can run the test command in both environments. ```shell pixi run --environment test-py311 test pixi run --environment test-py312 test # Or using the task directly, which will spawn a dialog to select the environment of choice pixi run test ``` These could now run in CI to test separate environments: .github/workflows/test.yml ```yaml test: runs-on: ubuntu-latest strategy: matrix: environment: [test-py311, test-py312] steps: - uses: actions/checkout@v4 - uses: prefix-dev/setup-pixi@v0 with: environments: ${{ matrix.environment }} - run: pixi run -e ${{ matrix.environment }} test ``` More info on that in the GitHub actions [documentation](../../integration/ci/github_actions/). ## Development, Testing, Production environments This assumes a clean workspace, so if you have been following along, you might want to start a new workspace. ```shell pixi init production_project cd production_project ``` Like before we'll start with creating multiple features. ```shell pixi add numpy python # default feature pixi add --feature dev jupyterlab pixi add --feature test pytest ``` Now we'll add the environments. To accommodate the different use-cases we'll add a `production`, `test` and `default` environment. - The `production` environment will only have the `default` feature, as that is the bare minimum for the project to run. - The `test` environment will have the `test` and the `default` features, as we want to test the project and require the testing tools. - The `default` environment will have the `dev` and `test` features. We make this the default environment as it will be the easiest to run locally, as it avoids the need to specify the environment when running tasks. We'll also add the `solve-group` `prod` to the environments, this will make sure that the dependencies are solved as if they were in the same environment. This will result in the `production` environment having the exact same versions of the dependencies as the `default` and `test` environment. This way we can be sure that the project will run in the same way in all environments. ```shell pixi workspace environment add production --solve-group prod pixi workspace environment add test --feature test --solve-group prod # --force is used to overwrite the default environment pixi workspace environment add default --feature dev --feature test --solve-group prod --force ``` If we run `pixi list -x` for the environments we can see that the different environments have the exact same dependency versions. ```shell # Default environment Package Version Build Size Kind Source jupyterlab 4.3.4 pyhd8ed1ab_0 6.9 MiB conda jupyterlab numpy 2.2.1 py313ha4a2180_0 6.2 MiB conda numpy pytest 8.3.4 pyhd8ed1ab_1 253.1 KiB conda pytest python 3.13.1 h4f43103_105_cp313 12.3 MiB conda python Environment: test Package Version Build Size Kind Source numpy 2.2.1 py313ha4a2180_0 6.2 MiB conda numpy pytest 8.3.4 pyhd8ed1ab_1 253.1 KiB conda pytest python 3.13.1 h4f43103_105_cp313 12.3 MiB conda python Environment: production Package Version Build Size Kind Source numpy 2.2.1 py313ha4a2180_0 6.2 MiB conda numpy python 3.13.1 h4f43103_105_cp313 12.3 MiB conda python ``` ### Non default environments When you want to have an environment that doesn't have the `default` feature, you can use the `--no-default-feature` flag. This will result in the environment not having the `default` feature, and only the features you specify. A common use-case of this would be having an environment that can generate your documentation. Let's add the `mkdocs` dependency to the `docs` feature. ```shell pixi add --feature docs mkdocs ``` Now we can add the `docs` environment without the `default` feature. ```shell pixi workspace environment add docs --feature docs --no-default-feature ``` If we run `pixi list -x -e docs` we can see that it only has the `mkdocs` dependency. ```shell Environment: docs Package Version Build Size Kind Source mkdocs 1.6.1 pyhd8ed1ab_1 3.4 MiB conda mkdocs ``` ## Conclusion The multiple environment feature is extremely powerful and can be used in many different ways. There is much more to explore in the [reference](../../reference/pixi_manifest/#the-feature-and-environments-tables) and [advanced](../../workspace/multi_environment/) sections. If there are any questions, or you know how to improve this tutorial, feel free to reach out to us on [GitHub](https://github.com/prefix-dev/pixi). In this tutorial, we will show you how to develop a ROS 2 package using `pixi`. The tutorial is written to be executed from top to bottom, missing steps might result in errors. The audience for this tutorial is developers who are familiar with ROS 2 and how are interested to try Pixi for their development workflow. ## Prerequisites - You need to have `pixi` installed. If you haven't installed it yet, you can follow the instructions in the [installation guide](../../). The crux of this tutorial is to show you only need pixi! - On Windows, it's advised to enable Developer mode. Go to Settings -> Update & Security -> For developers -> Developer mode. ## Create a Pixi workspace ```shell pixi init my_ros2_project -c robostack-humble -c conda-forge cd my_ros2_project ``` It should have created a directory structure like this: ```shell my_ros2_project β”œβ”€β”€ .gitattributes β”œβ”€β”€ .gitignore └── pixi.toml ``` The `pixi.toml` file is the manifest file for your workspace. It should look like this: pixi.toml ```toml [workspace] name = "my_ros2_project" version = "0.1.0" description = "Add a short description here" authors = ["User Name "] channels = ["robostack-humble", "conda-forge"] # Your project can support multiple platforms, the current platform will be automatically added. platforms = ["linux-64"] [tasks] [dependencies] ``` The `channels` you added to the `init` command are repositories of packages, you can search in these repositories through our [prefix.dev](https://prefix.dev/channels) website. The `platforms` are the systems you want to support, in Pixi you can support multiple platforms, but you have to define which platforms, so Pixi can test if those are supported for your dependencies. For the rest of the fields, you can fill them in as you see fit. ## Add ROS 2 dependencies To use a Pixi workspace you don't need any dependencies on your system, all the dependencies you need should be added through pixi, so other users can use your workspace without any issues. Let's start with the `turtlesim` example ```shell pixi add ros-humble-desktop ros-humble-turtlesim ``` This will add the `ros-humble-desktop` and `ros-humble-turtlesim` packages to your manifest. Depending on your internet speed this might take a minute, as it will also install ROS in your workspace folder (`.pixi`). Now run the `turtlesim` example. ```shell pixi run ros2 run turtlesim turtlesim_node ``` **Or** use the `shell` command to start a shell in the activated environment in your terminal. ```shell pixi shell ros2 run turtlesim turtlesim_node ``` Congratulations you have ROS 2 running on your machine with pixi! Some more fun with the turtle To control the turtle you can run the following command in a new terminal ```shell cd my_ros2_project pixi run ros2 run turtlesim turtle_teleop_key ``` Now you can control the turtle with the arrow keys on your keyboard. ## Add a custom Python node As ros works with custom nodes, let's add a custom node to our project. ```shell pixi run ros2 pkg create --build-type ament_python --destination-directory src --node-name my_node my_package ``` To build the package we need some more dependencies: ```shell pixi add colcon-common-extensions "setuptools<=58.2.0" ``` Add the created initialization script for the ros workspace to your manifest file. Then run the build command ```shell pixi run colcon build ``` This will create a sourceable script in the `install` folder, you can source this script through an activation script to use your custom node. Normally this would be the script you add to your `.bashrc` but instead you tell Pixi to use it by adding the following to `pixi.toml`: pixi.toml ```toml [activation] scripts = ["install/setup.sh"] ``` pixi.toml ```toml [activation] scripts = ["install/setup.bat"] ``` Multi platform support You can add multiple activation scripts for different platforms, so you can support multiple platforms with one workspace. Use the following example to add support for both Linux and Windows, using the [target](../../workspace/multi_platform_configuration/#activation) syntax. ```toml [workspace] platforms = ["linux-64", "win-64"] [activation] scripts = ["install/setup.sh"] [target.win-64.activation] scripts = ["install/setup.bat"] ``` Now you can run your custom node with the following command ```shell pixi run ros2 run my_package my_node ``` ## Simplify the user experience In `pixi` we have a feature called `tasks`, this allows you to define a task in your manifest file and run it with a simple command. Let's add a task to run the `turtlesim` example and the custom node. ```shell pixi task add sim "ros2 run turtlesim turtlesim_node" pixi task add build "colcon build --symlink-install" pixi task add hello "ros2 run my_package my_node" ``` Now you can run these task by simply running ```shell pixi run sim pixi run build pixi run hello ``` Advanced task usage Tasks are a powerful feature in pixi. - You can add [`depends-on`](../../workspace/advanced_tasks/#depends-on) to the tasks to create a task chain. - You can add [`cwd`](../../workspace/advanced_tasks/#working-directory) to the tasks to run the task in a different directory from the root of the workspace. - You can add [`inputs` and `outputs`](../../workspace/advanced_tasks/#caching) to the tasks to create a task that only runs when the inputs are changed. - You can use the [`target`](../../reference/pixi_manifest/#the-target-table) syntax to run specific tasks on specific machines. ```toml [tasks] sim = "ros2 run turtlesim turtlesim_node" build = {cmd = "colcon build --symlink-install", inputs = ["src"]} hello = { cmd = "ros2 run my_package my_node", depends-on = ["build"] } ``` ## Build a C++ node To build a C++ node you need to add the `ament_cmake` and some other build dependencies to your manifest file. ```shell pixi add ros-humble-ament-cmake-auto compilers pkg-config "cmake<4" ninja colcon-common-extensions ``` Now you can create a C++ node with the following command ```shell pixi run ros2 pkg create --build-type ament_cmake --destination-directory src --node-name my_cpp_node my_cpp_package ``` Now you can build it again and run it with the following commands ```shell # Passing arguments to the build command to build with Ninja, add them to the manifest if you want to default to ninja. pixi run build --cmake-args -G Ninja pixi run ros2 run my_cpp_package my_cpp_node ``` Tip Add the cpp task to the manifest file to simplify the user experience. ```shell pixi task add hello-cpp "ros2 run my_cpp_package my_cpp_node" ``` ## Conclusion In this tutorial, we showed you how to create a Python & CMake ROS2 project using `pixi`. We also showed you how to **add dependencies** to your project using `pixi`, and how to **run your project** using `pixi run`. This way you can make sure that your project is **reproducible** on all your machines that have `pixi` installed. ## Show Off Your Work! Finished with your project? We'd love to see what you've created! Share your work on social media using the hashtag #pixi and tag us @prefix_dev. Let's inspire the community together! ## Frequently asked questions ### What happens with `rosdep`? Currently, we don't support `rosdep` in a Pixi environment, so you'll have to add the packages using `pixi add`. `rosdep` will call `conda install` which isn't supported in a Pixi environment. ### Where can I find more documentation on the `robostack-*` channels? You can find more documentation on RoboStack channels in the [RoboStack documentation](https://robostack.github.io/). ### Community examples ROS 2 Humble on macOS,[Simulating differential drive using Gazebo](https://medium.com/@davisogunsina/ros-2-macos-support-installing-and-running-ros-2-on-macos-79039d1d3655). In this tutorial, we will show you how to develop a Rust package using `pixi`. The tutorial is written to be executed from top to bottom, missing steps might result in errors. The audience for this tutorial is developers who are familiar with Rust and `cargo` and how are interested to try Pixi for their development workflow. The benefit would be within a rust workflow that you lock both rust and the C/System dependencies your project might be using. For example tokio users might depend on `openssl` for linux. ## Prerequisites - You need to have `pixi` installed. If you haven't installed it yet, you can follow the instructions in the [installation guide](../../). The crux of this tutorial is to show you only need pixi! ## Create a Pixi workspace ```shell pixi init my_rust_project cd my_rust_project ``` It should have created a directory structure like this: ```shell my_rust_project β”œβ”€β”€ .gitattributes β”œβ”€β”€ .gitignore └── pixi.toml ``` The `pixi.toml` file is the manifest file for your workspace. It should look like this: pixi.toml ```toml [workspace] name = "my_rust_project" version = "0.1.0" description = "Add a short description here" authors = ["User Name "] channels = ["conda-forge"] platforms = ["linux-64"] # (1)! [tasks] [dependencies] ``` 1. The `platforms` is set to your system's platform by default. You can change it to any platform you want to support. e.g. `["linux-64", "osx-64", "osx-arm64", "win-64"]`. ## Add Rust dependencies To use a Pixi workspace you don't need any dependencies on your system, all the dependencies you need should be added through pixi, so other users can use your workspace without any issues. ```shell pixi add rust ``` This will add the `rust` package to your `pixi.toml` file under `[dependencies]`. Which includes the `rust` toolchain, and `cargo`. ## Add a `cargo` project Now that you have rust installed, you can create a `cargo` project in your `pixi` workspace. ```shell pixi run cargo init ``` `pixi run` is pixi's way to run commands in an environment. It will make sure that the environment is activated for the command to run. It runs its own cross-platform shell, if you want more information checkout the [`tasks` documentation](../../workspace/advanced_tasks/). You can also activate the environment in a shell by running `pixi shell`, after that you don't need `pixi run ...` anymore. Now we can build a `cargo` project using `pixi`. ```shell pixi run cargo build ``` To simplify the build process, you can add a `build` task to your `pixi.toml` file using the following command: ```shell pixi task add build "cargo build" ``` Which creates this field in the `pixi.toml` file: pixi.toml ```toml [tasks] build = "cargo build" ``` And now you can build your project using: ```shell pixi run build ``` You can also run your project using: ```shell pixi run cargo run ``` Which you can simplify with a task again. ```shell pixi task add start "cargo run" ``` So you should get the following output: ```shell pixi run start Hello, world! ``` Congratulations, you have a Rust project running on your machine with pixi! ## Next steps, why is this useful when there is `rustup`? Cargo is not a binary package manager, but a source-based package manager. This means that you need to have the Rust compiler installed on your system to use it. And possibly other dependencies that are not included in the `cargo` package manager. For example, you might need to install `openssl` or `libssl-dev` on your system to build a package. This is the case for `pixi` as well, but `pixi` will install these dependencies in your workspace folder, so you don't have to worry about them. Add the following dependencies to your cargo project: ```shell pixi run cargo add git2 ``` If your system is not preconfigured to build C and have the `libssl-dev` package installed you will not be able to build the project: ```shell pixi run build ... Could not find directory of OpenSSL installation, and this `-sys` crate cannot proceed without this knowledge. If OpenSSL is installed and this crate had trouble finding it, you can set the `OPENSSL_DIR` environment variable for the compilation process. Make sure you also have the development packages of openssl installed. For example, `libssl-dev` on Ubuntu or `openssl-devel` on Fedora. If you are in a situation where you think the directory *should* be found automatically, please open a bug at https://github.com/sfackler/rust-openssl and include information about your system as well as this message. $HOST = x86_64-unknown-linux-gnu $TARGET = x86_64-unknown-linux-gnu openssl-sys = 0.9.102 It looks like you are compiling on Linux and also targeting Linux. Currently this requires the `pkg-config` utility to find OpenSSL but unfortunately `pkg-config` could not be found. If you have OpenSSL installed you can likely fix this by installing `pkg-config`. ... ``` You can fix this, by adding the necessary dependencies for building git2, with pixi: ```shell pixi add openssl pkg-config compilers ``` Now you should be able to build your project again: ```shell pixi run build ... Compiling git2 v0.18.3 Compiling my_rust_project v0.1.0 (/my_rust_project) Finished dev [unoptimized + debuginfo] target(s) in 7.44s Running `target/debug/my_rust_project` ``` ## Extra: Add more tasks You can add more tasks to your `pixi.toml` file to simplify your workflow. For example, you can add a `test` task to run your tests: ```shell pixi task add test "cargo test" ``` And you can add a `clean` task to clean your project: ```shell pixi task add clean "cargo clean" ``` You can add a formatting task to your project: ```shell pixi task add fmt "cargo fmt" ``` You can extend these tasks to run multiple commands with the use of the `depends-on` field. ```shell pixi task add lint "cargo clippy" --depends-on fmt ``` ## Conclusion In this tutorial, we showed you how to create a Rust project using `pixi`. We also showed you how to **add dependencies** to your project using `pixi`. This way you can make sure that your project is **reproducible** on **any system** that has `pixi` installed. ## Show Off Your Work! Finished with your project? We'd love to see what you've created! Share your work on social media using the hashtag #pixi and tag us @prefix_dev. Let's inspire the community together! Welcome to the guide designed to ease your transition from `conda` or `mamba` to `pixi`. This document compares key commands and concepts between these tools, highlighting `pixi`'s unique approach to managing environments and packages. With `pixi`, you'll experience a workspace-based workflow, enhancing your development process, and allowing for easy sharing of your work. ## Why Pixi? `Pixi` builds upon the foundation of the conda ecosystem, introducing a workspace-centric approach rather than focusing solely on environments. This shift towards workspaces offers a more organized and efficient way to manage dependencies and run code, tailored to modern development practices. ## Key Differences at a Glance | Task | Conda/Mamba | Pixi | | --------------------------- | ------------------------------------------------- | -------------------------------------------------------------------------- | | Installation | Requires an installer | Download and add to path (See [installation](../../)) | | Creating an Environment | `conda create -n myenv -c conda-forge python=3.8` | `pixi init myenv` followed by `pixi add python=3.8` | | Activating an Environment | `conda activate myenv` | `pixi shell` within the workspace directory | | Deactivating an Environment | `conda deactivate` | `exit` from the `pixi shell` | | Running a Task | `conda run -n myenv python my_program.py` | `pixi run python my_program.py` (See [run](../../reference/cli/pixi/run/)) | | Installing a Package | `conda install numpy` | `pixi add numpy` | | Uninstalling a Package | `conda remove numpy` | `pixi remove numpy` | No `base` environment Conda has a base environment, which is the default environment when you start a new shell. **Pixi does not have a base environment**. And requires you to install the tools you need in the workspace or globally. Using `pixi global install bat` will install `bat` in a global environment, which is not the same as the `base` environment in conda. Activating Pixi environment in the current shell For some advanced use-cases, you can activate the environment in the current shell. This uses the `pixi shell-hook` which prints the activation script, which can be used without `pixi` itself. ```shell ~/myenv > eval "$(pixi shell-hook)" ``` ## Environment vs Workspace `Conda` and `mamba` focus on managing environments, while `pixi` emphasizes workspaces. In `pixi`, a workspace is a folder containing a [manifest](../../reference/pixi_manifest/)(`pixi.toml`/`pyproject.toml`) file that describes the workspace, a `pixi.lock` lock-file that describes the exact dependencies, and a `.pixi` folder that contains the environment. This workspace-centric approach allows for easy sharing and collaboration, as the workspace folder contains all the necessary information to recreate the environment. It manages more than one environment for more than one platform in a single workspace, and allows for easy switching between them. (See [multiple environments](../../workspace/multi_environment/)) ## Global environments `conda` installs all environments in one global location. When this is important to you for filesystem reasons, you can use the [detached-environments](../../reference/pixi_configuration/#detached-environments) feature of pixi. ```shell pixi config set detached-environments true # or a specific location pixi config set detached-environments /path/to/envs ``` This will make the installation of the environments go to the same folder. `pixi` does have the `pixi global` command to install tools on your machine. (See [global](../../reference/cli/pixi/global/)) This is not a replacement for `conda` but works the same as [`pipx`](https://pipx.pypa.io/stable/) and [`condax`](https://mariusvniekerk.github.io/condax/). It creates a single isolated environment for the given requirement and installs the binaries into the global path. ```shell pixi global install bat bat pixi.toml ``` Never install `pip` with `pixi global` Installations with `pixi global` get their own isolated environment. Installing `pip` with `pixi global` will create a new isolated environment with its own `pip` binary. Using that `pip` binary will install packages in the `pip` environment, making it unreachable from anywhere as you can't activate it. ## Automated switching You can import `environment.yml` files into a Pixi workspace β€” see our [import tutorial](../../tutorials/import/). Exporting your environment If you are working with Conda users or systems, you can [export your environment to a `environment.yml`](../../reference/cli/pixi/workspace/export/) file to share them. ```shell pixi workspace export conda-environment ``` Additionally you can export a [conda explicit specification](../../reference/cli/pixi/workspace/export/). ## Troubleshooting Encountering issues? Here are solutions to some common problems when being used to the `conda` workflow: - Dependency `is excluded due to strict channel priority not using this option from: 'https://conda.anaconda.org/conda-forge/'` This error occurs when the package is in multiple channels. `pixi` uses a strict channel priority. See [channel priority](../../advanced/channel_logic/) for more information. - `pixi global install pip`, pip doesn't work. `pip` is installed in the global isolated environment. Use `pixi add pip` in a workspace to install `pip` in the workspace environment and use that workspace. - `pixi global install ` -> `import ` -> `ModuleNotFoundError: No module named ''` The library is installed in the global isolated environment. Use `pixi add ` in a workspace to install the library in the workspace environment and use that workspace. Welcome to the guide designed to ease your transition from `poetry` to `pixi`. This document compares key commands and concepts between these tools, highlighting `pixi`'s unique approach to managing environments and packages. With `pixi`, you'll experience a workspace-based workflow similar to `poetry` while including the `conda` ecosystem and allowing for easy sharing of your work. ## Why Pixi? Poetry is most-likely the closest tool to Pixi in terms of workspace management, in the python ecosystem. On top of the PyPI ecosystem, `pixi` adds the power of the conda ecosystem, allowing for a more flexible and powerful environment management. ## Quick look at the differences | Task | Poetry | Pixi | | -------------------------- | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | Creating an Environment | `poetry new myenv` | `pixi init myenv` | | Running a Task | `poetry run which python` | `pixi run which python` `pixi` uses a built-in cross platform shell for run where poetry uses your shell. | | Installing a Package | `poetry add numpy` | `pixi add numpy` adds the conda variant. `pixi add --pypi numpy` adds the PyPI variant. | | Uninstalling a Package | `poetry remove numpy` | `pixi remove numpy` removes the conda variant. `pixi remove --pypi numpy` removes the PyPI variant. | | Building a package | `poetry build` | We've yet to implement package building and publishing | | Publishing a package | `poetry publish` | We've yet to implement package building and publishing | | Reading the pyproject.toml | `[tool.poetry]` | `[tool.pixi]` | | Defining dependencies | `[tool.poetry.dependencies]` | `[tool.pixi.dependencies]` for conda, `[tool.pixi.pypi-dependencies]` or `[project.dependencies]` for PyPI dependencies | | Dependency definition | - `numpy = "^1.2.3"` - `numpy = "~1.2.3"` - `numpy = "*"` | - `numpy = ">=1.2.3 <2.0.0"` - `numpy = ">=1.2.3 <1.3.0"` - `numpy = "*"` | | Lock file | `poetry.lock` | `pixi.lock` | | Environment directory | `~/.cache/pypoetry/virtualenvs/myenv` | `./.pixi` Defaults to the workspace directory, move this using the [`detached-environments`](../../reference/pixi_configuration/#detached-environments) | ## Support both `poetry` and `pixi` in my workspace You can allow users to use `poetry` and `pixi` in the same workspace, they will not touch each other's parts of the configuration or system. It's best to duplicate the dependencies, basically making an exact copy of the `tool.poetry.dependencies` into `tool.pixi.pypi-dependencies`. Make sure that `python` is only defined in the `tool.pixi.dependencies` and not in the `tool.pixi.pypi-dependencies`. Mixing `pixi` and `poetry` It's possible to use `poetry` in `pixi` environments but this is advised against. Pixi supports PyPI dependencies in a different way than `poetry` does, and mixing them can lead to unexpected behavior. As you can only use one package manager at a time, it's best to stick to one. If using poetry on top of a Pixi workspace, you'll always need to install the `poetry` environment after the `pixi` environment. And let `pixi` handle the `python` and `poetry` installation. # Global Tools \[ Pixi global demo \](https://github.com/user-attachments/assets/e94dc06f-75ae-4aa0-8830-7cb190d3f367) With `pixi global`, users can manage globally installed tools in a way that makes them available from any directory. This means that the Pixi environment will be placed in a global location, and the tools will be exposed to the system `PATH`, allowing you to run them from the command line. Some packages, especially those with graphical user interfaces, will also add start menu entries. ## Basic Usage Running the following command installs [`rattler-build`](https://prefix-dev.github.io/rattler-build/latest/) on your system. ```bash pixi global install rattler-build ``` What's great about `pixi global` is that, by default, it isolates each package in its own environment, exposing only the necessary entry points. This means you don't have to worry about removing a package and accidentally breaking seemingly unrelated packages. This behavior is quite similar to that of [`pipx`](https://pipx.pypa.io/latest/installation/). However, there are times when you may want multiple dependencies in the same environment. For instance, while `ipython` is really useful on its own, it becomes much more useful when `numpy` and `matplotlib` are available when using it. Let's execute the following command: ```bash pixi global install ipython --with numpy --with matplotlib ``` `numpy` exposes executables, but since it's added via `--with` it's executables are not being exposed. Importing `numpy` and `matplotlib` now works as expected. ```bash ipython -c 'import numpy; import matplotlib' ``` At some point, you might want to install multiple versions of the same package on your system. Since they will be all available on the system `PATH`, they need to be exposed under different names. Let's check out the following command: ```bash pixi global install --expose py3=python "python=3.12" ``` By specifying `--expose` we specified that we want to expose the executable `python` under the name `py3`. The package `python` has more executables, but since we specified `--exposed` they are not auto-exposed. You can run `py3` to start the python interpreter. ```shell py3 -c "print('Hello World')" ``` ## Install Dependencies From Source Pixi global also allows you to install [Pixi packages](../../build/getting_started/). Let's assume there's a C++ package we'd like to install globally from source. First, it needs to have a package manifest: pixi.toml ```toml [package] name = "cpp_math" version = "0.1.0" [package.build] backend = { name = "pixi-build-cmake", version = "*" } ``` If the source is on your machine, you can install it like this: ```shell pixi global install --path /path/to/cpp_math ``` If the source resides in a git repository, you can access it like this: ```shell pixi global install --git https://github.com/ORG_NAME/cpp_math.git ``` One has to take care if the source contains multiple outputs, see for example this recipe: recipe.yaml ```yaml recipe: name: multi-output version: "0.1.0" outputs: - package: name: foobar build: script: - if: win then: - if not exist %PREFIX%\bin mkdir %PREFIX%\bin - echo @echo off > %PREFIX%\bin\foobar.bat - echo echo Hello from foobar >> %PREFIX%\bin\foobar.bat else: - mkdir -p $PREFIX/bin - echo "#!/usr/bin/env bash" > $PREFIX/bin/foobar - echo "echo Hello from foobar" >> $PREFIX/bin/foobar - chmod +x $PREFIX/bin/foobar - package: name: bizbar build: script: - if: win then: - if not exist %PREFIX%\bin mkdir %PREFIX%\bin - echo @echo off > %PREFIX%\bin\bizbar.bat - echo echo Hello from bizbar >> %PREFIX%\bin\bizbar.bat else: - mkdir -p $PREFIX/bin - echo "#!/usr/bin/env bash" > $PREFIX/bin/bizbar - echo "echo Hello from bizbar" >> $PREFIX/bin/bizbar - chmod +x $PREFIX/bin/bizbar ``` In this case, we have to specify which output we want to install: ```shell pixi global install --path /path/to/package foobar ``` ## Shell Completions When you work in a terminal, you are using a shell and shells can process completions of command line tools. The process works like this: you type "git -" in your terminal and press ``. Then, your shell will present you all the flags `git` offers. However, that only works if you have the completions installed for the tool in question. If the tool you installed via `pixi global` contains completions they will be automatically installed. At the moment, only Linux and macOS are supported. First install a tool with `pixi global`: ```shell pixi global install git ``` The completions can be found under [`$PIXI_HOME`](../../reference/environment_variables/)`/completions`. You can then load the completions in the startup script of your shell: ~/.bashrc ```bash # bash, default on most Linux distributions for file in ~/.pixi/completions/bash/*; do [ -e "$file" ] && source "$file" done ``` ~/.zshrc ```zsh # zsh, default on macOS fpath+=(~/.pixi/completions/zsh) autoload -Uz compinit compinit ``` ~/.config/fish/config.fish ```fish # fish for file in ~/.pixi/completions/fish/* source $file end ``` Note Completions of packages are installed as long as their binaries are exposed under the same name: e.g. `exposed = { git = "git" }`. Tip Are you missing shell completions for your favorite CLI tool? Add them similar to [conda-forge/crush-feedstock #37](https://github.com/conda-forge/crush-feedstock/pull/37/changes). ## Adding a Series of Tools at Once Without specifying an installation environment, you can add multiple tools at once: ```shell pixi global install pixi-pack rattler-build ``` This command generates the following entry in the manifest: ```toml [envs.pixi-pack] channels = ["conda-forge"] dependencies= { pixi-pack = "*" } exposed = { pixi-pack = "pixi-pack" } [envs.rattler-build] channels = ["conda-forge"] dependencies = { rattler-build = "*" } exposed = { rattler-build = "rattler-build" } ``` Creating two separate non-interfering environments, while exposing only the minimum required binaries. ## Creating a Data Science Sandbox Environment You can create an environment with multiple tools using the following command: ```shell pixi global install --environment data-science --expose jupyter --expose ipython jupyter numpy pandas matplotlib ipython ``` This command generates the following entry in the manifest: ```toml [envs.data-science] channels = ["conda-forge"] dependencies = { jupyter = "*", ipython = "*" } exposed = { jupyter = "jupyter", ipython = "ipython" } ``` In this setup, both `jupyter` and `ipython` are exposed from the `data-science` environment, allowing you to run: ```shell > ipython # Or > jupyter lab ``` These commands will be available globally, making it easy to access your preferred tools without switching environments. ## Install Packages For a Different Platform You can install packages for a different platform using the `--platform` flag. This is useful when you want to install packages for a different platform, such as `osx-64` packages on `osx-arm64`. For example, running this on `osx-arm64`: ```shell pixi global install --platform osx-64 python ``` will create the following entry in the manifest: ```toml [envs.python] channels = ["conda-forge"] platforms = ["osx-64"] dependencies = { python = "*" } # ... ``` ## Packaging ### Opt Out of `CONDA_PREFIX` Pixi activates the target environment before running a globally exposed executable, which usually sets `CONDA_PREFIX` to that environment's path. Some tools inspect `CONDA_PREFIX` and expect it to point to a standard Conda installation, which can lead to confusing behavior when the tool runs from a Pixi-managed prefix. Package authors can opt out of exporting `CONDA_PREFIX` by shipping a marker file at `etc/pixi//global-ignore-conda-prefix` inside the environment (for example `etc/pixi/borg/global-ignore-conda-prefix` for an executable named `borg`). When this file is present for the exposed executable, Pixi removes `CONDA_PREFIX` from the environment variables, letting the tool behave as if no Conda environment is active. Here's a minimal `recipe.yaml` snippet that adds the marker while building the package with executable `borg`: ```yaml build: script: - mkdir -p $PREFIX/etc/pixi/borg - touch $PREFIX/etc/pixi/borg/global-ignore-conda-prefix ``` After installing such a package with `pixi global install`, the exposed executable no longer sees `CONDA_PREFIX` and can fall back to its default behavior. # Concepts documentation When building a package, you often have to do more than just run the code. Steps like formatting, linting, compiling, testing, benchmarking, etc. are often part of a workspace. With Pixi tasks, this should become much easier to do. Here are some quick examples pixi.toml ```toml [tasks] # Commands as lists so you can also add documentation in between. configure = { cmd = [ "cmake", # Use the cross-platform Ninja generator "-G", "Ninja", # The source is in the root directory "-S", ".", # We wanna build in the .build directory "-B", ".build", ] } # Add task descriptions, to be surfaced when the tasks are listed say-hello = { cmd = ["echo", "hello world"], description = "Greet the world." } # Depend on other tasks build = { cmd = ["ninja", "-C", ".build"], depends-on = ["configure"] } # Using environment variables run = "python main.py $PIXI_PROJECT_ROOT" set = "export VAR=hello && echo $VAR" # Cross platform file operations copy = "cp pixi.toml pixi_backup.toml" clean = "rm pixi_backup.toml" move = "mv pixi.toml backup.toml" # Setting a default environment for the task test = { cmd = "pytest", default-environment = "test" } ``` ## Depends on Just like packages can depend on other packages, our tasks can depend on other tasks. This allows for complete pipelines to be run with a single command. An obvious example is **compiling** before **running** an application. Checkout our [`cpp_sdl` example](https://github.com/prefix-dev/pixi/tree/main/examples/cpp-sdl) for a running example. In that package we have some tasks that depend on each other, so we can assure that when you run `pixi run start` everything is set up as expected. ```fish pixi task add configure "cmake -G Ninja -S . -B .build" pixi task add build "ninja -C .build" --depends-on configure pixi task add start ".build/bin/sdl_example" --depends-on build ``` Results in the following lines added to the `pixi.toml` pixi.toml ```toml [tasks] # Configures CMake configure = "cmake -G Ninja -S . -B .build" # Build the executable but make sure CMake is configured first. build = { cmd = "ninja -C .build", depends-on = ["configure"] } # Start the built executable start = { cmd = ".build/bin/sdl_example", depends-on = ["build"] } ``` The tasks will be executed after each other: - First `configure` because it has no dependencies. - Then `build` as it only depends on `configure`. - Then `start` as all its dependencies are run. If one of the commands fails (exit with non-zero code.) it will stop and the next one will not be started. With this logic, you can also create aliases as you don't have to specify any command in a task. ```shell pixi task add fmt ruff pixi task add lint pylint ``` pixi.toml ```toml [tasks] fmt = "ruff" lint = "pylint" ``` Hiding Tasks Tasks can be hidden from user facing commands by [naming them](#task-names) with an `_` prefix. ### Shorthand Syntax Pixi supports a shorthand syntax for defining tasks that only depend on other tasks. Instead of using the more verbose `depends-on` field, you can define a task directly as an array of dependencies. Executing: ```text pixi task alias style fmt lint ``` results in the following `pixi.toml`: pixi.toml ```toml [tasks] fmt = "ruff" lint = "pylint" style = [{ task = "fmt" }, { task = "lint" }] ``` Now you can run both tools with one command. ```shell pixi run style ``` ### Environment specification for task dependencies You can specify the environment to use for a dependent task: pixi.toml ```toml [tasks] test = "python --version" [feature.py311.dependencies] python = "3.11.*" [feature.py312.dependencies] python = "3.12.*" [environments] py311 = ["py311"] py312 = ["py312"] # Task that depends on other tasks in different environments [tasks.test-all] depends-on = [ { task = "test", environment = "py311" }, { task = "test", environment = "py312" }, ] ``` This allows you to run tasks in different environments as part of a single pipeline. When you run the main task, Pixi ensures each dependent task uses its specified environment: ```shell pixi run test-all ``` The environment specified for a task dependency takes precedence over the environment specified via the CLI `--environment` flag. This means even if you run `pixi run test-all --environment py312`, the first dependency will still run in the `py311` environment as specified in the TOML file. In the example above, the `test-all` task runs the `test` task in both Python 3.11 and 3.12 environments, allowing you to verify compatibility across different Python versions with a single command. ## Working directory Pixi tasks support the definition of a working directory. `cwd` stands for Current Working Directory. The directory is relative to the Pixi workspace root, where the `pixi.toml` file is located. By default, tasks are executed from the Pixi workspace root. To change this, use the `--cwd` flag. For example, consider a Pixi workspace structured as follows: ```shell β”œβ”€β”€ pixi.toml └── scripts └── bar.py ``` To add a task that runs the `bar.py` file from the `scripts` directory, use: ```shell pixi task add bar "python bar.py" --cwd scripts ``` This will add the following line to [manifest file](../../reference/pixi_manifest/): pixi.toml ```toml [tasks] bar = { cmd = "python bar.py", cwd = "scripts" } ``` ## Default environment You can set the default Pixi [environment](../../tutorials/multi_environment/#adding-an-environment) used by a task using the `default-environment` field: pixi.toml ```toml [feature.test.dependencies] pytest = "*" [environments] test = ["test"] # An environment covering the "test" feature [tasks] test = { cmd = "pytest", default-environment = "test" } ``` The default environment can be overridden as usual with the `--environment` argument: ```shell pixi run -e other_environment test ``` ## Task Arguments Tasks can accept arguments that can be referenced in the command. This provides more flexibility and reusability for your tasks. ### Why Use Task Arguments? Task arguments make your tasks more versatile and maintainable: - **Reusability**: Create generic tasks that can work with different inputs rather than duplicating tasks for each specific case - **Flexibility**: Change behavior at runtime without modifying your pixi.toml file - **Clarity**: Make your task intentions clear by explicitly defining what values can be customized - **Validation**: Define required arguments to ensure tasks are called correctly - **Default values**: Set sensible defaults while allowing overrides when needed For example, instead of creating separate build tasks for development and production modes, you can create a single parameterized task that handles both cases. Arguments can be: - **Required**: must be provided when running the task - **Optional**: can have default values that are used when not explicitly provided - **Constrained**: can be restricted to a set of allowed values using `choices` ### Defining Task Arguments Define arguments in your task using the `args` field: pixi.toml ```toml # Task with required arguments [tasks.greet] args = ["name"] cmd = "echo Hello, {{ name }}!" # Task with optional arguments (default values) [tasks.build] args = [ { "arg" = "project", "default" = "my-app" }, { "arg" = "mode", "default" = "development" }, ] cmd = "echo Building {{ project }} with {{ mode }} mode" # Task with mixed required and optional arguments [tasks.deploy] args = ["service", { "arg" = "environment", "default" = "staging" }] cmd = "echo Deploying {{ service }} to {{ environment }}" ``` Argument naming restrictions Argument names cannot contain dashes (`-`) due to them being seen as a minus sign in MiniJinja. Use underscores (`_`) or camelCase instead. ### Using Task Arguments When running a task, provide arguments in the order they are defined: ```shell # Required argument pixi run greet John ✨ Pixi task (greet in default): echo Hello, John! # Default values are used when omitted pixi run build ✨ Pixi task (build in default): echo Building my-app in development mode # Override default values pixi run build my-project production ✨ Pixi task (build in default): echo Building my-project in production mode # Mixed argument types pixi run deploy auth-service ✨ Pixi task (deploy in default): echo Deploying auth-service to staging pixi run deploy auth-service production ✨ Pixi task (deploy in default): echo Deploying auth-service to production ``` ### Passing Extra Arguments with `--` When a task defines typed `args`, all command-line values are matched against those definitions. If you need to pass *additional* flags or arguments directly to the underlying command on top of the typed args, use `--` as a separator. Everything after `--` is forwarded verbatim to the command, regardless of the task's `args` definition. ```toml [tasks.test] cmd = "pytest {{ target }} -v" args = [{ arg = "target", default = "tests/unit" }] ``` ```shell # Without --, extra flags would cause an error: # Γ— task 'test' received more arguments than expected # hint: use `--` to separate task arguments from extra passthrough arguments pixi run test tests/integration --tb=short --maxfail=5 # With --, the typed arg is filled and the rest is forwarded: pixi run test tests/integration -- --tb=short --maxfail=5 ✨ Pixi task (test in default): pytest tests/integration -v --tb=short --maxfail=5 ``` You can also use `--` when relying on a default argument value: ```shell # "target" uses its default, "--maxfail=5" is forwarded to the command pixi run test -- --maxfail=5 ✨ Pixi task (test in default): pytest tests/unit -v --maxfail=5 ``` Tasks without typed args For tasks that do **not** define `args`, `--` is passed through to the underlying command unchanged. This preserves its meaning for programs that use `--` themselves (e.g. `git log -- somefile`). ### Restricting Values with Choices You can restrict the allowed values of an argument using the `choices` field. If a value is provided that is not in the list, Pixi will report an error instead of running the task. pixi.toml ```toml # Task with choices to restrict allowed values [tasks.compile] args = [{ "arg" = "mode", "choices" = ["debug", "release"] }] cmd = "echo 'Compiling in {{ mode }} mode'" # Task with choices and a default value [tasks.test] args = [ { "arg" = "suite", "default" = "unit", "choices" = [ "unit", "integration", "e2e", ] }, ] cmd = "echo 'Running {{ suite }} tests'" ``` ```shell # Providing a valid choice pixi run compile debug ✨ Pixi task (compile): echo 'Compiling in debug mode' Compiling in debug mode # Default value must also be one of the choices pixi run test ✨ Pixi task (test): echo 'Running unit tests' Running unit tests # Providing an invalid value results in an error pixi run compile fast Γ— got 'fast' for argument 'mode' of task 'compile', choose from: debug, release ``` ### Passing Arguments to Dependent Tasks You can pass arguments to tasks that are dependencies of other tasks: pixi.toml ```toml # Base task with arguments [tasks.install] args = [ { arg = "path", default = "/default/path" }, # Path to manifest { arg = "flag", default = "--normal" }, # Installation flag ] cmd = "echo Installing with manifest {{ path }} and flag {{ flag }}" # Dependent task specifying positional arguments for the base task [tasks.install-release] depends-on = [{ task = "install", args = ["/path/to/manifest", "--debug"] }] # Task with multiple dependencies, passing different arguments [tasks.deploy] cmd = "echo Deploying" depends-on = [ # Override with named custom path and named verbose flag { task = "install", args = [ { path = "/custom/path" }, { flag = "--verbose" }, ] }, # Other dependent tasks can be added here ] ``` When executing a dependent task, the arguments are passed to the dependency: ```shell pixi run install-release ✨ Pixi task (install in default): echo Installing with manifest /path/to/manifest and flag --debug pixi run deploy ✨ Pixi task (install in default): echo Installing with manifest /custom/path and flag --verbose ✨ Pixi task (deploy in default): echo Deploying ``` When a dependent task doesn't specify all arguments, the default values are used for the missing ones: pixi.toml ```toml [tasks.base-task] args = [ { "arg" = "arg1", "default" = "default1" }, # First argument with default { "arg" = "arg2", "default" = "default2" }, # Second argument with default ] cmd = "echo Base task with {{ arg1 }} and {{ arg2 }}" [tasks.partial-override] # Only override the first argument depends-on = [{ "task" = "base-task", "args" = ["override1"] }] ``` ```shell pixi run partial-override ✨ Pixi task (base-task in default): echo Base task with override1 and default2 ``` For a dependent task to accept arguments to pass to the dependency, you can use the same syntax as passing arguments to the command: pixi.toml ```toml [tasks.base-task] args = [ { "arg" = "arg1", "default" = "default1" }, # First argument with default { "arg" = "arg2", "default" = "default2" }, # Second argument with default ] cmd = "echo Base task with {{ arg1 }} and {{ arg2 }}" [tasks.partial-override] # Only override the first argument depends-on = [{ "task" = "base-task", "args" = ["override1"] }] [tasks.partial-override-with-arg] # Only override the first argument args = [ { arg = "arg2", default = "new-default2" }, # Argument with new default ] depends-on = [{ task = "base-task", args = ["override1", "{{ arg2 }}"] }] ``` ```shell pixi run partial-override-with-arg ✨ Pixi task (base-task in default): echo Base task with override1 and new-default2 pixi run partial-override-with-arg cli-arg ✨ Pixi task (base-task in default): echo Base task with override1 and cli-arg ``` ### MiniJinja Templating for Task Arguments Task commands and env variables defined in the manifest support MiniJinja templating syntax for accessing and formatting argument values. This provides powerful flexibility when constructing commands. Templating and ad-hoc CLI commands MiniJinja templating is only applied to tasks defined in your manifest file (`pixi.toml` / `pyproject.toml`). Ad-hoc commands passed directly to `pixi run` on the command line are **not** templated by default, so commands like `pixi run echo '{{ hello }}'` are passed through as-is. Use the `--templated` flag to opt in to template rendering for CLI commands: ```shell pixi run --templated echo '{{ pixi.platform }}' ``` Basic syntax for using an argument in your command: pixi.toml ```toml [tasks] greet = { cmd = "echo Hello, {{ name }}!", args = ["name"] } ``` You can also use filters to transform argument values: pixi.toml ```toml [tasks] # The arg `text`, converted to uppercase, will be printed. task1 = { cmd = "echo {{ text | upper }}", args = ["text"] } # If arg `text` contains 'hoi', it will be converted to lowercase. The result will be printed. task2 = { cmd = "echo {{ text | lower if 'hoi' in text }}", args = [ { arg = "text", default = "" }, ] } # With `a` and `b` being strings, they will be appended and then printed. task3 = { cmd = "echo {{ a + b }}", args = ["a", { arg = "b", default = "!" }] } # If the string "win" is in arg `platform`, "windows" will be printed, otherwise "unix". task4 = { cmd = """echo {% if "win" in platform %}windows{% else %}unix{% endif %}""", args = [ "platform", ] } # `names` will be split by whitespace and then every name will be printed separately task5 = { cmd = "{% for name in names | split %} echo {{ name }};{% endfor %}", args = [ "names", ] } ``` #### Pixi Variables In addition to task arguments, Pixi automatically provides a `pixi` object in the MiniJinja context with system variables: | Variable | Description | Example Value | | ----------------------- | ---------------------------------------------------------------- | --------------------------------- | | `pixi.platform` | The platform name for the environment in which the task will run | `linux-64`, `osx-arm64`, `win-64` | | `pixi.environment.name` | The name of the current environment (when available) | `default`, `prod`, `test` | | `pixi.manifest_path` | Absolute path to the manifest file | `/path/to/project/pixi.toml` | | `pixi.version` | The version of pixi being used | `0.59.0` | | `pixi.init_cwd` | The current working directory when pixi was invoked | `/path/to/cwd` | | `pixi.is_win` | Boolean flag indicating if the platform is Windows | `true` or `false` | | `pixi.is_unix` | Boolean flag indicating if the platform is Unix-like | `true` or `false` | | `pixi.is_linux` | Boolean flag indicating if the platform is Linux | `true` or `false` | | `pixi.is_osx` | Boolean flag indicating if the platform is macOS | `true` or `false` | These variables are particularly useful for creating platform-specific or environment-aware tasks: pixi.toml ```toml [tasks] # Platform-specific commands build = { cmd = "cargo build --target {{ pixi.platform }}", args = [] } download-binary = { cmd = "curl -O https://example.com/binary-{{ pixi.platform }}.tar.gz", args = [] } # Conditional execution based on platform install = { cmd = "{% if pixi.is_win %}install.bat{% else %}./install.sh{% endif %}", args = [] } # Environment-aware tasks deploy = { cmd = "deploy.sh --env {{ pixi.environment.name }}", args = [] } # Using manifest path validate = { cmd = "validator --manifest {{ pixi.manifest_path }}", args = [] } # Using init_cwd in inputs/outputs for caching mkdir_test = { cmd = "mkdir -p {{ pixi.init_cwd }}/test", outputs = ["{{ pixi.init_cwd }}/test"] } ``` The pixi variables can also be combined with task arguments: pixi.toml ```toml [tasks] deploy = { cmd = "deploy.sh --platform {{ pixi.platform }} --env {{ environment }} --version {{ pixi.version }}", args = [{ arg = "environment", default = "staging" }] } ``` When running tasks with typed arguments, the platform will automatically reflect the best platform for the environment where the task executes. For more information about available filters and template syntax, see the [MiniJinja documentation](https://docs.rs/minijinja/latest/minijinja/filters/index.html). ## Task Names A task name follows these rules: - **No spaces** are allowed in the name. - Must **be unique** within the table. - `_` at the start of the name will **hide** the task from the `pixi task list` command. Hiding tasks can be useful if your workspace defines many tasks but your users only need to use a subset of them. pixi.toml ```toml # Hidden task that is only intended to be used by other tasks [tasks._git-clone] args = ["url"] cmd = "echo git clone {{ url }}" # Hidden task that clones a dependency [tasks._clone-subproject] depends-on = [ { task = "_git-clone", args = [ "https://git.hub/org/subproject.git", ] }, ] # Task to build the project which depends on cloning a dependency [tasks.build] cmd = "echo Building project" depends-on = ["_clone-subproject"] ``` ## Caching When you specify `inputs` and/or `outputs` to a task, Pixi will reuse the result of the task. For the cache, Pixi checks that the following are true: - No package in the environment has changed. - The selected inputs and outputs are the same as the last time the task was run. We compute fingerprints of all the files selected by the globs and compare them to the last time the task was run. - The command is the same as the last time the task was run. If all of these conditions are met, Pixi will not run the task again and instead use the existing result. Inputs and outputs can be specified as globs, which will be expanded to all matching files. You can also use MiniJinja templates in your `inputs` and `outputs` fields to parameterize the paths, making tasks more reusable: pixi.toml ```toml [tasks] # This task will only run if the `main.py` file has changed. run = { cmd = "python main.py", inputs = ["main.py"] } # This task will remember the result of the `curl` command and not run it again if the file `data.csv` already exists. download_data = { cmd = "curl -o data.csv https://example.com/data.csv", outputs = [ "data.csv", ] } # This task will only run if the `src` directory has changed and will remember the result of the `make` command. build = { cmd = "make", inputs = [ "src/*.cpp", "include/*.hpp", ], outputs = [ "build/app.exe", ] } # Process a specific file based on the provided argument process-file = { cmd = "python process.py inputs/{{ filename }}.txt --output outputs/{{ filename }}.processed", args = [ "filename", ], inputs = [ "inputs/{{ filename }}.txt", ], outputs = [ "outputs/{{ filename }}.processed", ] } ``` When using template variables in inputs/outputs, Pixi expands the templates using the provided arguments or environment variables, and uses the resolved paths for caching decisions. This allows you to create generic tasks that can handle different files without duplicating task configurations: ```shell # First run processes the file and caches the result pixi run process-file data1 # Second run with the same argument uses the cached result pixi run process-file data1 # [cache hit] # Run with a different argument processes a different file pixi run process-file data2 ``` Note: if you want to debug the globs you can use the `--verbose` flag to see which files are selected. ```shell # shows info logs of all files that were selected by the globs pixi run -v start ``` ## Environment Variables You can set environment variables directly for a task, as well as by other means. See [the environment variable priority documentation](../../reference/environment_variables/#environment-variable-priority) for full details of ways to set environment variables, and how those ways interact with each other. Notes on environment variables in tasks: - Values set via `tasks..env` are interpreted by `deno_task_shell` when the task runs. Shell-style expansions like `env = { VAR = "$FOO" }` therefore work the same on all operating systems. - Templating is allowed in env variables, when you have something like `{ cmd="pytest", env={ BACKEND="{{ backend }}" }, args=[{arg="backend", default="numpy"}] }`. The arg `{{ backend }}` value is interpreted by the `backend` values passed in. Warning In older versions of Pixi, this priority was not well-defined, and there are a number of known deviations from the current priority which exist in some older versions: - `activation.scripts` used to take priority over `activation.env` - activation scripts of dependencies used to take priority over `activation.env` - outside environment variables used to override variables set in `task.env` If you previously relied on a certain priority which no longer applies, you may need to change your task definitions. For the specific case of overriding `task.env` with outside environment variables, this behavior can now be recreated using [task arguments](#task-arguments). For example, if you were previously using a setup like: pixi.toml ```toml [tasks] echo = { cmd = "echo $ARGUMENT", env = { ARGUMENT = "hello" } } ``` ```shell ARGUMENT=world pixi run echo ✨ Pixi task (echo in default): echo $ARGUMENT world ``` you can now recreate this behavior like: pixi.toml ```toml [tasks] echo = { cmd = "echo {{ ARGUMENT }}", args = [{"arg" = "ARGUMENT", "default" = "hello" }] } ``` ```shell pixi run echo world ✨ Pixi task (echo): echo world world ``` ## Clean environment You can make sure the environment of a task is "Pixi only". Here Pixi will only include the minimal required environment variables for your platform to run the command in. The environment will contain all variables set by the conda environment like `"CONDA_PREFIX"`. It will however include some default values from the shell, like: `"DISPLAY"`, `"LC_ALL"`, `"LC_TIME"`, `"LC_NUMERIC"`, `"LC_MEASUREMENT"`, `"SHELL"`, `"USER"`, `"USERNAME"`, `"LOGNAME"`, `"HOME"`, `"HOSTNAME"`,`"TMPDIR"`, `"XPC_SERVICE_NAME"`, `"XPC_FLAGS"` ```toml [tasks] clean_command = { cmd = "python run_in_isolated_env.py", clean-env = true } ``` This setting can also be set from the command line with `pixi run --clean-env TASK_NAME`. `clean-env` not supported on Windows On Windows it's hard to create a "clean environment" as `conda-forge` doesn't ship Windows compilers and Windows needs a lot of base variables. Making this feature not worthy of implementing as the amount of edge cases will make it unusable. ## Our task runner: deno_task_shell To support the different OS's (Windows, OSX and Linux), Pixi integrates a shell that can run on all of them. This is [`deno_task_shell`](https://deno.land/manual@v1.35.0/tools/task_runner#built-in-commands). The task shell is a limited implementation of a bourne-shell interface. Task command lines and the values of `tasks..env` are parsed and expanded by this shell. ### Built-in commands Next to running actual executable like `./myprogram`, `cmake` or `python` the shell has some built-in commands. - `cp`: Copies files. - `mv`: Moves files. - `rm`: Remove files or directories. Ex: `rm -rf [FILE]...` - Commonly used to recursively delete files or directories. - `mkdir`: Makes directories. Ex. `mkdir -p DIRECTORY...` - Commonly used to make a directory and all its parents with no error if it exists. - `pwd`: Prints the name of the current/working directory. - `sleep`: Delays for a specified amount of time. Ex. `sleep 1` to sleep for 1 second, `sleep 0.5` to sleep for half a second, or `sleep 1m` to sleep a minute - `echo`: Displays a line of text. - `cat`: Concatenates files and outputs them on stdout. When no arguments are provided, it reads and outputs stdin. - `exit`: Causes the shell to exit. - `unset`: Unsets environment variables. - `xargs`: Builds arguments from stdin and executes a command. ### Syntax - **Boolean list:** use `&&` or `||` to separate two commands. - `&&`: if the command before `&&` succeeds continue with the next command. - `||`: if the command before `||` fails continue with the next command. - **Sequential lists:** use `;` to run two commands without checking if the first command failed or succeeded. - **Environment variables:** - Set env variable using: `export ENV_VAR=value` - Use env variable using: `$ENV_VAR` - unset env variable using `unset ENV_VAR` - **Shell variables:** Shell variables are similar to environment variables, but won't be exported to spawned commands. - Set them: `VAR=value` - use them: `VAR=value && echo $VAR` - **Pipelines:** Use the stdout output of a command into the stdin a following command - `|`: `echo Hello | python receiving_app.py` - `|&`: use this to also get the stderr as input. - **Command substitution:** `$()` to use the output of a command as input for another command. - `python main.py $(git rev-parse HEAD)` - **Negate exit code:** `!` before any command will negate the exit code from 1 to 0 or visa-versa. - **Redirects:** `>` to redirect the stdout to a file. - `echo hello > file.txt` will put `hello` in `file.txt` and overwrite existing text. - `python main.py 2> file.txt` will put the `stderr` output in `file.txt`. - `python main.py &> file.txt` will put the `stderr` **and** `stdout` in `file.txt`. - `echo hello >> file.txt` will append `hello` to the existing `file.txt`. - **Glob expansion:** `*` to expand all options. - `echo *.py` will echo all filenames that end with `.py` - `echo **/*.py` will echo all filenames that end with `.py` in this directory and all descendant directories. - `echo data[0-9].csv` will echo all filenames that have a single number after `data` and before `.csv` More info in [`deno_task_shell` documentation](https://deno.land/manual@v1.35.0/tools/task_runner#task-runner). Pixi is a tool to manage environments. This document explains what an environment looks like and how to use it. ## Activation An environment is nothing more than a set of files that are installed into a certain location, that somewhat mimics a global system install. You need to activate the environment to use it. In the most simple sense that mean adding the `bin` directory of the environment to the `PATH` variable. But there is more to it in a conda environment, as it also sets some environment variables. To do the activation we have multiple options: - `pixi shell`: start a shell with the environment activated. - `pixi shell-hook`: print the command to activate the environment in your current shell. - `pixi run` run a command or [task](../advanced_tasks/) in the default environment. Where the `run` command is special as it runs its own cross-platform shell and has the ability to run tasks. More information about tasks can be found in the [tasks documentation](../advanced_tasks/). Using the `pixi shell-hook` in Pixi you would get the following output: ```shell export PATH="/home/user/development/pixi/.pixi/envs/default/bin:/home/user/.local/bin:/home/user/bin:/usr/local/bin:/usr/local/sbin:/usr/bin:/home/user/.pixi/bin" export CONDA_PREFIX="/home/user/development/pixi/.pixi/envs/default" export PIXI_PROJECT_NAME="pixi" export PIXI_PROJECT_ROOT="/home/user/development/pixi" export PIXI_PROJECT_VERSION="0.12.0" export PIXI_PROJECT_MANIFEST="/home/user/development/pixi/pixi.toml" export CONDA_DEFAULT_ENV="pixi" export PIXI_ENVIRONMENT_PLATFORMS="osx-64,linux-64,win-64,osx-arm64" export PIXI_ENVIRONMENT_NAME="default" export PIXI_PROMPT="(pixi) " . "/home/user/development/pixi/.pixi/envs/default/etc/conda/activate.d/activate-binutils_linux-64.sh" . "/home/user/development/pixi/.pixi/envs/default/etc/conda/activate.d/activate-gcc_linux-64.sh" . "/home/user/development/pixi/.pixi/envs/default/etc/conda/activate.d/activate-gfortran_linux-64.sh" . "/home/user/development/pixi/.pixi/envs/default/etc/conda/activate.d/activate-gxx_linux-64.sh" . "/home/user/development/pixi/.pixi/envs/default/etc/conda/activate.d/libglib_activate.sh" . "/home/user/development/pixi/.pixi/envs/default/etc/conda/activate.d/rust.sh" ``` It sets the `PATH` and some more environment variables. But more importantly it also runs activation scripts that are presented by the installed packages. An example of this would be the [`libglib_activate.sh`](https://github.com/conda-forge/glib-feedstock/blob/52ba1944dffdb2d882d824d6548325155b58819b/recipe/scripts/activate.sh) script. Thus, just adding the `bin` directory to the `PATH` is not enough. Shell used for activation: - On Windows, Pixi executes activation under `cmd.exe`. - On Linux and macOS, Pixi executes activation under `bash`. This affects both `[activation.env]` and `activation.scripts`: they are applied by the platform's shell during activation, before any task runs. You can modify the activation with the `activation` table in the manifest, you can add more activation scripts or inject environment variables into the activation scripts. ```toml [activation.env] # Python users often set: PYTHONIOENCODING = "utf-8" PYTHONNOUSERSITE = "1" # R users often set: PIXI_R_LIBS = "$CONDA_PREFIX/lib/R/library" R_LIBS = "$PIXI_R_LIBS" R_LIBS_USER = "$PIXI_R_LIBS" [target.unix.activation] # Use sh scripts on unix scripts = [ # Common in the ROS workspaces "install/setup.sh", # Want to add some personal scripts to the activation: "activation.sh", ] # Use batch scripts on windows [target.win.activation] scripts = ["install/setup.bat"] ``` Find the reference for the `activation` table [here](../../reference/pixi_manifest/#the-activation-table). ## Traditional `conda activate`-like activation If you prefer to use the traditional `conda activate`-like activation, you can use the `pixi shell-hook` command. ```shell $ which python python not found $ eval "$(pixi shell-hook)" $ (default) which python /path/to/project/.pixi/envs/default/bin/python ``` For example, with `bash` and `zsh` you can use the following command: ```shell eval "$(pixi shell-hook)" ``` Custom activation function With the `--manifest-path` option you can also specify which environment to activate. If you want to add a `bash` function to your `~/.bashrc` that will activate the environment, you can use the following command: ```shell function pixi_activate() { # default to current directory if no path is given local manifest_path="${1:-.}" eval "$(pixi shell-hook --manifest-path $manifest_path)" } ``` After adding this function to your `~/.bashrc`/`~/.zshrc`, you can activate the environment by running: With fish, you can also evaluate the output of `pixi shell-hook`: ```fish pixi shell-hook | source ``` Or, if you want to add a function to your `~/.config/fish/config.fish`: ```fish function pixi_activate # default to current directory if no path is given set -l manifest_path $argv[1] test -z "$manifest_path"; and set manifest_path "." pixi shell-hook --manifest-path "$manifest_path" | source end ``` After adding this function to your `~/.config/fish/config.fish`, you can activate the environment by running: ```shell pixi_activate # or with a specific manifest pixi_activate ~/projects/my_project ``` Using direnv See our [direnv page](../../integration/third_party/direnv/) on how to leverage `pixi shell-hook` to integrate with direnv. ## Structure All Pixi environments are by default located in the `.pixi/envs` directory of the workspace. This keeps your machine and your workspace clean and isolated from each other, and makes it easy to clean up after a workspace is done. While this structure is generally recommended, environments can also be stored outside of workspace directories by enabling [detached environments](../../reference/pixi_configuration/#detached-environments). If you look at the `.pixi/envs` directory, you will see a directory for each environment, the `default` being the one that is normally used, if you specify a custom environment the name you specified will be used. ```shell .pixi └── envs β”œβ”€β”€ cuda β”‚ β”œβ”€β”€ bin β”‚ β”œβ”€β”€ conda-meta β”‚ β”œβ”€β”€ etc β”‚ β”œβ”€β”€ include β”‚ β”œβ”€β”€ lib β”‚ ... └── default β”œβ”€β”€ bin β”œβ”€β”€ conda-meta β”œβ”€β”€ etc β”œβ”€β”€ include β”œβ”€β”€ lib ... ``` These directories are conda environments, and you can use them as such, but you cannot manually edit them, this should always go through the `pixi.toml`. Pixi will always make sure the environment is in sync with the `pixi.lock` file. If this is not the case then all the commands that use the environment will automatically it, e.g. `pixi run`, `pixi shell`. ### Environment Metadata On environment creation, Pixi will add a small file containing some metadata. This file is called `pixi` and is located in the `conda-meta` folder of the environment. This file contains the following information: - `manifest_path`: The path to the manifest file that describes the workspace used to create this environment - `environment_name`: The name of the environment - `pixi_version`: The version of Pixi that was used to create this environment - `environment_lock_file_hash`: The hash of the `pixi.lock` file that was used to create this environment ```json { "manifest_path": "/home/user/dev/pixi/pixi.toml", "environment_name": "default", "pixi_version": "0.34.0", "environment_lock_file_hash": "4f36ee620f10329d" } ``` The `environment_lock_file_hash` is used to check if the environment is in sync with the `pixi.lock` file. If the hash of the `pixi.lock` file is different from the hash in the `pixi` file, Pixi will update the environment. This is used to speedup activation, in order to trigger a full revalidation and installation use `pixi install` or `pixi reinstall`. A broken environment would typically not be found with a hash comparison, but a revalidation would reinstall the environment. By default, all lock file modifying commands will always trigger a revalidation, as does `pixi install`. ### Cleaning up If you want to clean up the environments, you can simply delete the `.pixi/envs` directory, and Pixi will recreate the environments when needed. ```shell pixi clean # or manually: rm -rf .pixi/envs # or per environment: pixi clean --environment cuda # or manually: rm -rf .pixi/envs/default rm -rf .pixi/envs/cuda ``` ## Solving environments When you run a command that uses the environment, Pixi will check if it is in sync with the `pixi.lock` file. If it is not, Pixi will solve the environment and update it. This means that Pixi will retrieve the best set of packages for the dependency requirements that you specified in the `pixi.toml` and will put the output of the solve step into the `pixi.lock` file. Solving is a mathematical problem and can take some time, but we take pride in the way we solve environments, and we are confident that we can solve yours in a reasonable time. If you want to learn more about the solving process, you can read these: - [Rattler(conda) resolver blog](https://prefix.dev/blog/the_new_rattler_resolver) - [UV(PyPI) resolver blog](https://astral.sh/blog/uv-unified-python-packaging) Pixi solves both the `conda` and `PyPI` dependencies, where the `PyPI` dependencies use the conda packages as a base, so you can be sure that the packages are compatible with each other. These solvers are split between the [`rattler`](https://github.com/conda/rattler) and [`uv`](https://github.com/astral-sh/uv) library, these control the heavy lifting of the solving process, which is executed by our custom SAT solver: [`resolvo`](https://github.com/mamba-org/resolvo). `resolvo` is able to solve multiple ecosystem like `conda` and `PyPI`. It implements the lazy solving process for `PyPI` packages, which means that it only downloads the metadata of the packages that are needed to solve the environment. It also supports the `conda` way of solving, which means that it downloads the metadata of all the packages at once and then solves in one go. For the `[pypi-dependencies]`, `uv` implements `sdist` building to retrieve the metadata of the packages, and `wheel` building to install the packages. For this building step, `pixi` requires to first install `python` in the (conda)`[dependencies]` section of the `pixi.toml` file. This will always be slower than the pure conda solves. So for the best Pixi experience you should stay within the `[dependencies]` section of the `pixi.toml` file. ## Caching packages Pixi caches all previously downloaded packages in a cache folder. This cache folder is shared between all Pixi workspaces and globally installed tools. Normally the location would be the following platform-specific default cache folder: - Linux: `$XDG_CACHE_HOME/rattler` or `$HOME/.cache/rattler` - macOS: `$HOME/Library/Caches/rattler` - Windows: `%LOCALAPPDATA%\rattler` This location is configurable by setting the `PIXI_CACHE_DIR` or `RATTLER_CACHE_DIR` environment variable. When you want to clean the cache, you can simply delete the cache directory, and Pixi will re-create the cache when needed. The cache contains multiple folders concerning different caches from within pixi. - `pkgs`: Contains the downloaded/unpacked `conda` packages. - `repodata`: Contains the `conda` repodata cache. - `uv-cache`: Contains the `uv` cache. This includes multiple caches, e.g. `built-wheels` `wheels` `archives` - `http-cache`: Contains the `conda-pypi` mapping cache. ### De-duplication When Pixi installs packages into an environment, it does not copy files from the cache. Instead, it creates **hard links** (or **reflinks** on file systems that support copy-on-write, such as APFS on macOS and btrfs/XFS on Linux). This means every environment that uses the same version of a package shares the same on-disk files, so the package is effectively stored only once. For example, if three workspaces all depend on `numpy 1.26.4`, the individual files of that package exist once in the cache and are linked into each environment. This can save gigabytes of disk space, especially when you work with many environments or large packages like CUDA toolkits. Hard links vs reflinks - **Hard links** point multiple directory entries to the same data on disk. Modifying one link modifies all of them, but this is not an issue because Pixi environments are meant to be read-only. - **Reflinks** (copy-on-write links) behave like instant copies that only allocate new disk space when one side is modified. This makes them safer than hard links: if a process accidentally writes to a file in an environment, only that environment's copy is affected while the cached original and all other environments stay intact. On supported file systems Pixi prefers reflinks for this reason. - If neither hard links nor reflinks are available (e.g. when the cache and the workspace are on different mount points), Pixi falls back to copying files. > A lock file is the protector of the environments, and Pixi is the key to unlock it. ## What is a lock file? To answer this question, we first need to highlight the difference between the manifest and the lock file. The manifest lists the direct dependencies of your project. When you install your environment, this manifest goes through "dependency resolution": all the dependencies of your requested dependencies are found, et cetera all the way down. During the resolution process, it is ensured that resolved versions are compatible with each other. A lock file lists the exact dependencies that were resolved during this resolution process - the packages, their versions, and other metadata useful for package management. A lock file improves reproducibility through a relatively small file. Installers can create exactly the same environment without needing to manage the actual package contents itself. Do not edit the lock file A lock file is built for machines, and made human readable for easy inspection. It's not meant to be edited by hand. ## Lock files in Pixi Pixi - like many other modern package managers - has native support for lock files. This file is named `pixi.lock` . During the creation of the lock file, Pixi resolves the packages - for all environments and platforms listed in the manifest. This greatly increases the reproducibility of your project making it easy to use on different OSs or CPU architectures - in fact, for a lot of cases, sharing a lock file can be done instead of sharing a Docker container! This make recreating your local development environment in CI very easy. The Pixi lock file is also human readable, so you can take a look at which packages are listed without extra tools - as well as easily track changes to the file (don't make edits to it - you did read the warning block above right?). ## Lock file changes Many Pixi commands will create a lock file if one doesn't already exist, or update it if needed. For example, when you install a package, Pixi goes through the following process: 1. User requests a package to be installed 1. Dependency resolution 1. Generating and writing of lock file 1. Install resulting packages Additionally - Pixi ensures that the lock file remains in sync with both your manifest, as well as your installed environment. If it detects that they aren't in sync, it will regenerate the lock file. You can read more about this in the [Lock file satisfiability](#lock-file-satisfiability) section. The following commands will check and automatically update the lock file if needed: - [`pixi install`](../../reference/cli/pixi/install/) - [`pixi run`](../../reference/cli/pixi/run/) - [`pixi shell`](../../reference/cli/pixi/shell/) - [`pixi shell-hook`](../../reference/cli/pixi/shell-hook/) - [`pixi tree`](../../reference/cli/pixi/tree/) - [`pixi list`](../../reference/cli/pixi/list/) - [`pixi add`](../../reference/cli/pixi/add/) - [`pixi remove`](../../reference/cli/pixi/remove/) If you want to remove the lock file, you can simply delete it - ready for it to be generated again with the latest package versions when one of the above commands are run. You may want to have more control over the interplay between the manifest, the lock file, and the created environment. There are additional command line options to help with this: - `--frozen`: install the environment as defined in the lock file, doesn't update `pixi.lock` if it isn't up-to-date with [manifest file](../../reference/pixi_manifest/). It can also be controlled by the `PIXI_FROZEN` environment variable (example: `PIXI_FROZEN=true`). - `--locked`: only install if the `pixi.lock` is up-to-date with the [manifest file](../../reference/pixi_manifest/). It can also be controlled by the `PIXI_LOCKED` environment variable (example: `PIXI_LOCKED=true`). Conflicts with `--frozen`. ## Committing your lockfile Reproducibility is very important in a range of projects (e.g., deploying software services, working on research projects, data analysis). Reproducibility of environments helps with reproducibility of results - it ensures your developers, and deployment machines are all using the same packages. Hesitant to commit the lockfile? Consider this: - Docker images for reproducible environments are **always larger**. - Git works well with YAML. - It serves as a cache for the dependency resolution, giving **faster installation and CI**. - You don't need it... until you do. Deleting or ignoring is easier than recreating one under pressure. There is, however, a class of projects where one does not simply just commit the lockfile - there are additional considerations at play. Namely, this is when developing *libraries*. ______________________________________________________________________ Libraries have an evolving nature and need to be tested against environments covering a wide range of package versions to ensure compatibility. This includes an environment with the latest available versions of packages. ### Additional considerations for libraries If you commit the lock file in your library project, you will want to also consider the following: - **Upgrading the lockfile:** How often do you want to upgrade the lockfile used by your developers? Do you want to do these upgrades in the main repo history? Do you want to manage this lockfile via (e.g.,) [the Renovate Bot](https://docs.renovatebot.com/modules/manager/pixi/) or via a custom CI job? - **Custom CI workflow to test against latest versions:** Do you want to have a workflow to test against the latest dependency versions? If so - you likely want to have the following CI workflow on a cron schedule: - Remove the `pixi.lock` before running the `setup-pixi` action - Run your tests - If the tests fail: - See how the generated `pixi.lock` differs from that in `main` by using `pixi-diff` and `pixi-diff-to-markdown` - Automatically file an issue so that its tracked in the project repo You can see how these considerations above have been explored by the following projects: - Scipy (being explored - will update with PR link once available. [Issue](https://github.com/scipy/scipy/issues/23637)) ______________________________________________________________________ If you decide in the end not to commit the lock file, forgoing its benefits, you may want to use an action such as [Parcels-code/pixi-lock](https://github.com/parcels-code/pixi-lock) to cache generated lock files and speed up your CI. ### File structure The Pixi lock file is structured into two parts. - The environments that are used in the workspace - listing the packages contained. e.g.: ```yaml environments: default: channels: - url: https://conda.anaconda.org/conda-forge/ packages: linux-64: ... - conda: https://conda.anaconda.org/conda-forge/linux-64/python-3.12.2-hab00c5b_0_cpython.conda ... osx-64: ... - conda: https://conda.anaconda.org/conda-forge/osx-64/python-3.12.2-h9f0c242_0_cpython.conda ... ``` - The definition of the packages themselves. e.g.: ```yaml - kind: conda name: python version: 3.12.2 build: h9f0c242_0_cpython subdir: osx-64 url: https://conda.anaconda.org/conda-forge/osx-64/python-3.12.2-h9f0c242_0_cpython.conda sha256: 7647ac06c3798a182a4bcb1ff58864f1ef81eb3acea6971295304c23e43252fb md5: 0179b8007ba008cf5bec11f3b3853902 depends: - bzip2 >=1.0.8,<2.0a0 - libexpat >=2.5.0,<3.0a0 - libffi >=3.4,<4.0a0 - libsqlite >=3.45.1,<4.0a0 - libzlib >=1.2.13,<1.3.0a0 - ncurses >=6.4,<7.0a0 - openssl >=3.2.1,<4.0a0 - readline >=8.2,<9.0a0 - tk >=8.6.13,<8.7.0a0 - tzdata - xz >=5.2.6,<6.0a0 constrains: - python_abi 3.12.* *_cp312 license: Python-2.0 size: 14596811 timestamp: 1708118065292 ``` ### The version of the lock file The lock file also has a version number, this is to ensure that the lock file is compatible with the local version of `pixi`. ```yaml version: 6 ``` Pixi is backward compatible with the lock file, but not forward compatible. This means that you can use an older lock file with a newer version of `pixi`, but not the other way around. ## Lock file satisfiability The lock file is a description of the environment, and it should always be satisfiable. Satisfiable means that the given manifest file and the created environment are in sync with the lock file. If the lock file is not satisfiable, Pixi will generate a new lock file automatically. Steps to check if the lock file is satisfiable: - All `environments` in the manifest file are in the lock file - All `channels` in the manifest file are in the lock file - All `packages` in the manifest file are in the lock file, and the versions in the lock file are compatible with the requirements in the manifest file, for both `conda` and `pypi` packages. - Conda packages use a `matchspec` which can match on all the information we store in the lock file, even `timestamp`, `subdir` and `license`. - If `pypi-dependencies` are added, all `conda` package that are python packages in the lock file have a `purls` field. - All hashes for the `pypi` editable packages are correct. - There is only a single entry for every package in the lock file. If you want to get more details checkout the [actual code](https://github.com/prefix-dev/pixi/blob/main/crates/pixi_core/src/lock_file/satisfiability/mod.rs) as this is a simplification of the actual code. ### Motivating Example There are multiple scenarios where multiple environments are useful. - **Testing of multiple package versions**, e.g. `py39` and `py310` or polars `0.12` and `0.13`. - **Smaller single tool environments**, e.g. `lint` or `docs`. - **Large developer environments**, that combine all the smaller environments, e.g. `dev`. - **Strict supersets of environments**, e.g. `prod` and `test-prod` where `test-prod` is a strict superset of `prod`. - **Multiple system requirements within one workspace**, e.g. a `cuda` environment and a `cpu` environment. - **And many more.** (Feel free to edit this document in our GitHub and add your use case.) This prepares `pixi` for use in large workspaces with multiple use-cases, multiple developers and different CI needs. ## Design Considerations There are a few things we wanted to keep in mind in the design: 1. **User-friendliness**: Pixi is a user focussed tool that goes beyond developers. The feature should have good error reporting and helpful documentation from the start. 1. **Keep it simple**: Not understanding the multiple environments feature shouldn't limit a user to use pixi. The feature should be "invisible" to the non-multi env use-cases. 1. **No Automatic Combinatorial**: To ensure the dependency resolution process remains manageable, the solution should avoid a combinatorial explosion of dependency sets. By making the environments user defined and not automatically inferred by testing a matrix of the features. 1. **Single environment Activation**: The design should allow only one environment to be active at any given time, simplifying the resolution process and preventing conflicts. 1. **Fixed lock files**: It's crucial to preserve fixed lock files for consistency and predictability. Solutions must ensure reliability not just for authors but also for end-users, particularly at the time of lock file creation. ### Feature & Environment Set Definitions Introduce environment sets into the `pixi.toml` this describes environments based on features. Introduce features into the `pixi.toml` that can describe parts of environments. As an environment goes beyond just `dependencies` the `feature` fields can be described by including the following fields: - `dependencies`: The conda package dependencies - `pypi-dependencies`: The pypi package dependencies - `system-requirements`: The system requirements of the environment - `activation`: The activation information for the environment - `platforms`: The platforms the environment can be run on. - `channels`: The channels used to create the environment. Adding the `priority` field to the channels to allow concatenation of channels instead of overwriting. - `target`: All the above features but also separated by targets. - `tasks`: Feature specific tasks, tasks in one environment are selected as default tasks for the environment. Default features ```toml [dependencies] # short for [feature.default.dependencies] python = "*" numpy = "==2.3" [pypi-dependencies] # short for [feature.default.pypi-dependencies] pandas = "*" [system-requirements] # short for [feature.default.system-requirements] libc = "2.33" [activation] # short for [feature.default.activation] scripts = ["activate.sh"] ``` Different dependencies per feature ```toml [feature.py39.dependencies] python = "~=3.9.0" [feature.py310.dependencies] python = "~=3.10.0" [feature.test.dependencies] pytest = "*" ``` Full set of environment modification in one feature ```toml [feature.cuda] dependencies = {cuda = "x.y.z", cudnn = "12.0"} pypi-dependencies = {torch = "1.9.0"} platforms = ["linux-64", "osx-arm64"] activation = {scripts = ["cuda_activation.sh"]} system-requirements = {cuda = "12"} # Channels concatenate using a priority instead of overwrite, so the default channels are still used. # Using the priority the concatenation is controlled, default is 0, the default channels are used last. # Highest priority comes first. channels = ["nvidia", {channel = "pytorch", priority = -1}] # Results in: ["nvidia", "conda-forge", "pytorch"] when the default is `conda-forge` tasks = { warmup = "python warmup.py" } target.osx-arm64 = {dependencies = {mlx = "x.y.z"}} ``` Define tasks as defaults of an environment ```toml [feature.test.tasks] test = "pytest" [environments] test = ["test"] # `pixi run test` == `pixi run --environment test test` ``` The environment definition should contain the following fields: - `features: Vec`: The features that are included in the environment set, which is also the default field in the environments. - `solve-group: String`: The solve group is used to group environments together at the solve stage. This is useful for environments that need to have the same dependencies but might extend them with additional dependencies. For instance when testing a production environment with additional test dependencies. Creating environments from features ```toml [environments] # implicit: default = ["default"] default = ["py39"] # implicit: default = ["py39", "default"] py310 = ["py310"] # implicit: py310 = ["py310", "default"] test = ["test"] # implicit: test = ["test", "default"] test39 = ["test", "py39"] # implicit: test39 = ["test", "py39", "default"] ``` Testing a production environment with additional dependencies ```toml [environments] # Creating a `prod` environment which is the minimal set of dependencies used for production. prod = {features = ["py39"], solve-group = "prod"} # Creating a `test_prod` environment which is the `prod` environment plus the `test` feature. test_prod = {features = ["py39", "test"], solve-group = "prod"} # Using the `solve-group` to solve the `prod` and `test_prod` environments together # Which makes sure the tested environment has the same version of the dependencies as the production environment. ``` Creating environments without including the default feature ```toml [dependencies] python = "*" numpy = "*" [feature.lint.dependencies] pre-commit = "*" [environments] # Create a custom environment which only has the `lint` feature (numpy isn't part of that env). lint = {features = ["lint"], no-default-feature = true} ``` ### lock file Structure Within the `pixi.lock` file, a package may now include an additional `environments` field, specifying the environment to which it belongs. To avoid duplication the packages `environments` field may contain multiple environments so the lock file is of minimal size. ```yaml - platform: linux-64 name: pre-commit version: 3.3.3 category: main environments: - dev - test - lint ...: - platform: linux-64 name: python version: 3.9.3 category: main environments: - dev - test - lint - py39 - default ...: ``` ### User Interface Environment Activation Users can manually activate the desired environment via command line or configuration. This approach guarantees a conflict-free environment by allowing only one feature set to be active at a time. For the user the cli would look like this: Default behavior ```shell ➜ pixi run python # Runs python in the `default` environment ``` Activating an specific environment ```shell ➜ pixi run -e test pytest ➜ pixi run --environment test pytest # Runs `pytest` in the `test` environment ``` Activating a shell in an environment ```shell ➜ pixi shell -e cuda pixi shell --environment cuda # Starts a shell in the `cuda` environment ``` Running any command in an environment ```shell ➜ pixi run -e test any_command # Runs any_command in the `test` environment which doesn't require to be predefined as a task. ``` ### Ambiguous Environment Selection It's possible to define tasks in multiple environments, in this case the user should be prompted to select the environment. Here is a simple example of a task only manifest: pixi.toml ```toml [workspace] name = "test_ambiguous_env" channels = [] platforms = ["linux-64", "win-64", "osx-64", "osx-arm64"] [tasks] default = "echo Default" ambi = "echo Ambi::Default" [feature.test.tasks] test = "echo Test" ambi = "echo Ambi::Test" [feature.dev.tasks] dev = "echo Dev" ambi = "echo Ambi::Dev" [environments] default = ["test", "dev"] test = ["test"] dev = ["dev"] ``` Trying to run the `ambi` task will prompt the user to select the environment. As it is available in all environments. Interactive selection of environments if task is in multiple environments ```shell ➜ pixi run ambi ? The task 'ambi' can be run in multiple environments. Please select an environment to run the task in: β€Ί ❯ default # selecting default test dev ✨ Pixi task (ambi in default): echo Ambi::Test Ambi::Test ``` As you can see it runs the task defined in the `feature.task` but it is run in the `default` environment. This happens because the `ambi` task is defined in the `test` feature, and it is overwritten in the default environment. So the `tasks.default` is now non-reachable from any environment. Some other results running in this example: ```shell ➜ pixi run --environment test ambi ✨ Pixi task (ambi in test): echo Ambi::Test Ambi::Test ➜ pixi run --environment dev ambi ✨ Pixi task (ambi in dev): echo Ambi::Dev Ambi::Dev # dev is run in the default environment ➜ pixi run dev ✨ Pixi task (dev in default): echo Dev Dev # dev is run in the dev environment ➜ pixi run -e dev dev ✨ Pixi task (dev in dev): echo Dev Dev ``` ## Initial write-up Initial write-up of the proposal: [GitHub Gist by 0xbe7a](https://gist.github.com/0xbe7a/bbf8a323409be466fe1ad77aa6dd5428) ## Real world example use cases Polarify test setup In `polarify` they want to test multiple versions combined with multiple versions of polars. This is currently done by using a matrix in GitHub actions. This can be replaced by using multiple environments. pixi.toml ```toml [workspace] name = "polarify" # ... channels = ["conda-forge"] platforms = ["linux-64", "osx-arm64", "osx-64", "win-64"] [tasks] postinstall = "pip install --no-build-isolation --no-deps --disable-pip-version-check -e ." [dependencies] python = ">=3.9" pip = "*" polars = ">=0.14.24,<0.21" [feature.py39.dependencies] python = "3.9.*" [feature.py310.dependencies] python = "3.10.*" [feature.py311.dependencies] python = "3.11.*" [feature.py312.dependencies] python = "3.12.*" [feature.pl017.dependencies] polars = "0.17.*" [feature.pl018.dependencies] polars = "0.18.*" [feature.pl019.dependencies] polars = "0.19.*" [feature.pl020.dependencies] polars = "0.20.*" [feature.test.dependencies] pytest = "*" pytest-md = "*" pytest-emoji = "*" hypothesis = "*" [feature.test.tasks] test = "pytest" [feature.lint.dependencies] pre-commit = "*" [feature.lint.tasks] lint = "pre-commit run --all" [environments] pl017 = ["pl017", "py39", "test"] pl018 = ["pl018", "py39", "test"] pl019 = ["pl019", "py39", "test"] pl020 = ["pl020", "py39", "test"] py39 = ["py39", "test"] py310 = ["py310", "test"] py311 = ["py311", "test"] py312 = ["py312", "test"] ``` .github/workflows/test.yml ```yaml jobs: tests-per-env: runs-on: ubuntu-latest strategy: matrix: environment: [py311, py312] steps: - uses: actions/checkout@v4 - uses: prefix-dev/setup-pixi@v0.5.1 with: environments: ${{ matrix.environment }} - name: Run tasks run: | pixi run --environment ${{ matrix.environment }} test tests-with-multiple-envs: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: prefix-dev/setup-pixi@v0.5.1 with: environments: pl017 pl018 - run: | pixi run -e pl017 test pixi run -e pl018 test ``` Test vs Production example This is an example of a workspace that has a `test` feature and `prod` environment. The `prod` environment is a production environment that contains the run dependencies. The `test` feature is a set of dependencies and tasks that we want to put on top of the previously solved `prod` environment. This is a common use case where we want to test the production environment with additional dependencies. pixi.toml ```toml [workspace] name = "my-app" # ... channels = ["conda-forge"] platforms = ["osx-arm64", "linux-64"] [tasks] postinstall-e = "pip install --no-build-isolation --no-deps --disable-pip-version-check -e ." postinstall = "pip install --no-build-isolation --no-deps --disable-pip-version-check ." dev = "uvicorn my_app.app:main --reload" serve = "uvicorn my_app.app:main" [dependencies] python = ">=3.12" pip = "*" pydantic = ">=2" fastapi = ">=0.105.0" sqlalchemy = ">=2,<3" uvicorn = "*" aiofiles = "*" [feature.test.dependencies] pytest = "*" pytest-md = "*" pytest-asyncio = "*" [feature.test.tasks] test = "pytest --md=report.md" [environments] # both default and prod will have exactly the same dependency versions when they share a dependency default = {features = ["test"], solve-group = "prod-group"} prod = {features = [], solve-group = "prod-group"} ``` In ci you would run the following commands: ```shell pixi run postinstall-e && pixi run test ``` Locally you would run the following command: ```shell pixi run postinstall-e && pixi run dev ``` Then in a Dockerfile you would run the following command: Dockerfile ```dockerfile FROM ghcr.io/prefix-dev/pixi:latest # this doesn't exist yet WORKDIR /app COPY . . RUN pixi run --environment prod postinstall EXPOSE 8080 CMD ["/usr/local/bin/pixi", "run", "--environment", "prod", "serve"] ``` Multiple machines from one workspace This is an example for an ML workspace that should be executable on a machine that supports `cuda` and `mlx`. It should also be executable on machines that don't support `cuda` or `mlx`, we use the `cpu` feature for this. pixi.toml ```toml [workspace] name = "my-ml-workspace" description = "A workspace that does ML stuff" authors = ["Your Name "] channels = ["conda-forge", "pytorch"] # All platforms that are supported by the workspace as the features will take the intersection of the platforms defined there. platforms = ["win-64", "linux-64", "osx-64", "osx-arm64"] [tasks] train-model = "python train.py" evaluate-model = "python test.py" [dependencies] python = "3.11.*" pytorch = {version = ">=2.0.1", channel = "pytorch"} torchvision = {version = ">=0.15", channel = "pytorch"} polars = ">=0.20,<0.21" matplotlib-base = ">=3.8.2,<3.9" ipykernel = ">=6.28.0,<6.29" [feature.cuda] platforms = ["win-64", "linux-64"] channels = ["nvidia", {channel = "pytorch", priority = -1}] system-requirements = {cuda = "12.1"} [feature.cuda.tasks] train-model = "python train.py --cuda" evaluate-model = "python test.py --cuda" [feature.cuda.dependencies] pytorch-cuda = {version = "12.1.*", channel = "pytorch"} [feature.mlx] platforms = ["osx-arm64"] # MLX is only available on macOS >=13.5 (>14.0 is recommended) system-requirements = {macos = "13.5"} [feature.mlx.tasks] train-model = "python train.py --mlx" evaluate-model = "python test.py --mlx" [feature.mlx.dependencies] mlx = ">=0.16.0,<0.17.0" [feature.cpu] platforms = ["win-64", "linux-64", "osx-64", "osx-arm64"] [environments] cuda = ["cuda"] mlx = ["mlx"] default = ["cpu"] ``` Executing on a cuda machine ```shell pixi run train-model --environment cuda # will execute `python train.py --cuda` # fails if not on linux-64 or win-64 with cuda 12.1 ``` Executing with mlx ```shell pixi run train-model --environment mlx # will execute `python train.py --mlx` # fails if not on osx-arm64 ``` Executing on a machine without cuda or mlx ```shell pixi run train-model ``` [Pixi's vision](../../misc/vision/) includes being supported on all major platforms. Sometimes that needs some extra configuration to work well. On this page, you will learn what you can configure to align better with the platform you are making your application for. Here is an example manifest file that highlights some of the features: pixi.toml ```toml [workspace] # Default workspace info.... # A list of platforms you are supporting with your package. platforms = ["win-64", "linux-64", "osx-64", "osx-arm64"] [dependencies] python = ">=3.8" [target.win-64.dependencies] # Overwrite the needed python version only on win-64 python = "3.7" [activation] scripts = ["setup.sh"] [target.win-64.activation] # Overwrite activation scripts only for windows scripts = ["setup.bat"] ``` pyproject.toml ```toml [tool.pixi.workspace] # Default workspace info.... # A list of platforms you are supporting with your package. platforms = ["win-64", "linux-64", "osx-64", "osx-arm64"] [tool.pixi.dependencies] python = ">=3.8" [tool.pixi.target.win-64.dependencies] # Overwrite the needed python version only on win-64 python = "~=3.7.0" [tool.pixi.activation] scripts = ["setup.sh"] [tool.pixi.target.win-64.activation] # Overwrite activation scripts only for windows scripts = ["setup.bat"] ``` ## Platform definition The `workspace.platforms` defines which platforms your workspace supports. When multiple platforms are defined, Pixi determines which dependencies to install for each platform individually. All of this is stored in a lock file. Running `pixi install` on a platform that is not configured will warn the user that it is not setup for that platform: ```shell ❯ pixi install WARN Not installing dependency for (default) on current platform: (osx-arm64) as it is not part of this project's supported platforms. ``` ## Target specifier With the target specifier, you can overwrite the original configuration specifically for a single platform. If you are targeting a specific platform in your target specifier that was not specified in your `workspace.platforms` then Pixi will throw an error. ### Dependencies It might happen that you want to install a certain dependency only on a specific platform, or you might want to use a different version on different platforms. pixi.toml ```toml [dependencies] python = ">=3.8" [target.win-64.dependencies] msmpi = "*" python = "3.8" ``` In the above example, we specify that we depend on `msmpi` only on Windows. We also specifically want `python` on `3.8` when installing on Windows. This will overwrite the dependencies from the generic set of dependencies. This will not touch any of the other platforms. You can use pixi's cli to add these dependencies to the manifest file. ```shell pixi add --platform win-64 posix ``` This also works for the `host` and `build` dependencies. ```bash pixi add --host --platform win-64 posix pixi add --build --platform osx-64 clang ``` Which results in this. pixi.toml ```toml [target.win-64.host-dependencies] posix = "1.0.0.*" [target.osx-64.build-dependencies] clang = "16.0.6.*" ``` ### Activation Pixi's vision is to enable completely cross-platform workspaces, but you often need to run tools that are not built by your projects. Generated activation scripts are often in this category, default scripts in unix are `bash` and for windows they are `bat` To deal with this, you can define your activation scripts using the target definition. pixi.toml ```toml [activation] scripts = ["setup.sh", "local_setup.bash"] [target.win-64.activation] scripts = ["setup.bat", "local_setup.bat"] ``` When this workspace is used on `win-64` it will only execute the target scripts not the scripts specified in the default `activation.scripts` **System requirements** tell Pixi the system specifications needed to install and run your environment. They ensure that the dependencies match the operating system and hardware of your machine. Think of it like this: You're defining what "kind of machines" your environment can run on. ```toml [system-requirements] linux = "4.18" libc = { family = "glibc", version = "2.28" } cuda = "12" macos = "13.0" ``` This results in an environment that can run on: - Linux with kernel version `4.18` - GNU C Library (glibc) version `2.28` - CUDA version `12` - macOS version `13.0` When resolving dependencies, Pixi combines: - The default requirements for the `platforms`. - Any custom requirements you've added through the `[system-requirements]` table. The root-level `[system-requirements]` table applies to the [default feature](../multi_environment/). This means it affects all environments that include the default feature (which is the default behavior unless `no-default-feature = true` is set). This way, Pixi guarantees your environment is consistent and compatible with your machine. System requirements are added as [virtual packages](https://conda.io/projects/conda/en/latest/user-guide/tasks/manage-virtual.html). Virtual packages are special packages (like `__linux`, `__cuda`, `__glibc`) that don't contain any files. They simply declare what features are available on the system, and the solver uses them to filter out incompatible packages. Need to support multiple types of systems that don't share the same specifications? You can define `system-requirements` for different `features` in your workspace. For example, if you have a feature that requires CUDA and another that does not, you can specify the system requirements for each feature separately. Check the example [below](#setting-system-requirements-environment-specific) for more details. ## Maximum or Minimum System Requirements The system requirements don't specify a maximum or minimum version. They specify the version that can be expected on the host system. It's up to the dependency resolver to determine if the system meets the requirements based on the versions available. e.g.: - a package can require `__cuda >= 12` and the system can have `12.1`, `12.6`, or any higher version. - a package can require `__cuda <= 12` and the system can have `12.0.0`, `11`, or any lower version. Most of the time, packages will specify the minimum version (`>=`) it requires. So we often say that the `system-requirements` define the minimum version of the system specifications. For example [`cuda-version-12.9-h4f385c5_3.conda`](https://conda-metadata-app.streamlit.app/?q=conda-forge%2Fnoarch%2Fcuda-version-12.9-h4f385c5_3.conda) contains the following package constraints: ```text cudatoolkit 12.9|12.9.* __cuda >=12 ``` ## Default System Requirements The following configurations outline the default system requirements for different operating systems: ```toml # Default system requirements for Linux [system-requirements] linux = "4.18" libc = { family = "glibc", version = "2.28" } ``` Windows currently has no minimal system requirements defined. If your workspace requires specific Windows configurations, you should define them accordingly. ```toml # Default system requirements for macOS [system-requirements] macos = "13.0" ``` ```toml # Default system requirements for macOS ARM64 [system-requirements] macos = "13.0" ``` ## Customizing System Requirements You only need to define system requirements if your environment necessitates a different set from the defaults. This is common when installing environments on older or newer versions of operating systems. ### Adjusting for Older Systems If you're encountering an error like: ```bash Γ— The current system has a mismatching virtual package. The workspace requires '__linux' to be at least version '4.18' but the system has version '4.12.14' ``` This indicates that the environment's system requirements are higher than your current system's specifications. To resolve this, you can lower the system requirements in your configuration: ```toml [system-requirements] linux = "4.12.14" ``` This adjustment informs the dependency resolver to accommodate the older system version. ### Using CUDA in pixi To utilize CUDA in your environment, you must specify the desired CUDA version in the system-requirements table. This ensures that CUDA is recognized and appropriately locked into the lock file if necessary. Example Configuration ```toml [system-requirements] cuda = "12" # Replace "12" with the specific CUDA version you intend to use ``` 1. Can `system-requirements` enforce a specific CUDA runtime version? - No. The `system-requirements` field is used to specify the supported CUDA version based on the host’s NVIDIA driver API. Adding this field ensures that packages depending on `__cuda >= {version}` are resolved correctly. ### Setting System Requirements environment specific This can be set per `feature` in the `the manifest` file. ```toml [feature.cuda.system-requirements] cuda = "12" [environments] cuda = ["cuda"] ``` ### Available Override Options In certain scenarios, you might need to override the system requirements detected on your machine. This can be particularly useful when working on systems that do not meet the environment's default requirements. You can override virtual packages by setting the following environment variables: - `CONDA_OVERRIDE_CUDA` - Description: Sets the CUDA version. - Usage Example: `CONDA_OVERRIDE_CUDA=11` - `CONDA_OVERRIDE_GLIBC` - Description: Sets the glibc version. - Usage Example: `CONDA_OVERRIDE_GLIBC=2.28` - `CONDA_OVERRIDE_OSX` - Description: Sets the macOS version. - Usage Example: `CONDA_OVERRIDE_OSX=13.0` ## Additional Resources For more detailed information on managing `virtual packages` and overriding system requirements, refer to the [Conda Documentation](https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-virtual.html). Pixi is built on top of both the conda and PyPI ecosystems. **Conda** is a cross-platform, cross-language package ecosystem that allows users to install packages and manage environments. It is widely used in the data science and machine learning community, but it is also used in other fields. Its power comes from the fact that it always installs binary packages, meaning that it doesn’t need to compile anything. This makes the ecosystem very fast and easy to use. **PyPI** is the Python Package Index, which is the main package index for Python packages. It is a much larger ecosystem than conda, especially because the barrier to entry for uploading packages is lower. This means that there are a lot of packages available, but it also means that the quality of the packages is not always as high as in the conda ecosystem. Pixi can install packages from **both** **ecosystems**, but it uses a **conda-first approach**. The simplified process is as follows: 1. Resolve the conda dependencies. 1. Map the conda packages to PyPI packages. 1. Resolve the remaining PyPI dependencies. ## Tool Comparison Here is a non-exhaustive comparison of the features of conda and PyPI ecosystems. | Feature | Conda | PyPI | | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Package format | Binary | Source & Binary (wheel) | | Package managers | [`conda`](https://github.com/conda/conda), [`mamba`](https://github.com/mamba-org/mamba), [`micromamba`](https://github.com/mamba-org/mamba), [`pixi`](https://github.com/prefix-dev/pixi) | [`pip`](https://github.com/pypa/pip), [`poetry`](https://github.com/python-poetry/poetry), [`uv`](https://github.com/astral-sh/uv), [`pdm`](https://github.com/pdm-project/pdm), [`hatch`](https://github.com/pypa/hatch), [`rye`](https://github.com/astral-sh/rye), [`pixi`](https://github.com/prefix-dev/pixi) | | Environment management | [`conda`](https://github.com/conda/conda), [`mamba`](https://github.com/mamba-org/mamba), [`micromamba`](https://github.com/mamba-org/mamba), [`pixi`](https://github.com/prefix-dev/pixi) | [`venv`](https://docs.python.org/3/library/venv.html), [`virtualenv`](https://virtualenv.pypa.io/en/latest/), [`pipenv`](https://pipenv.pypa.io/en/latest/), [`pyenv`](https://github.com/pyenv/pyenv), [`uv`](https://github.com/astral-sh/uv), [`poetry`](https://github.com/python-poetry/poetry), [`pixi`](https://github.com/prefix-dev/pixi) | | Package building | [`conda-build`](https://github.com/conda/conda-build), [`pixi`](https://github.com/prefix-dev/pixi) | [`setuptools`](https://github.com/pypa/setuptools), [`poetry`](https://github.com/python-poetry/poetry), [`flit`](https://github.com/pypa/flit), [`hatch`](https://github.com/pypa/hatch), [`uv`](https://github.com/astral-sh/uv), [`rye`](https://github.com/astral-sh/rye) | | Package index | [`conda-forge`](https://prefix.dev/channels/conda-forge), [`bioconda`](https://prefix.dev/channels/bioconda), and more | [pypi.org](https://pypi.org) | ## `uv` by Astral Pixi uses the [`uv`](https://github.com/astral-sh/uv) library to handle PyPI packages. Pixi doesn't install `uv` (the tool) itself: because both tools are built in Rust, it is used as a library. We're extremely grateful to the [Astral](https://astral.sh) team for their work on `uv`, which is a great library that allows us to handle PyPI packages in a much better way than before. Initially, next to `pixi` we were building a library called `rip` which had the same goals as `uv`, but we decided to switch to `uv` because it quickly became a more mature library, and it has a lot of features that we need. - [Initial blog post about announcing `rip`](https://prefix.dev/blog/pypi_support_in_pixi) - [Blog post to announce the switch to `uv`](https://prefix.dev/blog/uv_in_pixi) ## Solvers Because Pixi supports both ecosystems, it currently needs two different solvers to handle the dependencies. - The [`resolvo`](https://github.com/prefix-dev/resolvo) library is used to solve the conda dependencies. Implemented in [`rattler`](https://github.com/conda/rattler). - The [`PubGrub`](https://github.com/pubgrub-rs/pubgrub) library is used to solve the PyPI dependencies. Implemented in [`uv`](https://github.com/astral-sh/uv). Note The holy grail of Pixi is to have a single solver that can handle both ecosystems. Because resolvo is written to support both ecosystems, it is possible to use it for PyPI packages as well, but this is not yet implemented. Because PyPI packages need a base environment to install into, we need to use the conda-first approach, which means that we first solve the conda dependencies, then the PyPI dependencies. Pixi first runs the conda (`rattler`) solver, which will resolve the conda dependencies. Then it maps the conda packages to PyPI packages, using [`parselmouth`](https://github.com/prefix-dev/parselmouth). Then it runs the PyPI (`uv`) solver, which will resolve the remaining PyPI dependencies. The consequence is that Pixi will install the conda package (and not the PyPI package) if both are available and specified as dependencies. Here is an example of how this works in practice: pixi.toml ```toml [dependencies] python = ">=3.8" numpy = ">=1.21.0" [pypi-dependencies] numpy = ">=1.21.0" ``` Which results in the following output: ```output ➜ pixi list -x Package Version Build Size Kind Source numpy 2.3.0 py313h41a2e72_0 6.2 MiB conda https://conda.anaconda.org/conda-forge/ python 3.13.5 hf3f3da0_102_cp313 12.3 MiB conda https://conda.anaconda.org/conda-forge/ ``` In this example, Pixi will first resolve the conda dependencies and install the `numpy` and `python` conda packages. Then it will map the `numpy` conda package to the `numpy` PyPI package and resolve any PyPI dependencies. Since there are no remaining PyPI dependencies (as `numpy` was already installed as a conda package), no PyPI packages will be installed. Another example is when you have a PyPI package dependency that is not specified as a conda package dependency: pixi.toml ```toml [dependencies] python = ">=3.8" [pypi-dependencies] numpy = ">=1.21.0" ``` Which results in the following output: ```output > pixi list --explicit Package Version Build Size Kind Source numpy 2.3.1 43.8 MiB pypi numpy-2.3.1-cp313-cp313-macosx_11_0_arm64.whl python 3.13.5 hf3f3da0_102_cp313 12.3 MiB conda https://conda.anaconda.org/conda-forge/ ``` In this example, Pixi will first resolve the conda dependencies and install the `python` conda package. Then, since `numpy` is not specified as a conda dependency, Pixi will resolve the PyPI dependencies and install the `numpy` PyPI package. To override or change the mapping of conda packages to PyPI packages, you can use the [`conda-pypi-map`](../../reference/pixi_manifest/#conda-pypi-map-optional) field in the `pixi.toml` file. ### Pinned package conflicts When trying to install conda and PyPI dependencies, such as with the following `pixi.toml` manifest: pixi.toml ```toml [dependencies] typing_extensions = "*" [pypi-dependencies] typing_extensions = "==4.14" ``` you might encounter the following error message: ```text Error: Γ— failed to solve the pypi requirements of environment 'default' for platform 'osx-arm64' β”œβ”€β–Ά failed to resolve pypi dependencies ╰─▢ Because you require typing-extensions==4.14 and typing-extensions==4.15.0, we can conclude that your requirements are unsatisfiable. help: The following PyPI packages have been pinned by the conda solve, and this version may be causing a conflict: typing-extensions==4.15.0 ``` This is due to the (current) two-stage solve. First, the conda dependencies are resolved. As any version (`*`) of `typing_extensions` is valid, it resolves to the latest available (`4.15.0` in this case). Then, the PyPI dependencies are resolved (`typing_extensions == 4.14`), with the constraints of the already resolved conda dependencies (`typing_extensions == 4.15.0`). These two dependencies are incompatible and the solve fails. While this might be a trivial case, it is less obvious when the packages are not explicit dependencies: pixi.toml ```toml [dependencies] some-conda-package = "*" # depends on any typing-extensions [pypi-dependencies] some-pypi-package = "==0.1.0" # depends on typing-extensions<4.14 ``` which produces the following solve error: ```text Error: Γ— failed to solve the pypi requirements of environment 'default' for platform 'osx-arm64' β”œβ”€β–Ά failed to resolve pypi dependencies ╰─▢ Because some-pypi-dependency==0.1.0 depends on typing-extensions<4.15 and typing-extensions==4.15.0, we can conclude that some-pypi-dependency==0.1.0 cannot be used. And because only some-pypi-dependency==0.1.0 is available and you require some-pypi-dependency, we can conclude that your requirements are unsatisfiable. help: The following PyPI packages have been pinned by the conda solve, and this version may be causing a conflict: typing-extensions==4.15.0 ``` A solution in this case would be to add to the conda dependencies `typing-extensions < 4.15`, that is, the same constraint imposed by the PyPI package(s): pixi.toml ```toml [dependencies] some-conda-package = "*" # depends on any typing-extensions typing_extensions = "<4.15" [pypi-dependencies] some-pypi-package = "==0.1.0" # depends on typing-extensions<4.14 ``` # Package Specifications When adding packages to your Pixi workspace or global environment, you can use various specifications to control exactly which package version and build you want. This is particularly important when packages have multiple builds for different hardware configurations (like CPU vs GPU). For the conda packages Pixi uses the [MatchSpec](https://rattler.prefix.dev/py-rattler/match_spec#matchspec) format to specify package requirements. For PyPI packages, Pixi uses the standard [PEP440 version specifiers](https://peps.python.org/pep-0440/). ## Quick Examples ```bash # Install a specific version pixi add python=3.11 # Install with version constraints pixi add "numpy>=1.21,<2.0" # Install a specific build (e.g., CUDA-enabled package) using = syntax pixi add "pytorch=*=cuda*" # Alternative bracket syntax for build specification pixi add "pytorch [build='cuda*']" # Specify both version and build using bracket syntax pixi add "pytorch [version='2.9.*', build='cuda*']" # Simple PyPI package pixi add --pypi requests # PyPI package version range pixi add --pypi "requests>=2.20,<3.0" # PyPI package with extras pixi add --pypi "requests[security]==2.25.1" ``` ```bash # Install a specific version pixi global install python=3.11 # Install with version constraints pixi global install "numpy>=1.21,<2.0" # Install a specific build (e.g., CUDA-enabled package) using = syntax pixi global install "pytorch=*=cuda*" # Alternative bracket syntax for build specification pixi global install "pytorch [build='cuda*']" # Specify both version and build using bracket syntax pixi global install "pytorch [version='2.9.*', build='cuda*']" ``` ```bash # Execute a command in an ephemeral environment pixi exec python # Execute with specific package versions pixi exec -s python=3.11 python # Execute with specific package builds pixi exec -s "python=*=*cp313" python # Execute with channel specification pixi exec --channel conda-forge python ``` ## Basic Version Specifications Pixi uses the [**conda MatchSpec**](https://rattler.prefix.dev/py-rattler/match_spec#matchspec) format for specifying package requirements. A MatchSpec allows you to precisely define which package version, build, and channel you want. The simplest way to specify a package is by name and [optional version operators](#version-operators): pixi.toml ```toml [dependencies] # Latest version (any) numpy = "*" # Specific version python = "==3.11.0" # Version range scipy = ">=1.9,<2.0" # Fuzzy version matching (any 3.11.x) pandas = "3.11.*" ``` ## Full MatchSpec Syntax Beyond simple version specifications, you can use the full [MatchSpec](https://rattler.prefix.dev/py-rattler/match_spec#matchspec) syntax to precisely control which package variant you want. ### Command Line Syntax Pixi supports two syntaxes on the command line: **1. Equals syntax (compact):** ```shell # Format: package=version=build pixi add "pytorch=2.0.*=cuda*" # Only build string (any version) pixi add "numpy=*=py311*" ``` **2. Bracket syntax (explicit):** ```shell # Format: package [key='value', ...] pixi add "pytorch [version='2.0.*', build='cuda*']" # Multiple constraints pixi add "numpy [version='>=1.21', build='py311*', channel='conda-forge']" # Build number constraint pixi add "python [version='3.11.0', build_number='>=1']" ``` Both syntaxes are equivalent and can be used interchangeably. ### TOML Mapping Syntax In your `pixi.toml`, use the mapping syntax for complete control: pixi.toml ```toml [dependencies.pytorch] version = "2.0.*" # Build string pattern build = "cuda*" # Build number constraint build-number = ">=1" # Specific channel channel = "https://prefix.dev/my-channel" # Checksums md5 = "1234567890abcdef1234567890abcdef" sha256 = "abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890" # License type license = "BSD-3-Clause" # Package file name file-name = "pytorch-2.0.0-cuda.tar.bz2" ``` This syntax allows you to specify: - **version**: Version constraint using [operators](#version-operators) - **build**: Build string pattern (see [build strings](#build-strings)) - **build-number**: Build number constraint (e.g., `">=1"`, `"0"`) (see [build number](#build-number)) - **channel**: Specific channel name or full URL (see [channel](#channel)) - **sha256/md5**: Package checksums for verification (see [checksums](#checksums-sha256md5)) - **license**: Expected license type (see [license](#license)) - **file-name**: Specific package file name (see [file name](#file-name)) ### Version Operators Pixi supports various version operators: | Operator | Meaning | Example | | -------- | --------------------- | -------------------------------- | | `==` | Exact match | `==3.11.0` | | `!=` | Not equal | `!=3.8` | | `<` | Less than | `<3.12` | | `<=` | Less than or equal | `<=3.11` | | `>` | Greater than | `>3.9` | | `>=` | Greater than or equal | `>=3.9` | | `~=` | Compatible release | `~=3.11.0` (>= 3.11.0, < 3.12.0) | | `*` | Wildcard | `3.11.*` (any 3.11.x) | | `,` | AND | `">=3.9,<3.12"` | | \` | \` | OR | ### Build Strings Build strings identify specific builds of the same package version. They're especially important for packages that have different builds for: - **Hardware acceleration**: CPU, GPU/CUDA builds - **Python versions**: Packages built for different Python interpreters - **Compiler variants**: Different compiler versions or configurations A build string typically looks like: `py311h43a39b2_0` Breaking it down: - `py311`: Python version indicator - `h43a39b2`: Hash of the build configuration - `_0`: Build number You can use wildcards in build patterns to match multiple builds: ```shell # Match any CUDA build pixi add "pytorch=*=cuda*" # Match Python 3.11 builds pixi add "numpy=*=py311*" # Using bracket syntax pixi add "pytorch [build='cuda*']" ``` ### Build Number The build number is an integer that increments each time a package is rebuilt with the same version. Use build number constraints when you need a specific rebuild of a package: ```shell # Specific build number pixi add "python [version='3.11.0', build_number='1']" # Build number constraint pixi add "numpy [build_number='>=5']" ``` pixi.toml ```toml [dependencies.python] version = "3.11.0" build-number = ">=1" ``` Build numbers are useful when: - A package was rebuilt to fix a compilation issue - You need to ensure you have a specific rebuild with bug fixes - Working with reproducible environments that require exact builds ### Channel Channels are repositories where conda packages are hosted. You can specify which channel to fetch a package from: ```shell # Specific channel by name pixi add "pytorch [channel='pytorch']" # Channel URL pixi add "custom-package [channel='https://prefix.dev/my-channel']" # Or use the shorter `::` syntax pixi add pytorch::pytorch pixi add https://prefix.dev/my-channel::custom-package ``` pixi.toml ```toml [dependencies.pytorch] channel = "pytorch" [dependencies.custom-package] channel = "https://prefix.dev/my-channel" ``` Note that for `pixi add`, channels must also be listed in your workspace configuration: pixi.toml ```toml [workspace] channels = ["conda-forge", "pytorch", "nvidia"] ``` You can also add these using the command line: ```shell pixi workspace channel add conda-forge ``` ### Checksums (SHA256/MD5) Checksums verify package integrity and authenticity. Use them for reproducibility and security: pixi.toml ```toml [dependencies.numpy] version = "1.21.0" sha256 = "1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef" md5 = "abcdef1234567890abcdef1234567890" ``` When specified, Pixi will: - Verify the downloaded package matches the checksum - Fail the installation if checksums don't match - Ensure you get the exact package you expect SHA256 is preferred over MD5 for security reasons. ### License Specify the expected license of a package. This is useful for: - Ensuring compliance with your organization's policies - Filtering packages by license type - Documentation purposes pixi.toml ```toml [dependencies.pytorch] version = "2.0.*" license = "BSD-3-Clause" ``` ### File Name Specify the exact package file name to download. This is rarely needed but useful for: - Debugging package resolution issues - Ensuring a specific package artifact - Advanced use cases with custom package builds pixi.toml ```toml [dependencies.pytorch] file-name = "pytorch-2.0.0-cuda.tar.bz2" ``` ## Source Packages Warning `pixi-build` is a preview feature, and will change until it is stabilized. Please keep that in mind when you use it for your workspaces. For these packages to be recognized they need to be understood by Pixi as source packages. Look at the [Pixi Manifest Reference](../../reference/pixi_manifest/#the-package-section) for more information on how to declare source packages in your `pixi.toml`. ### Path-based Source Packages pixi.toml ```toml [dependencies.local-package] # Local file path to a pixi package path = "/path/to/package" ``` The path should be relative to the workspace root or an absolute path, but absolute paths are discouraged for portability. ### Git-based Source Packages pixi.toml ```toml # Git repository of a Pixi package [dependencies.git-package] # Git repository git = "https://github.com/org/repo" # Git branch branch = "main" # Subdirectory within repo subdirectory = "packages/mypackage" [dependencies.tagged-git-package] # Git with specific tag git = "https://github.com/org/repo" tag = "v1.0.0" [dependencies.rev-git-package] # Git with specific revision git = "https://github.com/org/repo" rev = "abc123def" ``` For git repositories, you can specify: - **git**: Repository URL - **branch**: Git branch name - **tag**: Git tag - **rev**: Specific git revision/commit SHA - **subdirectory**: Path within the repository ## PyPI package specifications Pixi also supports installing package dependencies from PyPI using `pixi add --pypi` and in your `pixi.toml` and `pyproject.toml`. Pixi implements the standard [PEP440 version specifiers](https://peps.python.org/pep-0440/) for specifying package versions. ### Command Line Syntax When using `pixi add --pypi`, you can [specify packages similarly to `pip`](https://pip.pypa.io/en/stable/user_guide/#installing-packages): ```shell # Simple package pixi add --pypi requests # Specific version pixi add --pypi "requests==2.25.1" # Version range pixi add --pypi "requests>=2.20,<3.0" # Extras pixi add --pypi "requests[security]==2.25.1" # URL pixi add --pypi "requests @ https://files.pythonhosted.org/packages/1e/db/4254e3eabe8020b458f1a747140d32277ec7a271daf1d235b70dc0b4e6e3/requests-2.32.5-py3-none-any.whl#sha256=2462f94637a34fd532264295e186976db0f5d453d1cdd31473c85a6a161affb6" # Git repository pixi add --pypi "requests @ git+https://github.com/psf/requests.git@v2.25.1" pixi add --pypi requests --git https://github.com/psf/requests.git --tag v2.25.1 pixi add --pypi requests --git https://github.com/psf/requests.git --branch main pixi add --pypi requests --git https://github.com/psf/requests.git --rev 70298332899f25826e35e42f8d83425124f755a ``` ### TOML Mapping Syntax In your `pixi.toml` or `pyproject.toml` (under `[tool.pixi.pypi-dependencies]`), you can specify PyPI packages like this: pixi.toml ```toml [pypi-dependencies] # Version specification black = "==22.3.0" ruff = ">=0.0.241,<1.0.0" # Specific index URL pytest = { version = "==7.2.0", index = "https://pypi.org/simple" } # Extras fastapi = { version = "==0.78.0", extras = ["all"] } # URL uvicorn = { url = "https://files.pythonhosted.org/packages/1e/db/4254e3eabe8020b458f1a747140d32277ec7a271daf1d235b70dc0b4e6e3/requests-2.32.5-py3-none-any.whl#sha256=2462f94637a34fd532264295e186976db0f5d453d1cdd31473c85a6a161affb6" } # Git repository requests0 = { git = "https://github.com/psf/requests.git", rev = "70298332899f25826e35e42f8d83425124f755a" } requests1 = { git = "https://github.com/psf/requests.git", branch = "main" } requests2 = { git = "https://github.com/psf/requests.git", tag = "v2.28.1" } requests3 = { git = "https://github.com/psf/requests.git", subdirectory = "requests" } # Local path local_package = { path = "../local_package" } local_package2 = { path = "../local_package2", extras = ["extra_feature"] } local_package3 = { path = "../local_package3", editable = true } ``` ## Further Reading - [Pixi Manifest Reference](../../reference/pixi_manifest/#dependencies) - Complete dependency specification options - [Multi-Platform Configuration](../../workspace/multi_platform_configuration/) - Platform-specific dependencies - [Conda Package Specification](https://conda.io/projects/conda/en/latest/user-guide/concepts/pkg-specs.html) - Conda's package specification docs # The Global Manifest This global manifest contains the list of environments that are installed globally, their dependencies and exposed binaries. It can be edited, synced, checked in to a version control system, and shared with others. Running the commands from the section before results in the following manifest: ```toml version = 1 [envs.rattler-build] channels = ["conda-forge"] dependencies = { rattler-build = "*" } exposed = { rattler-build = "rattler-build" } [envs.ipython] channels = ["conda-forge"] dependencies = { ipython = "*", numpy = "*", matplotlib = "*" } exposed = { ipython = "ipython", ipython3 = "ipython3" } [envs.python] channels = ["conda-forge"] dependencies = { python = "3.12.*" } # (1)! exposed = { py3 = "python" } # (2)! ``` 1. Dependencies are the packages that will be installed into the environment. You can specify the version or use a wildcard. 1. The exposed binaries are the ones that will be available in the system path. In this case, `python` is exposed under the name `py3`. ## Manifest locations The manifest can be found at the following locations depending on your operating system. Run [`pixi info`](../../reference/cli/pixi/info/), to find the currently used manifest on your system. | **Priority** | **Location** | **Comments** | | ------------ | -------------------------------------------------- | --------------------------------------- | | 4 | `$PIXI_HOME/manifests/pixi-global.toml` | Global manifest in `PIXI_HOME`. | | 3 | `$HOME/.pixi/manifests/pixi-global.toml` | Global manifest in user home directory. | | 2 | `$XDG_CONFIG_HOME/pixi/manifests/pixi-global.toml` | XDG compliant config directory. | | 1 | `$HOME/.config/pixi/manifests/pixi-global.toml` | Config directory. | | **Priority** | **Location** | **Comments** | | ------------ | ------------------------------------------------------------------- | --------------------------------------- | | 3 | `$PIXI_HOME/manifests/pixi-global.toml` | Global manifest in `PIXI_HOME`. | | 2 | `$HOME/.pixi/manifests/pixi-global.toml` | Global manifest in user home directory. | | 1 | `$HOME/Library/Application Support/pixi/manifests/pixi-global.toml` | Config directory. | | **Priority** | **Location** | **Comments** | | ------------ | ------------------------------------------------ | --------------------------------------- | | 3 | `$PIXI_HOME\manifests/pixi-global.toml` | Global manifest in `PIXI_HOME`. | | 2 | `%USERPROFILE%\.pixi\manifests\pixi-global.toml` | Global manifest in user home directory. | | 1 | `%APPDATA%\pixi\manifests\pixi-global.toml` | Config directory. | Note If multiple locations exist, the manifest with the highest priority will be used. ## Channels The `channels` key describes the Conda channels that will be used to download the packages. There is a priority to these, so the first one will have the highest priority. If a package is not found in that channel the next one will be used. For example, running: ```text pixi global install --channel conda-forge --channel bioconda snakemake ``` Results in the following entry in the manifest: ```toml [envs.snakemake] channels = ["conda-forge", "bioconda"] dependencies = { snakemake = "*" } exposed = { snakemake = "snakemake" } ``` More information on channels can be found [here](../../advanced/channel_logic/). ## Dependencies Dependencies are the Conda packages that will be installed into your environment. For example, running: ```text pixi global install "python<3.12" ``` creates the following entry in the manifest: ```toml [envs.vim] channels = ["conda-forge"] dependencies = { python = "<3.12" } # ... ``` Typically, you'd specify just the tool you're installing, but you can add more packages if needed. Defining the environment to install into will allow you to add multiple dependencies at once. For example, running: ```shell pixi global install --environment my-env git vim python ``` will create the following entry in the manifest: ```toml [envs.my-env] channels = ["conda-forge"] dependencies = { git = "*", vim = "*", python = "*" } # ... ``` You can [`add`](../../reference/cli/pixi/global/add/) dependencies to an existing environment by running: ```shell pixi global add --environment my-env package-a package-b ``` They will be added as dependencies to the `my-env` environment but won't auto expose the binaries from the new packages. You can [`remove`](../../reference/cli/pixi/global/remove/) dependencies by running: ```shell pixi global remove --environment my-env package-a package-b ``` ## Exposed executables One can instruct `pixi global install`, under which name it will expose executables: ```shell pixi global install --expose bird=bat bat ``` The manifest is modified like this: ```toml [envs.bat] channels = ["https://prefix.dev/conda-forge"] dependencies = { bat = "*" } exposed = { bird = "bat" } ``` This means that executable `bat` will be exposed under the name `bird`. ### Automatically Exposed Executables There is some added automatic behavior, if you install a package with the same name as the environment, it will be exposed with the same name. Even if the binary name is only exposed through dependencies of the package For example, running: ```text pixi global install ansible ``` will create the following entry in the manifest: ```toml [envs.ansible] channels = ["conda-forge"] dependencies = { ansible = "*" } exposed = { ansible = "ansible" } # (1)! ``` 1. The `ansible` binary is exposed even though it is installed by a dependency of `ansible`, the `ansible-core` package. It's also possible to expose an executable which is located in a nested directory. For example dotnet.exe executable is located in a dotnet folder, to expose `dotnet` you must specify its relative path : ```text pixi global install dotnet --expose dotnet=dotnet\dotnet ``` Which will create the following entry in the manifest: ```toml [envs.dotnet] channels = ["conda-forge"] dependencies = { dotnet = "*" } exposed = { dotnet = 'dotnet\dotnet' } ``` ## Shortcuts Especially for graphical user interfaces it is useful to add shortcuts. This way the application shows up in the start menu or is suggested when you want to open a file type the application supports. If the package supports shortcuts, nothing has to be done from your side. Simply executing `pixi global install` will do the trick. For example, `pixi global install mss` will lead to the following manifest: ```toml [envs.mss] channels = ["https://prefix.dev/conda-forge"] dependencies = { mss = "*" } exposed = { ... } shortcuts = ["mss"] ``` Note the `shortcuts` entry. If it's present, `pixi` will install the shortcut for the `mss` package. This means, the application will show up in the start menu. If you want to package an application yourself that would benefit from this, you can check out the corresponding [documentation](https://conda.github.io/menuinst/). ## Trampolines To increase efficiency, `pixi` uses *trampolines*β€”small, specialized binary files that manage configuration and environment setup before executing the main binary. The trampoline approach allows for skipping the execution of activation scripts that have a significant performance impact. When you execute a globally installed executable, a trampoline performs the following sequence of steps: - Each trampoline first reads a configuration file named after the binary being executed. This configuration file, in JSON format (e.g., `python.json`), contains key information about how the environment should be set up. The configuration file is stored in [`$PIXI_HOME`](../../reference/environment_variables/)`/bin/trampoline_configuration`. - Once the configuration is loaded and the environment is set, the trampoline executes the original binary with the correct environment settings. - When installing a new binary, a new trampoline is placed in the [`$PIXI_HOME`](../../reference/environment_variables/)`/bin` directory and is hard-linked to the [`$PIXI_HOME`](../../reference/environment_variables/)`/bin/trampoline_configuration/trampoline_bin`. This optimizes storage space and avoids duplication of the same trampoline. The trampoline will take care that the `PATH` contains the newest changes on your local `PATH` while avoiding caching temporary `PATH` changes during installation. If you want to control the base `PATH` pixi considers, you can set `export PIXI_BASE_PATH=$PATH` in your shell startup script. # Building documentation In this tutorial, we will show you how to build the same C++ package as from [Building a C++ Package](../cpp/) tutorial using [`rattler-build`](https://rattler.build). In this tutorial we assume that you've read the [Building a C++ Package](../cpp/) tutorial. If you haven't read it yet, we recommend you to do so before continuing. You might also want to check out the [documentation](../backends/pixi-build-rattler-build/) for the `pixi-build-rattler-build` backend. The project structure and the source code will be the same as in the previous tutorial, so we may skip explicit explanations of some parts. This approach may be useful when no build backend for your language or build system exists. Another reason to use it is when you would like to have more control over the build process. To illustrate this, we will use the same C++ package as in the previous tutorial, but this time we will use `rattler-build` to build it. This will unveil the hidden complexity of the build process, and give you a better grasp of how backends work. Warning `pixi-build` is a preview feature, and will change until it is stabilized. Please keep that in mind when you use it for your workspaces. Hint Prefer using a backend if it exists. This will give you a more streamlined and unified build experience. ## Workspace structure To get started, please recreate the structure of the workspace from the previous tutorial [Building a C++ Package](../cpp/). ### The `pixi.toml` file We are now using the `pixi-build-rattler-build` backend instead of the `pixi-build-cmake` backend. ```toml [workspace] channels = ["https://prefix.dev/conda-forge"] platforms = ["osx-arm64", "osx-64", "linux-64", "win-64"] preview = ["pixi-build"] [dependencies] cpp_math = { path = "." } python = "3.12.*" [tasks] start = "python -c 'import cpp_math as b; print(b.add(1, 2))'" [package] name = "cpp_math" version = "0.1.0" [package.build] backend = { name = "pixi-build-rattler-build", version = "0.3.*" } ``` ## The `recipe.yaml` file Next lets add the `recipe.yaml` file that describes how `rattler-build` builds the package. You can find the reference on the `rattler-build` documentation [web page](https://rattler.build/latest/reference/recipe_file/). ```yaml package: name: cpp_math version: 0.1.0 source: path: . use_gitignore: true # (1)! build: number: 0 script: | # (2)! cmake $CMAKE_ARGS \ -GNinja \ -DCMAKE_BUILD_TYPE=Release \ -DCMAKE_INSTALL_PREFIX=$PREFIX \ -DCMAKE_EXPORT_COMPILE_COMMANDS=ON \ -DBUILD_SHARED_LIBS=ON \ -B $SRC_DIR/../build \ -S . cmake --build $SRC_DIR/../build --target install requirements: build: # (3)! - ${{ compiler('cxx') }} - cmake - ninja host: # (4)! - python 3.12.* - nanobind ``` 1. Because we are specifying the current directory as the source directory, `rattler-build` may skip files that are not tracked by git. If your files are already tracked by git, you can remove this configuration. 1. This build script configures and builds a `CMake` project using the `Ninja` build system. It sets various options such as the build type to `Release`, the installation prefix to `$PREFIX`, and enables shared libraries and compile commands export. The script then builds the project in the specified build directory `($SRC_DIR/../build)` and installs the built files to the installation directory. 1. For build dependencies we need compilers and the build systems `cmake` and `ninja`. Make sure that `cmake` version matches the one from `CMakeLists.txt` file. 1. For `python` bindings, we need `nanobind` and `python` itself. They are set in `host` dependencies section as we link them to the `python` where the bindings will be installed, not built. ## Testing if everything works Now that we've defined a `pixi` task which allows us to check that our package can properly add `1` and `2`: ```toml [tasks] start = "python -c 'import cpp_math as b; print(b.add(1, 2))'" ``` Executing the tasks works as expected ```bash $ pixi run start 3 ``` This command builds the bindings, installs them and then runs the `test` task. ## Conclusion In this tutorial, we created a Pixi package using `rattler-build` and a `recipe.yaml` file. Using this approach, we had more control over the build process. For example, we could changed the build type to `Debug` using `CMAKE_BUILD_TYPE`, use `Make` instead of `Ninja` by removing the `-GNinja` configuration. Or we could use `make -j$(nproc)` to specify the number of jobs to run in parallel when building the package. At the same time, we lost all the benefit of heavy lifting that is done by language build backend. Thanks for reading! Happy Coding πŸš€ Any questions? Feel free to reach out or share this tutorial on [X](https://twitter.com/prefix_dev), [join our Discord](https://discord.gg/kKV8ZxyzY4), [e-mail](mailto:hi@prefix.dev) us or follow our [GitHub](https://github.com/prefix-dev). To decouple the building of a conda package from Pixi we provide something what are called build backends. These are essentially executables following a specific protocol that is implemented for both Pixi and the build backend. This also allows for decoupling of the build backend from Pixi and it's manifest specification. ## Available Backends | Backend | Use Case | | ----------------------------------------------------------- | --------------------------------------------- | | [**`pixi-build-cmake`**](pixi-build-cmake/) | Projects using CMake | | [**`pixi-build-python`**](pixi-build-python/) | Building Python packages | | [**`pixi-build-rattler-build`**](pixi-build-rattler-build/) | Direct `recipe.yaml` builds with full control | | [**`pixi-build-ros`**](pixi-build-ros/) | ROS (Robot Operating System) packages | | [**`pixi-build-r`**](pixi-build-r/) | R packages using `R CMD INSTALL` | | [**`pixi-build-rust`**](pixi-build-rust/) | Cargo-based Rust applications and libraries | | [**`pixi-build-mojo`**](pixi-build-mojo/) | Mojo applications and packages | All backends are available through the [conda-forge](https://prefix.dev/channels/conda-forge) conda channel and work across multiple platforms (Linux, macOS, Windows). For the latest backend versions, you can prepend the channel list with the [prefix.dev/pixi-build-backends](https://prefix.dev/channels/pixi-build-backends) conda channel. ## Key Concepts - [Compilers](../key_concepts/compilers/) - How pixi-build integrates with conda-forge's compiler infrastructure ### Installation Install a certain build backend by adding it to the `package.build` section of the manifest file.: ```toml [package.build.backend] channels = [ "https://prefix.dev/pixi-build-backends", "https://prefix.dev/conda-forge", ] name = "pixi-build-python" version = "0.1.*" ``` For custom backend channels, you can add the channel to the `channels` section of the manifest file: ```toml [package.build] backend = { name = "pixi-build-python", version = "0.4.*" } channels = [ "https://prefix.dev/pixi-build-backends", "https://prefix.dev/conda-forge", ] ``` ### Overriding the Build Backend Sometimes you want to override the build backend that is used by pixi. Meaning overriding the backend that is specified in the [`[package.build]`](../../reference/pixi_manifest/#build-table). We currently have two environment variables that allow for this: 1. `PIXI_BUILD_BACKEND_OVERRIDE`: This environment variable allows for overriding of one or multiple backends. Use `{name}={path}` to specify a backend name mapped to a path and `,` to separate multiple backends. For example: `pixi-build-cmake=/path/to/bin,pixi-build-python` will: 1. override the `pixi-build-cmake` backend with the executable located at `/path/to/bin` 1. and will use the `pixi-build-python` backend from the `PATH`. 1. `PIXI_BUILD_BACKEND_OVERRIDE_ALL`: If this environment variable is set to *some* value e.g `1` or `true`, it will not install any backends in isolation and will assume that all backends are overridden and available in the `PATH`. This is useful for development purposes. e.g `PIXI_BUILD_BACKEND_OVERRIDE_ALL=1 pixi install` ## Troubleshooting ### Rebuilding Generated Recipes When you build a package using `pixi build`, the build backends generate a complete rattler-build recipe that is stored in your project's build directory. This can be useful for debugging build issues or understanding exactly how your package is being built. ### Recipe Locations The build backends generate recipes in two locations: #### 1. General Recipe (all outputs) ```text /.pixi/build/work/--/debug/ ``` This directory contains: - `recipe.yaml` - A general recipe that can build all package outputs - `variants.yaml` - All variant configurations for the package #### 2. Variant-Specific Recipe (single output) ```text /.pixi/build/work/--/debug/recipe// ``` This directory contains: - `recipe.yaml` - The complete rattler-build recipe generated by the build backend - `variants.yaml` - The variant configuration used for this specific build ### Rebuilding a Package To debug or rebuild a package using the same configuration, you have two options: #### Option 1: Navigate to the recipe directory 1. Navigate to the recipe directory: ```bash cd .pixi/build/work/--/recipe//debug/ ``` 1. Use `rattler-build` to rebuild the package: ```bash rattler-build build ``` #### Option 2: Point to the recipe directory Use the `--recipe` flag to build without changing directories: ```bash rattler-build build --recipe .pixi/build/work/--/debug/recipe// ``` This allows you to: - Inspect the exact recipe that was generated - Debug build failures with direct access to `rattler-build` - Understand how the build backend translated your project model (`pixi.toml`) Tip The `` ensures that each unique combination of build variants gets its own recipe directory, making it easy to compare different build configurations. ### Debugging JSON-RPC You can find JSON version of your project model and requests/responses in the same directory alongside `recipe.yaml`. We store: - Project model: `project_model.json` - Requests: `*_params.json` - Responses: `*_response.json` This example shows how to build a C++ package with CMake and use it together with `pixi-build`. To read more about how building packages work with Pixi see the [Getting Started](../getting_started/) guide. You might also want to check out the [documentation](../backends/pixi-build-cmake/) for the `pixi-build-cmake` backend. We'll start off by creating a workspace that use [nanobind](https://github.com/wjakob/nanobind) to build Python bindings. That we can also test using pixi. We'll later combine this example together with a Python package. Warning `pixi-build` is a preview feature, and will change until it is stabilized. Please keep that in mind when you use it for your workspaces. ## Creating a New Workspace To get started, create a new workspace with pixi: ```bash pixi init cpp_math ``` This should give you the basic `pixi.toml` to get started. We'll now create the following source directory structure: ```bash cpp_math/ β”œβ”€β”€ CMakeLists.txt β”œβ”€β”€ pixi.toml β”œβ”€β”€ .gitignore └── src └── math.cpp ``` ## Creating the workspace files Next up we'll create the: - `pixi.toml` file that will be used to configure pixi. - `CMakeLists.txt` file that will be used to build the bindings. - `src/math.cpp` file that will contain the bindings. ### The `pixi.toml` file Use the following `pixi.toml` file, you can hover over the annotations to see why each step was added. ```toml [workspace] channels = ["https://prefix.dev/conda-forge"] platforms = ["osx-arm64", "linux-64", "osx-64", "win-64"] preview = ["pixi-build"] # (1)! [dependencies] # (2)! cpp_math = { path = "." } python = "*" [tasks] start = "python -c 'import cpp_math as b; print(b.add(1, 2))'" # (3)! [package] # (4)! name = "cpp_math" version = "0.1.0" [package.build] backend = { name = "pixi-build-cmake", version = "0.3.*" } [package.build.config] extra-args = ["-DCMAKE_BUILD_TYPE=Release"] # (9)! [package.host-dependencies] cmake = "3.20.*" # (8)! nanobind = "2.4.*" # (6)! python = "3.12.*" # (7)! ``` 1. Add the **preview** feature `pixi-build` that enables Pixi to build the package. 1. These are the workspace dependencies. We add our own package as well as Python so that we can later run our package. 1. Let's add a task that will run our test 1. This is where we specify the package name and version. This section denotes that there is both a workspace and a package defined by this `pixi.toml` file. 1. We use `pixi-build-cmake` as the build-system, so that we get the backend to build cmake packages. 1. We use the [nanobind](https://github.com/wjakob/nanobind) package to build our bindings. 1. We need python to build the bindings, so we add a host dependency on the `python` package. 1. We override the cmake version to ensure it matches our `CMakeLists.txt` file. 1. Optionally, we can add extra arguments to the CMake invocation (e.g. `-DCMAKE_BUILD_TYPE=Release` or `-DUSE_FOOBAR=True`). This totally depends on the specific workspace / CMakeLists.txt file. ### The `CMakeLists.txt` file Next lets add the `CMakeList.txt` file: ```CMake cmake_minimum_required(VERSION 3.20...3.27) project(cpp_math) find_package(Python 3.8 COMPONENTS Interpreter Development.Module REQUIRED) # (1)! execute_process( COMMAND "${Python_EXECUTABLE}" -m nanobind --cmake_dir OUTPUT_STRIP_TRAILING_WHITESPACE OUTPUT_VARIABLE nanobind_ROOT ) # (2)! execute_process( COMMAND ${Python_EXECUTABLE} -c "import sysconfig; print(sysconfig.get_path('purelib'))" OUTPUT_VARIABLE PYTHON_SITE_PACKAGES OUTPUT_STRIP_TRAILING_WHITESPACE ) # (3)! find_package(nanobind CONFIG REQUIRED) # (4)! nanobind_add_module(${PROJECT_NAME} src/math.cpp) # (5)! install( # (6)! TARGETS ${PROJECT_NAME} EXPORT ${PROJECT_NAME}Targets LIBRARY DESTINATION ${PYTHON_SITE_PACKAGES} ARCHIVE DESTINATION ${CMAKE_INSTALL_LIBDIR} RUNTIME DESTINATION ${BINDIR} ) ``` 1. Find `python`, this actually finds anything above 3.8, but we are using 3.8 as a minimum version. 1. Because we are using `python` in a conda environment we need to query the python interpreter to find the `nanobind` package. 1. Because we want to make the installation directory independent of the python version, we query the python `site-packages` directory. 1. Find the installed nanobind package. 1. Use our bindings file as the source file. 1. Install the bindings into the designated prefix. ### The `src/math.cpp` file Next lets add the `src/math.cpp` file, this one is quite simple: ```cpp #include int add(int a, int b) { return a + b; } // (1)! NB_MODULE(cpp_math, m) { m.def("add", &add); // (2)! } ``` 1. We define a function that will be used to add two numbers together. 1. We bind this function to the python module using the `nanobind` package. ## Testing if everything works Now that we have created the files we can test if everything works: ```bash $ pixi run start 3 ``` This command builds the bindings, installs them and then runs the `test` task. ## Conclusion In this tutorial, we created a Pixi package using C++. It can be used as-is, to upload to a conda channel. 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](https://twitter.com/prefix_dev), [join our Discord](https://discord.gg/kKV8ZxyzY4), [e-mail](mailto:hi@prefix.dev) us or follow our [GitHub](https://github.com/prefix-dev). If you add a package to the [dependency table](../../reference/pixi_manifest/#dependencies) of a feature that dependency will be available in all environments that include that feature. The dependencies of a package that is being built are a bit more granular. Here you can see the three types of dependencies for a simple C++ package. ```toml [package.build-dependencies] cxx-compiler = "*" [package.host-dependencies] catch = "*" [package.run-dependencies] git = "*" ``` Each dependency is used at a different step of the package building process. `cxx-compiler` is used to build the package, `catch` will be linked into the package and `git` will be available during runtime. Let's delve deeper into the various types of package dependencies and their specific roles in the build process. ### [Build Dependencies](../../reference/pixi_manifest/#build-dependencies) pixi-build-cmake When using the `pixi-build-cmake` backend you do not need to specify `cmake` or the compiler as a dependency. The backend will install `cmake`, `ninja` and the C++ compilers by default. This table contains dependencies that are needed to build the workspace. Different from dependencies and host-dependencies these packages are installed for the architecture of the build machine. This enables cross-compiling from one machine architecture to another. Typical examples of build dependencies are: - Compilers are invoked on the build machine, but they generate code for the target machine. If the package is cross-compiled, the architecture of the build and target machine might differ. - `cmake` is invoked on the build machine to generate additional files which are then include in the compilation process. Info The *build* target refers to the machine that will execute the build. Programs and libraries installed by these dependencies will be executed on the build machine. For example, if you compile on a MacBook with an Apple Silicon chip but target Linux x86_64 then your *build* platform is `osx-arm64` and your *host* platform is `linux-64`. ### [Host Dependencies](../../reference/pixi_manifest/#host-dependencies) Host dependencies are the dependencies needed during build/link time that are specific to the host machine. The difference to build dependencies becomes for example important during cross compilation. The compiler is a build dependency since it is specific to your machine. In contrast, the libraries you link to are host dependencies since they are specific to the host machine. Typical examples of host dependencies are: - Base interpreters: a Python package would list `python` here and an R package would list `mro-base` or `r-base`. - Libraries your package links against like `openssl`, `rapidjson`, or `xtensor`. #### Python Code Because of the way building currently works, dependencies like `hatchling`,`pip`,`uv` etc. are host dependencies. Otherwise, it would use the wrong python prefix during the build process. This is more of a technical limitation, and we are looking into ways to make this less of a hassle. But for now, you will need to add these dependencies to the `host-dependencies` section. So as an example, say we want to use `hatchling` and `uv` as to build a python package. You need to use, something like this in your manifest file: ```toml [host-dependencies] hatchling = "*" uv = "*" ``` #### Native Code When cross-compiling, you might need to specify host dependencies that should have the *target* machine architecture, and are used during the build process. When linking a library, for example. Let's recap an explanation that can be found here [A Master Guide To Linux Cross-Compiling](https://ruvi-d.medium.com/a-master-guide-to-linux-cross-compiling-b894bf909386) - *Build machine*: where the code is built. - *Host machine*: where the built code runs. - *Target machine*: where the binaries spit out by the built code runs. Let's say we are using a Linux PC (linux-64) to cross compile a CMake application called `Awesome` to run on a Linux ARM target machine (linux-aarch64). We would get the following table: | Component | Type | Build | Host | Target | | --------- | ----------- | ------ | ------- | ------- | | GCC | Compiler | x86_64 | x86_64 | aarch64 | | CMake | Build tool | x86_64 | x86_64 | N/A | | Awesome | Application | x86_64 | aarch64 | N/A | So if I need to use a library like SDL2, I would need to add it to the `host-dependencies` table. As the machine running `Awesome` will have a different host architecture than the build architecture. Giving you something like this in your manifest file: ```toml # in our example these dependencies will use the aarch64 binaries [host-dependencies] sdl2 = "*" ``` #### Run-Exports Conda packages, can define `run-exports`, that are dependencies that when specified in the `host-dependencies` section, will be implicitly be added to the `run-dependencies` section. This is useful to avoid having to specify the same dependencies in both sections. As most packages on conda-forge will have these `run-exports` defined. When using something like `zlib`, you would only need to specify it in the `host-dependencies` section, and it will be used as a run-dependency automatically. ### [Dependencies (Run Dependencies)](../../reference/pixi_manifest/#dependencies) These are the dependencies that are required to when running the package, they are the most common dependencies. And are what you would usually use in a `workspace`. The source packages in the `[dev]` table are not built or installed into the pixi environment. The `build-dependencies`, `host-dependencies` and `run-dependencies` of those packages are installed into the pixi environment. Source dependencies in the `[dependencies]` section are build in their own isolated environment located at`.pixi/build` and the resulting conda package is then installed into the default environment. This means that the `build-` and `host-dependencies` will not be in the pixi environment. This document explains how you can use the `[dev]` table to depend on the development dependencies of a package. ## Using the `[dev]` table Assume a Rust package that you want to develop using Pixi. Then we add a `pixi.toml` manifest file: pixi.toml ```toml [workspace] channels = ["https://prefix.dev/conda-forge"] platforms = ["linux-64", "win-64", "osx-64", "osx-arm64"] preview = ['pixi-build'] [package.build.backend] name = "pixi-build-rust" version = "0.4.*" ``` Now you can use Pixi to build the package into a conda package: ```bash pixi build ``` Because of the isolation, the development dependencies such as `cargo` are not available in `pixi run`. To change that you can add a `[dev]` table to the manifest file: pixi.toml ```toml [dev] dev-package = { path = "." } ``` Now when you run `pixi install` the development dependencies will be installed into the Pixi environment. This means that you can now use `cargo` in `pixi run`: ```bash pixi run cargo run ``` This is because the packages in the `[dev]` table are not build or installed but all their `build-`, `host-`, `run-dependencies` are. Thus, you can use them during development. ## Extended example This is a full `pixi.toml` example using the `[dev]` table: pixi.toml ```toml [workspace] channels = ["https://prefix.dev/conda-forge"] platforms = ["linux-64", "win-64", "osx-64", "osx-arm64"] preview = ['pixi-build'] [package.build.backend] name = "pixi-build-rust" version = "0.4.*" [package.build-dependencies] cmake = "*" [package.host-dependencies] python = "*" [package.run-dependencies] bat = "*" [dev] dev-package = { path = "." } [dependencies] cargo-insta = "*" [tasks] build = "cargo build --release" start = "cargo run" test = "cargo test" ``` What you will see when you run `pixi list` is that you will have `cmake`, `python`, `bat` and `rust` installed all without defining them in the actual dependencies. This is because they are defined in the dependencies of the package that was included in the `[dev]` table. Next to managing workflows and environments, Pixi can also build packages. This is useful for the following reasons: - Building and uploading a package to a conda channel - Allowing users to directly depend on the source and build it automatically - Managing multiple packages in a workspace We've been working to support these use-cases with the `build` feature in pixi. The vision is to enable building of packages from source, for any language, on any platform. Known limitations Currently, the `build` feature has a number of limitations: 1. Limited set of [build-backends](https://github.com/prefix-dev/pixi-build-backends). 1. Build-backends are probably missing a lot of parameters/features. 1. Workspace dependencies cannot be inherited. ## Setting up the Manifest This is an overview of the Pixi manifest using the `pixi-build` feature. A more in-depth overview of what is available in the `[package]` part of the manifest can be found in the [Manifest Reference](../../reference/pixi_manifest/#the-package-section). pixi.toml ```toml ### Specifies properties for the whole workspace ### [workspace] preview = ["pixi-build"] channels = ["https://prefix.dev/conda-forge"] platforms = ["win-64", "linux-64", "osx-arm64", "osx-64"] [tasks] start = "rich-example-main" [dependencies] python_rich = { path = "." } ### Specify the package properties ### [package] name = "python_rich" version = "0.1.0" # We are using `pixi-build-python` in order to build a Python package [package.build.backend] name = "pixi-build-python" version = "0.4.*" # The Python package `python_rich` uses `hatchling` as Python build backend [package.host-dependencies] hatchling = "*" # The Python package `python_rich` has a run dependency on `rich` [package.run-dependencies] rich = "13.9.*" ``` Under the `[workspace]` section, you can specify properties like the name, channels, and platforms. This is currently an alias for `[project]`. Since the build feature is still in preview, you have to add "pixi-build" to `workspace.preview`. ```toml [workspace] preview = ["pixi-build"] ``` In `package` you specify properties specific to the package you want to build. ```toml [package] name = "python_rich" version = "0.1.0" ``` Packages are built by using build backends. By specifying `package.build.backend` and `package.build.channels` you determine which backend is used and from which channel it will be downloaded. There are [different build backends available](../backends/). Pixi backends describe how to build a conda package, for a certain language or build tool. In this example, we are using `pixi-build-python` backend in order to build a Python package. ```toml [package.build.backend] name = "pixi-build-python" version = "0.4.*" ``` We need to add our package `python_rich` as source dependency to the workspace. ```toml [dependencies] python_rich = { path = "." } ``` `python_rich` uses `hatchling` as Python build backend, so this needs to be mentioned in `host-dependencies`. Python PEP517 backends like `hatchling` know how to build a Python package. So `hatchling` creates a Python package, and `pixi-build-python` turns the Python package into a conda package. Read up on host-dependencies in the [dependency types chapter](../dependency_types/#host-dependencies) ```toml [package.host-dependencies] hatchling = "*" ``` We add `rich` as a run dependency to the package. This is necessary because the package uses `rich` during runtime. You can read up on run-dependencies in the [dependency types chapter](../dependency_types/#dependencies-run-dependencies) ```toml [package.run-dependencies] rich = "13.9.*" ``` ## CLI Commands Using the preview feature you can now build packages from source. - `pixi build` has been added and will build a `.conda` file out of your package. - Other commands like `pixi install` and `pixi run` automatically make use of the build feature when a `path`, `git` or `url` dependency is present. By default, the package definition assumes the location of the source to be in the root of the package definition. For example if your package has the following structure: ```text my_package β”œβ”€β”€ pixi.toml β”œβ”€β”€ src β”‚ └── my_code.cpp └── include └── my_code.h ``` Build backends are expected to have reasonable defaults from where to take the source code. Apart from the `pixi-build-rattler-build` backend where you specify the source in the `recipe.yaml`, the build backend will default to the directory where the package manifest is located Alternatively, you can specify where the source is located. ## Path If your source is located somewhere else, you can specify the location of the source using the `package.build.source.path` field. For example if your package has the following structure: ```text my_package β”œβ”€β”€ pixi.toml └── source β”œβ”€β”€ src β”‚ └── my_code.cpp └── include └── my_code.h ``` You can specify the location of the source like this: ```toml [package.build.source] path = "source" ``` This will also work with relative paths: ```toml [package.build.source] path = "../my_other_source_directory" ``` This works great in combination with git submodules. ## Git If your source is hosted in a git repository, you can specify the repository URL using the `package.build.source.git` field. ```toml [package.build.source] git = "https://github.com/user/repo.git" ``` You can pin to a specific branch, tag, or revision: ```toml [package.build.source] git = "https://github.com/user/repo.git" branch = "main" ``` ```toml [package.build.source] git = "https://github.com/user/repo.git" tag = "v1.0.0" ``` ```toml [package.build.source] git = "https://github.com/user/repo.git" rev = "abc123" ``` If the source is located in a subdirectory of the repository, you can specify that as well: ```toml [package.build.source] git = "https://github.com/user/repo.git" tag = "v1.0.0" subdirectory = "packages/mypackage" ``` In this tutorial, we will show you how to create a simple Python package with pixi. To read more about how building packages work with Pixi see the [Getting Started](../getting_started/) guide. You might also want to check out the [documentation](../backends/pixi-build-python/) for the `pixi-build-python` backend. Warning `pixi-build` is a preview feature, and will change until it is stabilized. Please keep that in mind when you use it for your projects. ## 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: 1. manage Python packages and packages written in other languages in the same workspace 1. 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 `python_rich`, so we will create the following structure: ```shell β”œβ”€β”€ src # (1)! β”‚ └── python_rich β”‚ └── __init__.py └── pyproject.toml ``` 1. This project uses a src-layout, but Pixi supports both [flat- and src-layouts](https://packaging.python.org/en/latest/discussions/src-layout-vs-flat-layout/#src-layout-vs-flat-layout). The Python package has a single function `main`. Calling that, will print a table containing the name, age and city of three people. src/python_rich/__init__.py ```py from dataclasses import dataclass, fields from rich.console import Console from rich.table import Table @dataclass class Person: name: str age: int city: str def main() -> None: console = Console() people = [ Person("John Doe", 30, "New York"), Person("Jane Smith", 25, "Los Angeles"), Person("Tim de Jager", 35, "Utrecht"), ] table = Table() for column in fields(Person): table.add_column(column.name) for person in people: table.add_row(person.name, str(person.age), person.city) console.print(table) ``` The metadata of the Python package is defined in `pyproject.toml`. pyproject.toml ```toml [project] dependencies = ["rich"] # (1)! name = "python_rich" requires-python = ">= 3.11" scripts = { rich-example-main = "python_rich:main" } # (2)! version = "0.1.0" [build-system] # (3)! build-backend = "hatchling.build" requires = ["hatchling"] ``` 1. We use the `rich` package to print the table in the terminal. 1. 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 `python_rich` module. 1. 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](https://pypi.org/) 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 prepend `tool.pixi.` to each table. Let's initialize a Pixi project. ```text pixi init --format pixi ``` We pass `--format pixi` in order to communicate to pixi, that we want a `pixi.toml` rather than extending `pyproject.toml`. ```shell β”œβ”€β”€ src β”‚ └── python_rich β”‚ └── __init__.py β”œβ”€β”€ .gitignore β”œβ”€β”€ pixi.toml └── pyproject.toml ``` This is the content of the `pixi.toml`: pixi.toml ```toml [workspace] # (1)! channels = ["https://prefix.dev/conda-forge"] platforms = ["win-64", "linux-64", "osx-arm64", "osx-64"] preview = ["pixi-build"] [dependencies] # (2)! python_rich = { path = "." } [tasks] # (3)! start = "rich-example-main" [package] # (4)! name = "python_rich" version = "0.1.0" [package.build] # (5)! backend = { name = "pixi-build-python", version = "0.4.*" } [package.host-dependencies] # (6)! hatchling = "==1.26.3" [package.run-dependencies] # (7)! rich = "13.9.*" ``` 1. In `workspace` information is set that is shared across all packages in the workspace. 1. In `dependencies` you specify all of your Pixi packages. Here, this includes only our own package that is defined further below under `package` 1. We define a task that runs the `rich-example-main` executable we defined earlier. You can learn more about tasks in this [section](../../workspace/advanced_tasks/) 1. 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. 1. 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. 1. In `package.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. 1. In `package.run-dependencies`, we add the Python dependencies needed during runtime. When we now run `pixi run start`, we get the following output: ```text ┏━━━━━━━━━━━━━━┳━━━━━┳━━━━━━━━━━━━━┓ ┃ 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](https://twitter.com/prefix_dev), [join our Discord](https://discord.gg/kKV8ZxyzY4), send us an [e-mail](mailto:hi@prefix.dev) or follow our [GitHub](https://github.com/prefix-dev). This guide shows how to build a ROS package into a conda package with Pixi using the `pixi-build-ros` backend. To understand the build feature, start with the general [Build Getting Started](../getting_started/) guide. For ROS without Pixi building (not packaging), see the [ROS 2 tutorial](../../tutorials/ros2/). You may also want to read the backend documentation for [pixi-build-ros](../backends/pixi-build-ros/). Warning `pixi-build` is a preview feature and may change before stabilization. Expect rough edges; please report issues so we can improve it. ## Create a Pixi workspace Initialize a new workspace and install the ROS 2 CLI so you can scaffold packages via the `ros2` cli. ```bash pixi init ros_ws --channel https://prefix.dev/robostack-jazzy --channel https://prefix.dev/conda-forge cd ros_ws pixi add ros-jazzy-ros2run ``` This adds the `ros2` cli command to your Pixi environment. In all examples below, ensure the [build preview](../../reference/pixi_manifest/#preview-features) is enabled in your workspace manifest: ros_ws/pixi.toml ```toml preview = ["pixi-build"] ``` Resulting workspace manifest: ros_ws/pixi.toml ```toml [workspace] channels = [ "https://prefix.dev/robostack-jazzy", "https://prefix.dev/conda-forge", ] platforms = [ "osx-arm64", "win-64", "linux-64", ] # Your platform here, e.g. "linux-64", "osx-arm64", "win-64" preview = ["pixi-build"] [dependencies] ros-jazzy-ros2run = ">=0.32.4,<0.33" ``` ## Creating a Python ROS package We'll be creating a normal ROS2 package using `ament_python` and then adding Pixi support to it. Most of the logic is done by the ROS2 CLI, so you can follow normal ROS 2 package creation steps. ### Initialize a ROS package Use the ROS CLI to generate an `ament_python` package skeleton within the workspace. ```bash pixi run ros2 pkg create --build-type ament_python --destination-directory src --node-name my_python_node my_python_ros_pkg ``` You should now have something like: ```text ros_ws/ β”œβ”€β”€ pixi.toml └── src/ └── my_python_ros_pkg/ β”œβ”€β”€ package.xml β”œβ”€β”€ resource/ β”œβ”€β”€ setup.cfg β”œβ”€β”€ setup.py β”œβ”€β”€ test/ └── my_python_ros_pkg/ β”œβ”€β”€ __init__.py └── my_python_node.py ``` ### Add Pixi package info to the new package Create a `pixi.toml` inside `src/my_python_ros_pkg` so Pixi can build it using the ROS backend. The backend reads most metadata from `package.xml`, so you only need to specify the backend and distro. src/my_python_ros_pkg/pixi.toml ```toml [package.build.backend] channels = [ "https://prefix.dev/pixi-build-backends", "https://prefix.dev/conda-forge", ] name = "pixi-build-ros" version = "*" [package.build.config] distro = "jazzy" ``` Notes: - When `package.build.config.distro` is set, the produced package name is prefixed like `ros--`. - The backend automatically reads `package.xml` (name, version, license, maintainers, URLs, dependencies). Any explicitly set fields in `pixi.toml` override `package.xml`. - Dependencies in `package.xml` are mapped to conda packages via RoboStack (for example `std_msgs` β†’ `ros--std-msgs`). Unknown deps pass through unchanged. ### Add the package to the pixi workspace Tell the root workspace to depend on the package via a path dependency that matches the ROS-prefixed name: ros_ws/pixi.toml ```toml [dependencies] ros-jazzy-ros2run = ">=0.32.4,<0.33" ros-jazzy-my-python-ros-pkg = { path = "src/my_python_ros_pkg" } ``` ### Testing your package Now install and run: ```bash pixi run ros2 run my_python_ros_pkg my_python_node ``` Outputs: ```bash Hi from my_python_ros_pkg. ``` ## Create a CMake ROS package Creating a C++ or mixed package using `ament_cmake`. ### Scaffold a C++ package: ```bash pixi run ros2 pkg create --build-type ament_cmake --destination-directory src --node-name my_cmake_node my_cmake_ros_pkg ``` ### Add the pixi package info Create a `pixi.toml` inside `src/my_cmake_ros_pkg` so Pixi can build it using the ROS backend. The backend reads most metadata from `package.xml`, so you only need to specify the `backend` and `distro`. src/my_cmake_ros_pkg/pixi.toml ```toml [package.build.backend] channels = [ "https://prefix.dev/pixi-build-backends", "https://prefix.dev/conda-forge", ] name = "pixi-build-ros" version = "*" [package.build.config] distro = "jazzy" ``` ### Add the package to the pixi workspace Tell the root workspace to depend on the package via a path dependency that matches the ROS-prefixed name: ros_ws/pixi.toml ```toml [dependencies] ros-jazzy-ros2run = ">=0.32.4,<0.33" ros-jazzy-my-python-ros-pkg = { path = "src/my_python_ros_pkg" } ros-jazzy-my-cmake-ros-pkg = { path = "src/my_cmake_ros_pkg" } ``` ### Testing your package Now install and run: ```bash pixi run ros2 run my_cmake_ros_pkg my_cmake_node ``` Outputs: ```bash hello world my_cmake_ros_pkg package ``` ## Building a ROS conda package With the package(s) added to the workspace, you can now build them. ```bash cd src/my_python_ros_pkg pixi build # then cd ../my_cmake_ros_pkg pixi build ``` You can now upload these artifacts to a conda channel and depend on them from other Pixi workspaces. ## Tips and gotchas - ROS distro and platform: pick the correct RoboStack channel (e.g. `robostack-humble`, `robostack-jazzy`) and ensure your platform is supported. - Keep `package.xml` accurate: name, version, license, maintainers, URLs, and dependencies are read automatically; but you can override them in the [pixi manifest](https://pixi.sh/latest/reference/pixi_manifest/#the-package-section). - Backend docs: see the [pixi-build-ros documentation](../backends/pixi-build-ros/) for configuration details like `env`, `distro` and `extra-input-globs`. - Colcon vs pixi build: you don’t need `colcon` when using `pixi`; the backend invokes the right build flow. But since you don't have to change your package structure, you can still use `colcon` if you want. - Not all ROS packages are available in RoboStack. If you depend on a package not in RoboStack, you can: - **Recommended:** Contribute to RoboStack to add it; see the [RoboStack Contributing page](https://robostack.github.io/Contributing.html) - Package it yourself with Pixi in a separate workspace and upload it to your own conda channel. - Optionally, this could use an [out of tree package definition](../package_source/) to build the package without changing its source code. ## Conclusion You can package ROS projects as conda packages with Pixi using the `pixi-build-ros` backend. Start simple, keep `package.xml` truthful, add ROS dependencies as needed, and iterate with the preview build feature. Once built, you can upload artifacts to a conda channel and depend on them from other Pixi workspaces. In this tutorial, we will show you how to use variants in order to build a Pixi package against different versions of a dependency. Some might call this functionality, build matrix, build configurations or parameterized builds, in the conda ecosystem this is referred to as a variant. Warning `pixi-build` is a preview feature, and will change until it is stabilized. Please keep that in mind when you use it for your projects. ## Why is This Useful? When we depend on a Pixi package, the dependency versions of the package itself are already set. For example, in the [C++ tutorial](../cpp/) the `cpp_math` package we built depended on Python 3.12. Pixi would report a version conflict, if we'd add use both Python 3.11 and `cpp_math` to our workspace. By using variants, we can add a set of allowed versions for a specific dependency. Pixi will then resolve the package with all the different variants. ## Let's Get Started In this tutorial we will continue with the result of the [workspace tutorial](../workspace/) so we can test it against multiple Python versions. As a reminder, we ended up with a top-level `pixi.toml` containing the workspace and the Python package `python_rich`. Our workspace then depended on `python_rich` and `cpp_math`. pixi.toml ```toml [dependencies] python_rich = { path = "." } ``` The file tree looks like this: ```shell . β”œβ”€β”€ packages β”‚ └── cpp_math β”‚ β”œβ”€β”€ CMakeLists.txt β”‚ β”œβ”€β”€ pixi.toml β”‚ └── src β”‚ └── math.cpp β”œβ”€β”€ pixi.lock β”œβ”€β”€ pixi.toml β”œβ”€β”€ pyproject.toml └── src └── python_rich └── __init__.py ``` In order to allow multiple Python versions we first have to change the Python version requirement of `cpp_math` from `3.12.*` to `*`. packages/cpp_math/pixi.toml ```toml [package.host-dependencies] cmake = ">=3.20, <3.27" nanobind = ">=2.4.0, <2.5.0" python = "*" # (1)! ``` 1. Used to be "3.12.\*" Now, we have to specify the Python versions we want to allow. We do that in `workspace.build-variants`: pixi.toml ```toml [workspace.build-variants] python = ["3.11.*", "3.12.*"] ``` If we'd run `pixi install` now, we'd leave it up to Pixi whether to use Python 3.11 or 3.12. In practice, you'll want to create multiple environments specifying a different dependency version. In our case this allows us to test our setup against both Python 3.11 and 3.12. pixi.toml ```toml [feature.py311.dependencies] python = "3.11.*" [feature.py312.dependencies] python = "3.12.*" [environments] py311 = ["py311"] py312 = ["py312"] ``` By running `pixi list` we can see the Python version used in each environment. You can also see that the `Build` string of `cpp_math` differ between `py311` and `py312`. That means that a different package has been built for each variant. Since `python_rich` only contains Python source code, a single build can be used for multiple Python versions. The package is `noarch`. Therefore, the build string is the same. ```pwsh $ pixi list --environment py311 Package Version Build Size Kind Source python 3.11.11 h9e4cc4f_1_cpython 29.2 MiB conda python cpp_math 0.1.0 py311h43a39b2_0 conda cpp_math python_rich 0.1.0 pyhbf21a9e_0 conda python_rich ``` ```pwsh $ pixi list --environment py312 Package Version Build Size Kind Source python 3.12.8 h9e4cc4f_1_cpython 30.1 MiB conda python cpp_math 0.1.0 py312h2078e5b_0 conda cpp_math python_rich 0.1.0 pyhbf21a9e_0 conda python_rich ``` ## Conclusion In this tutorial, we showed how to use variants to build multiple versions of a single package. We built `cpp_math` for Python 3.12 and 3.13, which allows us to test whether it works properly on both Python versions. Variants are not limited to a single dependency, you could for example try to test multiple versions of `nanobind`. On top of adding variants inline, they can also be included as files. Check out the [reference](../../reference/pixi_manifest/#build-variants-files-optional) to learn more! Thanks for reading! Happy Coding πŸš€ Any questions? Feel free to reach out or share this tutorial on [X](https://twitter.com/prefix_dev), [join our Discord](https://discord.gg/kKV8ZxyzY4), send us an [e-mail](mailto:hi@prefix.dev) or follow our [GitHub](https://github.com/prefix-dev). In this tutorial, we will show you how to integrate multiple Pixi packages into a single workspace. Warning `pixi-build` is a preview feature, and will change until it is stabilized. Please keep that in mind when you use it for your projects. ## Why is This Useful? The packages coming from conda channels are already built and ready to use. If you want to depend on a package you therefore typically get that package from such a channel. However, there are situations where you want to depend on the source of a package. This is the case for example if you want to develop on multiple packages within the same repository. Or if you need the changes of an unreleased version of one of your dependencies. ## Let's Get Started In this tutorial we will showcase how to develop two packages in one workspace. For that we will use the `python_rich` Python package developed in chapter [Building a Python package](../python/) and let it depend on the `cpp_math` C++ package developed in chapter [Building a C++ package](../cpp/). We will start with the original setup of `python_rich` and copy `cpp_math` into a folder called `packages`. The source directory structure now looks like this: ```shell . β”œβ”€β”€ packages β”‚ └── cpp_math β”‚ β”œβ”€β”€ CMakeLists.txt β”‚ β”œβ”€β”€ pixi.toml β”‚ └── src β”‚ └── math.cpp β”œβ”€β”€ pixi.lock β”œβ”€β”€ pixi.toml β”œβ”€β”€ pyproject.toml └── src └── python_rich └── __init__.py ``` Within a Pixi manifest, you can manage a workspace and/or describe a package. In the case of `python_rich` we choose to do both, so the only thing we have to add `cpp_math` as a [run dependency](../../reference/pixi_manifest/#run-dependencies) of `python_rich`. pixi.toml ```py [package.run-dependencies] cpp_math = { path = "packages/cpp_math" } rich = "13.9.*" ``` We only want to use the `workspace` table of the top-level manifest. Therefore, we can remove the workspace section in the manifest of `cpp_math`. packages/cpp_math/pixi.toml ```diff -[workspace] -channels = ["https://prefix.dev/conda-forge"] -platforms = ["osx-arm64", "osx-64", "linux-64", "win-64"] -preview = ["pixi-build"] - -[dependencies] -cpp_math = { path = "." } - -[tasks] -start = "python -c 'import cpp_math as b; print(b.add(1, 2))'" ``` There is actually one problem with `python_rich`. The age of every person is off by one year! ```text ┏━━━━━━━━━━━━━━┳━━━━━┳━━━━━━━━━━━━━┓ ┃ name ┃ age ┃ city ┃ ┑━━━━━━━━━━━━━━╇━━━━━╇━━━━━━━━━━━━━┩ β”‚ John Doe β”‚ 30 β”‚ New York β”‚ β”‚ Jane Smith β”‚ 25 β”‚ Los Angeles β”‚ β”‚ Tim de Jager β”‚ 35 β”‚ Utrecht β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ ``` We need to add one year to the age of every person. Luckily `cpp_math` exposes a function `add` which allows us to do exactly that. src/python_rich/__init__.py ```py from dataclasses import dataclass, fields from rich.console import Console from rich.table import Table import cpp_math @dataclass class Person: name: str age: int city: str def main() -> None: console = Console() people = [ Person("John Doe", 30, "New York"), Person("Jane Smith", 25, "Los Angeles"), Person("Tim de Jager", 35, "Utrecht"), ] table = Table() for column in fields(Person): table.add_column(column.name) for person in people: updated_age = cpp_math.add(person.age, 1) table.add_row(person.name, str(updated_age), person.city) console.print(table) ``` If you run `pixi run start`, the age of each person should now be accurate: ```text ┏━━━━━━━━━━━━━━┳━━━━━┳━━━━━━━━━━━━━┓ ┃ name ┃ age ┃ city ┃ ┑━━━━━━━━━━━━━━╇━━━━━╇━━━━━━━━━━━━━┩ β”‚ John Doe β”‚ 31 β”‚ New York β”‚ β”‚ Jane Smith β”‚ 26 β”‚ Los Angeles β”‚ β”‚ Tim de Jager β”‚ 36 β”‚ Utrecht β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ ``` ## Conclusion In this tutorial, we created a Pixi workspace containing two packages. The manifest of `python_rich` describes the workspace as well as the package, with `cpp_math` only the `package` section is used. Feel free to add more packages, written in different languages to this workspace! Thanks for reading! Happy Coding πŸš€ Any questions? Feel free to reach out or share this tutorial on [X](https://twitter.com/prefix_dev), [join our Discord](https://discord.gg/kKV8ZxyzY4), send us an [e-mail](mailto:hi@prefix.dev) or follow our [GitHub](https://github.com/prefix-dev). # pixi-build-cmake The `pixi-build-cmake` backend is designed for building C and C++ projects using the [CMake](https://cmake.org/) build system. It provides seamless integration with Pixi's package management workflow while maintaining cross-platform compatibility. Warning `pixi-build` is a preview feature, and will change until it is stabilized. This is why we require users to opt in to that feature by adding "pixi-build" to `workspace.preview`. ```toml [workspace] preview = ["pixi-build"] ``` ## Overview This backend automatically generates conda packages from CMake-based projects by: - **Detecting and configuring compilers**: Automatically includes the appropriate C/C++ compilers for your target platform - **Building with Ninja**: Uses the fast Ninja build system for optimal build performance - **Cross-platform support**: Works consistently across Linux, macOS, and Windows - **Standard CMake workflow**: Follows CMake best practices with sensible defaults ## Basic Usage To use the CMake backend in your `pixi.toml`, add it to your package's build configuration: ```toml [package] name = "cmake_package" version = "0.1.0" [package.build] backend = { name = "pixi-build-cmake", version = "*" } channels = [ "https://prefix.dev/conda-forge", ] ``` ### Required Dependencies The backend automatically includes the following build tools: - `cmake` - The CMake build system - `ninja` - Fast build system used by CMake - Platform-specific C++ compilers (e.g., `gcc_linux-64`, `clang_osx-64`) You can add these to your [`build-dependencies`](https://pixi.sh/latest/build/dependency_types/) if you need specific versions: ```toml [package.build-dependencies] ninja = "1.13" ``` ## Configuration Options You can customize the CMake backend behavior using the `[package.build.config]` section in your `pixi.toml`. The backend supports the following configuration options: ### `extra-args` - **Type**: `Array` - **Default**: `[]` - **Target Merge Behavior**: `Overwrite` - Platform-specific arguments completely replace base arguments Additional command-line arguments to pass to the CMake configuration step. These arguments are inserted into the `cmake` command that configures your project. ```toml [package.build.config] extra-args = [ "-DENABLE_TESTING=ON", "-DCMAKE_CXX_STANDARD=17" ] ``` For target-specific configuration, platform arguments completely replace the base configuration: ```toml [package.build.config] extra-args = ["-DCMAKE_BUILD_TYPE=Release"] [package.build.target.linux-64.config] extra-args = ["-DCMAKE_BUILD_TYPE=Debug", "-DLINUX_FLAG=ON"] # Result for linux-64: ["-DCMAKE_BUILD_TYPE=Debug", "-DLINUX_FLAG=ON"] ``` ### `env` - **Type**: `Map` - **Default**: `{}` - **Target Merge Behavior**: `Merge` - Platform environment variables override base variables with same name, others are merged Environment variables to set during the build process. These variables are available to both the CMake configuration and build steps. ```toml [package.build.config] env = { CMAKE_VERBOSE_MAKEFILE = "ON", CXXFLAGS = "-O3 -march=native" } ``` For target-specific configuration, platform environment variables are merged with base variables: ```toml [package.build.config] env = { CMAKE_VERBOSE_MAKEFILE = "OFF", COMMON_VAR = "base" } [package.build.target.linux-64.config] env = { COMMON_VAR = "linux", LINUX_VAR = "value" } # Result for linux-64: { CMAKE_VERBOSE_MAKEFILE = "OFF", COMMON_VAR = "linux", LINUX_VAR = "value" } ``` ### `debug-dir` The backend always writes JSON-RPC request/response logs and the generated intermediate recipe to the `debug` subdirectory inside each work directory (for example `/debug`). The deprecated `debug-dir` configuration option is ignored; if it is present in a manifest a warning is emitted. ### `extra-input-globs` - **Type**: `Array` - **Default**: `[]` - **Target Merge Behavior**: `Overwrite` - Platform-specific globs completely replace base globs Additional glob patterns to include as input files for the build process. These patterns are added to the default input globs that include source files (`**/*.{c,cc,cxx,cpp,h,hpp,hxx}`), CMake files (`**/*.{cmake,cmake.in}`, `**/CMakeFiles.txt`), and other build-related files. ```toml [package.build.config] extra-input-globs = [ "assets/**/*", "config/*.ini", "*.md" ] ``` For target-specific configuration, platform-specific globs completely replace the base: ```toml [package.build.config] extra-input-globs = ["*.txt"] [package.build.target.linux-64.config] extra-input-globs = ["*.txt", "*.linux", "linux-configs/**/*"] # Result for linux-64: ["*.txt", "*.linux", "linux-configs/**/*"] ``` ### `compilers` - **Type**: `Array` - **Default**: `["cxx"]` - **Target Merge Behavior**: `Overwrite` - Platform-specific compilers completely replace base compilers List of compilers to use for the build. The backend automatically generates appropriate compiler dependencies using conda-forge's compiler infrastructure. ```toml [package.build.config] compilers = ["c", "cxx", "fortran"] ``` For target-specific configuration, platform compilers completely replace the base configuration: ```toml [package.build.config] compilers = ["cxx"] [package.build.target.linux-64.config] compilers = ["c", "cxx", "cuda"] # Result for linux-64: ["c", "cxx", "cuda"] ``` Comprehensive Compiler Documentation For detailed information about available compilers, platform-specific behavior, and how conda-forge compilers work, see the [Compilers Documentation](../../key_concepts/compilers/). ## Build Process The CMake backend follows this build process: 1. **Version Detection**: Displays CMake and Ninja versions for diagnostics 1. **Configuration**: Runs `cmake` with the following default options: - `-GNinja`: Use Ninja generator - `-DCMAKE_BUILD_TYPE=Release`: Release build by default - `-DCMAKE_INSTALL_PREFIX=$PREFIX`: Install to conda prefix - `-DCMAKE_EXPORT_COMPILE_COMMANDS=ON`: Export compile commands for tooling - `-DBUILD_SHARED_LIBS=ON`: Build shared libraries by default - `-DPython_EXECUTABLE=$PYTHON`: Use the conda Python executable if it's part of the host dependencies. 1. **Build**: Executes `cmake --build` to compile the project 1. **Install**: Installs the built artifacts to the conda package ## CMake Flag Precedence With CMake, when duplicate flags are provided, the last flag takes precedence. The `pixi-build-cmake` backend places `extra-args` after the default CMake flags, allowing you to override default settings. For example, to switch from the default Release build to Debug mode: ```toml [package.build.config] extra-args = ["-DCMAKE_BUILD_TYPE=Debug"] ``` ## Default variants On Windows platforms, the backend automatically sets the following default variants: - `c_compiler`: `vs2022` - Visual Studio 2022 C compiler - `cxx_compiler`: `vs2022` - Visual Studio 2022 C++ compiler These variants are used when you specify compilers in your [`[package.build.config.compilers]`](#compilers) configuration. Only `cxx_compiler` will be installed by default, the `c_compiler` is set to help when you would add that compiler. This default is set to align with conda-forge's switch to Visual Studio 2022 and because [mainstream support for Visual Studio 2019 ended in 2024](https://learn.microsoft.com/en-us/lifecycle/products/visual-studio-2019). The `vs2022` compiler is more widely supported on modern GitHub runners and build environments. You can override these defaults by explicitly setting variants using [`[workspace.build-variants]`](https://pixi.sh/latest/reference/pixi_manifest/#build-variants-optional) in your `pixi.toml`: ```toml [workspace.build-variants] c_compiler = ["vs2019"] cxx_compiler = ["vs2019"] ``` ## Limitations - Currently, assumes C++ projects (hardcoded to `cxx` language) - Language detection from CMakeLists.txt is not yet implemented ## See Also - [Building C++ Packages](https://pixi.sh/latest/build/cpp/) - Tutorial for building C++ packages with Pixi - [CMake Documentation](https://cmake.org/documentation/) - Official CMake documentation # pixi-build-mojo The `pixi-build-mojo` backend is designed for building Mojo projects. It provides seamless integration with Pixi's package management workflow. Warning `pixi-build` is a preview feature, and will change until it is stabilized. This is why we require users to opt in to that feature by adding "pixi-build" to `workspace.preview`. ```toml [workspace] preview = ["pixi-build"] ``` ## Overview This backend automatically generates conda packages from Mojo projects. The generated packages can be installed into local envs for development, or packaged for distribution. ### Auto-derive of pkg and bin The Mojo backend includes auto-discovery of your project structure and will derive the following: - **Binaries**: Automatically searches for `main.mojo` or `main.πŸ”₯` in: - `/main.mojo` - **Packages**: Automatically searches for directories with `__init__.mojo` or `__init__.πŸ”₯` in: - `//` - `/src/` This means in most cases, you don't need to explicitly configure the `bins` or `pkg` fields. **Caveats**: - If both a `bin` and a `pkg` are auto-derived, only the `bin` will be created, you must manually specify the pkg. - If the user specifies a `pkg` a `bin` will not be auto-derived. - If the user specifies a `bin` a `pkg` will not be auto-derived. ## Basic Usage To use the Mojo backend in your `pixi.toml`, add it to your package's build configuration. The backend will automatically discover your project structure: ```text # Example project layout for combined binary/library. . β”œβ”€β”€ greetings β”‚Β Β  β”œβ”€β”€ __init__.mojo β”‚Β Β  └── lib.mojo β”œβ”€β”€ main.mojo β”œβ”€β”€ pixi.lock β”œβ”€β”€ pixi.toml └── README.md ``` With the project structure above, pixi-build-mojo will automatically discover: - The binary from `main.mojo` - The package from `greetings/__init__.mojo` Here's a minimal configuration that leverages auto-derive: ```toml [workspace] authors = ["J. Doe "] platforms = ["linux-64"] preview = ["pixi-build"] channels = [ "https://prefix.dev/conda-forge", "https://conda.modular.com/max-nightly", "https://prefix.dev/modular-community" ] [package] name = "greetings" version = "0.1.0" [package.build] backend = { name = "pixi-build-mojo", version = "0.1.*" } [tasks] [package.host-dependencies] mojo-compiler = "=25.5.0" [package.build-dependencies] mojo-compiler = "=25.5.0" small_time = ">=25.4.1,<26" extramojo = ">=0.16.0,<0.17" [package.run-dependencies] mojo-compiler = "=25.5.0" [dependencies] # For running `mojo test` while developing add all dependencies under # `[package.build-dependencies]` here as well. greetings = { path = "." } ``` ### Project Structure Examples The auto-derive feature supports various common project layouts: #### Binary-only project ```text . β”œβ”€β”€ main.mojo # Auto-derive as binary β”œβ”€β”€ pixi.toml └── README.md ``` #### Package-only project ```text . β”œβ”€β”€ mypackage/ # Auto-derive if matches project name β”‚ β”œβ”€β”€ __init__.mojo β”‚ └── utils.mojo β”œβ”€β”€ pixi.toml └── README.md ``` #### Source directory layout ```text . β”œβ”€β”€ src/ β”‚ β”œβ”€β”€ __init__.mojo # Auto-derive as package β”‚ └── lib.mojo β”œβ”€β”€ pixi.toml └── README.md ``` #### Combined project (shown earlier) ```text . β”œβ”€β”€ greetings/ β”‚ β”œβ”€β”€ __init__.mojo # NOT auto-derived as package β”‚ └── lib.mojo β”œβ”€β”€ main.mojo # Auto-derived as binary β”œβ”€β”€ pixi.toml └── README.md ``` ### Required Dependencies - `mojo` / `mojo-compiler` package for both the compiler and linked runtime ## Configuration Options You can customize the Mojo backend behavior using the `[package.build.config]` section in your `pixi.toml`. The backend supports the following configuration options: #### `env` - **Type**: `Map` - **Default**: `{}` Environment variables to set during the build process. ```toml [package.build.config] env = { ASSERT = "all" } ``` #### `debug-dir` The backend always writes JSON-RPC request/response logs and the generated intermediate recipe to the `debug` subdirectory inside the work directory (for example `/debug`). The deprecated `debug-dir` configuration option is ignored; if present, the backend emits a warning to highlight that it no longer has any effect. #### `extra-input-globs` - **Type**: `Array` - **Default**: `[]` Additional globs to pass to pixi to discover if the package should be rebuilt. ```toml [package.build.config] extra-input-globs = ["**/*.c", "assets/**/*", "*.md"] ``` ### `compilers` - **Type**: `Array` - **Default**: `[]` - **Target Merge Behavior**: `Overwrite` - Platform-specific compilers completely replace base compilers List of compilers to use for the build. Compilers use conda-forge's standard compiler infrastructure. ```toml [package.build.config] compilers = ["c", "cxx"] ``` For target-specific configuration, platform compilers completely replace the base configuration: ```toml [package.build.config] compilers = [] [package.build.target.linux-64.config] compilers = ["c", "cuda"] # Result for linux-64: ["mojo", "c", "cuda"] ``` Comprehensive Compiler Documentation For detailed information about available compilers, platform-specific behavior, and how conda-forge compilers work, see the [Compilers Documentation](../../key_concepts/compilers/). Note that the mojo compiler has special behavior as described above. ### `bins` - **Type**: `Array` - **Default**: Auto-derived if not specified List of binary configurations to build. The created binary will be placed in the `$PREFIX/bin` dir and will be in the path after running `pixi install` assuming the package is listed as a dependency as in the example above. `pixi build` will create a conda package that includes the binary. **Auto-derive behavior:** - If `bins` is not specified, pixi-build-mojo will search for a `main.mojo` or `main.πŸ”₯` file in the project root - If found, it creates a binary with the name set to the project name - If a pkg has been manually configured, a bin will not be auto-derived and must be manually configured. #### `bins[].name` - **Type**: `String` - **Default**: Project name (with dashes converted to underscores) for the first binary The name of the binary executable to create. If not specified: - For the first binary in the list, defaults to the project name - For additional binaries, this field is required ```toml [[package.build.config.bins]] # name = "greet" # Optional for first binary, defaults to project name ``` #### `bins[].path` - **Type**: `String` (path) - **Default**: Auto-derived for the first binary The path to the Mojo file that contains a `main` function. If not specified: - For the first binary, searches for `main.mojo` or `main.πŸ”₯` in the project root - For additional binaries, this field is required ```toml [[package.build.config.bins]] # path = "./main.mojo" # Optional if main.mojo exists in project root ``` #### `bins[].extra-args` - **Type**: `Array` - **Default**: `[]` Additional command-line arguments to pass to the Mojo compiler when building this binary. ```toml [[package.build.config.bins]] extra-args = ["-I", "special-thing"] ``` ### `pkg` - **Type**: `PkgConfig` - **Default**: Auto-derived if not specified Package configuration for creating Mojo package. The created Mojo package will be placed in the `$PREFIX/lib/mojo` dir, which will make it discoverable to anything that depends on the package. **Auto-derive behavior:** - If `pkg` is not specified, pixi-build-mojo will search for a directory containing `__init__.mojo` or `__init__.πŸ”₯` in the following order: 1. `//` 1. `/src/` - If found, it creates a package with the name set to the project name - If no valid package directory is found, no package is built - If a binary is manually configured, a pkg will not be auto-derived and must be manually specified. - If a binary is also auto-derive, a pkg will not be generated and must be manually specified #### `pkg.name` - **Type**: `String` - **Default**: Project name (with dashes converted to underscores) The name to give the Mojo package. The `.mojopkg` suffix will be added automatically. If not specified, defaults to the project name. ```toml [package.build.config.pkg] name = "greetings" ``` #### `pkg.path` - **Type**: `String` (path) - **Default**: Auto-derive The path to the directory that constitutes the package. If not specified, searches for a directory with `__init__.mojo` or `__init__.πŸ”₯` as described above. ```toml [package.build.config.pkg] path = "greetings" ``` #### `pkg.extra-args` - **Type**: `Array` - **Default**: `[]` Additional command-line arguments to pass to the Mojo compiler when building this package. ```toml [package.build.config.pkg] extra-args = ["-I", "special-thing"] ``` ## Default Variants On Windows platforms, the backend automatically sets the following default variants: - `c_compiler`: `vs2022` - Visual Studio 2022 C compiler - `cxx_compiler`: `vs2022` - Visual Studio 2022 C++ compiler These variants are used when you specify compilers in your [`[package.build.config.compilers]`](#compilers) configuration. Note that setting these default variants does not automatically add compilers to your build - you still need to explicitly configure which compilers to use. This default is set to align with conda-forge's switch to Visual Studio 2022 and because [mainstream support for Visual Studio 2019 ended in 2024](https://learn.microsoft.com/en-us/lifecycle/products/visual-studio-2019). The `vs2022` compiler is more widely supported on modern GitHub runners and build environments. You can override these defaults by explicitly setting variants using [`[workspace.build-variants]`](https://pixi.sh/latest/reference/pixi_manifest/#build-variants-optional) in your `pixi.toml`: ```toml [workspace.build-variants] c_compiler = ["vs2019"] cxx_compiler = ["vs2019"] ``` ## See Also - [Mojo Pixi Basic](https://docs.modular.com/pixi/) - [Modular Community Packages](https://github.com/modular/modular-community) # pixi-build-python The `pixi-build-python` backend is designed for building Python projects using standard Python packaging tools. It provides seamless integration with Pixi's package management workflow while supporting both [PEP 517](https://peps.python.org/pep-0517/) and [PEP 518](https://peps.python.org/pep-0518/) compliant projects. Warning `pixi-build` is a preview feature, and will change until it is stabilized. This is why we require users to opt in to that feature by adding "pixi-build" to `workspace.preview`. ```toml [workspace] preview = ["pixi-build"] ``` ## Overview This backend automatically generates conda packages from Python projects by: - **PEP 517/518 compliance**: Works with modern Python packaging standards including `pyproject.toml` - **PyPI-to-conda mapping** (opt-in): Maps `project.dependencies` and `build-system.requires` from `pyproject.toml` to conda packages (see [`ignore-pypi-mapping`](#ignore-pypi-mapping)) - **Automatic compiler detection**: Detects build tools like `maturin` or `setuptools-rust` and automatically adds required compilers - **Cross-platform support**: Works consistently across Linux, macOS, and Windows - **Flexible installation**: Automatically selects between `pip` and `uv` for package installation ## Basic Usage To use the Python backend in your `pixi.toml`, add it to your package's build configuration: ```toml [package] name = "python_package" version = "0.1.0" [package.build] backend = { name = "pixi-build-python", version = "*" } channels = ["https://prefix.dev/conda-forge"] ``` ### Required Dependencies The backend automatically includes the following build tools: - `python` - The Python interpreter - `pip` - Python package installer (or `uv` if specified) You can add these to your [`host-dependencies`](https://pixi.sh/latest/build/dependency_types/) if you need specific versions: ```toml [package.build-dependencies] python = "3.11" ``` The backend will be automatically selected by the automatic PyPI dependency mapping feature if you have `pyproject.toml` in your source directory. Otherwise, you need to explicitly add it to your package definition in the `[host-dependencies]`: ```toml [package.host-dependencies] hatchling = "*" ``` ## Configuration Options You can customize the Python backend behavior using the `[package.build.config]` section in your `pixi.toml`. The backend supports the following configuration options: ### `noarch` - **Type**: `Boolean` - **Default**: `true` (unless [compilers](#compilers) are specified) - **Target Merge Behavior**: `Overwrite` - Platform-specific noarch setting takes precedence over base Controls whether to build a platform-independent (noarch) package or a platform-specific package. The backend tries to derive whether the package can be built as `noarch` based on the presence of [compilers](#compilers). If compilers are specified, the backend assume that native extensions are build as part of the build process. Most of the time these are platform-specific, so the package will be built as a platform-specific package. If no compilers are specified, the default value for `noarch` is `true`, meaning the package will be built as a noarch python package. ```toml [package.build.config] noarch = false # Build platform-specific package ``` For target-specific configuration, platform-specific noarch setting overrides the base: ```toml [package.build.config] noarch = true [package.build.target.win-64.config] noarch = false # Windows needs platform build # Result for win-64: false ``` ### `env` - **Type**: `Map` - **Default**: `{}` - **Target Merge Behavior**: `Merge` - Platform environment variables override base variables with same name, others are merged Environment variables to set during the build process. These variables are available during package installation. ```toml [package.build.config] env = { SETUPTOOLS_SCM_PRETEND_VERSION = "1.0.0" } ``` For target-specific configuration, platform environment variables are merged with base variables: ```toml [package.build.config] env = { PYTHONPATH = "/base/path", COMMON_VAR = "base" } [package.build.target.win-64.config] env = { COMMON_VAR = "windows", WIN_SPECIFIC = "value" } # Result for win-64: { PYTHONPATH = "/base/path", COMMON_VAR = "windows", WIN_SPECIFIC = "value" } ``` ### `debug-dir` The backend always writes JSON-RPC request/response logs and the generated intermediate recipe to the `debug` subdirectory inside the work directory (for example `/debug`). The deprecated `debug-dir` configuration option is ignored; if present, a warning is emitted to highlight that the setting no longer has any effect. ### `extra-input-globs` - **Type**: `Array` - **Default**: `[]` - **Target Merge Behavior**: `Overwrite` - Platform-specific globs completely replace base globs Additional glob patterns to include as input files for the build process. These patterns are added to the default input globs that include Python source files, configuration files (`setup.py`, `pyproject.toml`, etc.), and other build-related files. ```toml [package.build.config] extra-input-globs = [ "data/**/*", "templates/*.html", "*.md" ] ``` For target-specific configuration, platform-specific globs completely replace the base: ```toml [package.build.config] extra-input-globs = ["*.py"] [package.build.target.win-64.config] extra-input-globs = ["*.py", "*.dll", "*.pyd", "windows-resources/**/*"] # Result for win-64: ["*.py", "*.dll", "*.pyd", "windows-resources/**/*"] ``` ### `compilers` - **Type**: `Array` - **Default**: `[]` (no compilers) - **Target Merge Behavior**: `Overwrite` - Platform-specific compilers completely replace base compilers List of compilers to use for the build. Most pure Python packages don't need compilers, but this is useful for packages with C extensions or other compiled components. The backend automatically generates appropriate compiler dependencies using conda-forge's compiler infrastructure. ```toml [package.build.config] compilers = ["c", "cxx"] ``` For target-specific configuration, platform compilers completely replace the base configuration: ```toml [package.build.config] compilers = [] [package.build.target.win-64.config] compilers = ["c", "cxx"] # Result for win-64: ["c", "cxx"] (only on Windows) ``` Pure Python vs. Extension Packages The Python backend defaults to no compilers (`[]`) since most Python packages are pure Python and don't need compilation. This is different from other backends like CMake which default to `["cxx"]`. Only specify compilers if your package has C extensions or other compiled components: ```toml # Pure Python package (default behavior) [package.build.config] # No compilers needed - defaults to [] # Python package with C extensions [package.build.config] compilers = ["c", "cxx"] ``` Automatic Compiler Detection The backend automatically detects compilers required by certain build tools in your `build-system.requires`. For example: - `maturin` β†’ "rust" - `setuptools-rust` β†’ "rust" These detected compilers are merged with any explicitly configured compilers. You only need to manually specify compilers if your package uses build tools that aren't auto-detected. Comprehensive Compiler Documentation For detailed information about available compilers, platform-specific behavior, and how conda-forge compilers work, see the [Compilers Documentation](../../key_concepts/compilers/). ### `abi3` - **Type**: `Boolean` - **Default**: `false` - **Target Merge Behavior**: `Overwrite` - Platform-specific setting takes precedence over base Controls whether the package uses the [Python Stable ABI (abi3)](https://docs.python.org/3/c-api/stable.html). When set to `true`, a `python_abi` dependency is added to the host requirements with version bounds derived from `requires-python` in your `pyproject.toml`. The `python_abi` package has `run_exports` that automatically propagate the ABI constraint to the run environment, so only a host dependency is needed. ```toml [package.build.config] abi3 = true compilers = ["c"] ``` The version bounds are computed from the lower bound of `requires-python`: - `requires-python = ">=3.9"` β†’ `python_abi >=3.9,<3.10.0a0` - `requires-python = ">=3.11,<4"` β†’ `python_abi >=3.11,<3.12.0a0` - If `requires-python` is not specified, defaults to `python_abi >=3.8,<3.9.0a0` Incompatible with noarch Setting `abi3 = true` with `noarch = true` will produce an error, since the stable ABI is only meaningful for packages with compiled extensions. ### `extra-args` - **Type**: `Array` - **Default**: `[]` - **Target Merge Behavior**: `Overwrite` - Platform-specific globs completely replace base globs Extra arguments to pass to `pip`. A use-case could be [`pip`'s `--config-settings` parameter](https://pip.pypa.io/en/stable/cli/pip_install/#cmdoption-C). ```toml [package.build.config] extra-args = ["-Cbuilddir=mybuilddir"] ``` For target-specific configuration, platform-specific globs completely replace the base: ```toml [package.build.config] extra-args = ["-Cbuilddir=mybuilddir"] [package.build.target.win-64.config] extra-args = ["-Cbuilddir=foo"] # Result for win-64: ["-Cbuilddir=foo"] ``` ### `ignore-pyproject-manifest` - **Type**: `Boolean` - **Default**: `false` - **Target Merge Behavior**: `Overwrite` - Platform-specific setting takes precedence over base Controls whether to ignore the `pyproject.toml` manifest file and rely solely on the project model for package metadata. When set to `true`, the backend will not extract metadata (name, version, description, license, URLs) from `pyproject.toml` and will use only the information provided in the Pixi project model. ```toml [package.build.config] ignore-pyproject-manifest = true # Ignore pyproject.toml metadata ``` This option is useful when you want complete control over package metadata through the Pixi project configuration, or when the `pyproject.toml` contains metadata that conflicts with your conda package requirements. For target-specific configuration, platform-specific setting overrides the base: ```toml [package.build.config] ignore-pyproject-manifest = false [package.build.target.win-64.config] ignore-pyproject-manifest = true # Ignore pyproject.toml on Windows only # Result for win-64: true ``` Metadata Extraction from pyproject.toml By default (when `ignore-pyproject-manifest` is `false`), the backend automatically extracts package metadata from your `pyproject.toml` file, including: - **name**: Package name from `project.name` - **version**: Package version from `project.version` - **description/summary**: From `project.description` - **license**: From `project.license` (supports text, file, or SPDX formats) - **homepage**: From `project.urls.Homepage` - **repository**: From `project.urls.Repository`, `project.urls.Source`, or `project.urls."Source Code"` - **documentation**: From `project.urls.Documentation` or `project.urls.Docs` This metadata is automatically included in the generated conda recipe. The `pyproject.toml` file itself is also added to the input globs for incremental build detection. ### `ignore-pypi-mapping` - **Type**: `Boolean` - **Default**: `true` - **Target Merge Behavior**: `Overwrite` - Platform-specific setting takes precedence over base Controls whether to ignore the automatic PyPI-to-conda dependency mapping feature. When set to `true` (the default), dependencies from `pyproject.toml` will not be automatically mapped to conda packages. Set to `false` to enable automatic mapping. ```toml [package.build.config] ignore-pypi-mapping = false # Enable automatic PyPI-to-conda mapping ``` Default Behavior This option currently defaults to `true` (mapping disabled) to avoid breaking existing setups. In a future release, the default will change to `false` (mapping enabled). If you want to opt-in to automatic dependency mapping now, explicitly set `ignore-pypi-mapping = false`. For target-specific configuration, platform-specific setting overrides the base: ```toml [package.build.config] ignore-pypi-mapping = false [package.build.target.win-64.config] ignore-pypi-mapping = true # Disable mapping on Windows only # Result for win-64: true ``` ## Automatic PyPI Dependency Mapping The Python backend can automatically map PyPI dependencies from your `pyproject.toml` to their corresponding conda packages. This means you don't need to manually duplicate your dependencies in both `pyproject.toml` and `pixi.toml`. Opt-in Feature This feature is currently disabled by default. To enable automatic PyPI-to-conda dependency mapping, set `ignore-pypi-mapping = false` in your build configuration: ```toml [package.build.config] ignore-pypi-mapping = false ``` ### How It Works The backend reads dependencies from two sources in your `pyproject.toml`: 1. **`project.dependencies`** β†’ Added to conda **run** dependencies 1. **`build-system.requires`** β†’ Added to conda **host** dependencies For each PyPI package, the backend queries a mapping service to find the corresponding conda-forge package name. The mapping is cached locally for 24 hours to improve performance. ### Example Given this `pyproject.toml`: ```toml [project] name = "my-package" version = "1.0.0" dependencies = [ "requests>=2.28", "pydantic>=2.0,<3.0", ] [build-system] requires = ["hatchling"] build-backend = "hatchling.build" ``` The backend automatically adds: - `requests >=2.28` and `pydantic >=2.0,<3.0` to run dependencies - `hatchling` to host dependencies ### Precedence Rules Dependencies specified in your `pixi.toml` take precedence over those inferred from `pyproject.toml`: - If you specify `requests = ">=2.30"` in `[package.run-dependencies]`, it will override the `requests>=2.28` from `pyproject.toml` - Dependencies not in `pixi.toml` are added from `pyproject.toml` This allows you to: - Use `pyproject.toml` as the single source of truth for most dependencies - Override specific packages in `pixi.toml` when you need different versions or conda-specific packages ### Limitations - **Environment markers** (e.g., `requests>=2.28; python_version >= "3.8"`) are only partially supported. At the moment, only `platform_system`, `os_name`, `platform_machine` and `sys_platforms` are currently checked. - **URL-based dependencies** (e.g., `package @ https://...`) are skipped - Packages without a conda-forge mapping are logged as warnings and skipped ## Build Process The Python backend follows this build process: 1. **Installer Detection**: Automatically chooses between `uv` and `pip` based on available dependencies 1. **Environment Setup**: Configures Python environment variables for the build 1. **Package Installation**: Executes the selected installer with the following options: - `--no-deps`: Don't install dependencies (handled by conda) - `--no-build-isolation`: Use the conda environment for building - `-vv`: Verbose output for debugging 1. **Package Creation**: Creates either a noarch or platform-specific conda package ## Installer Selection The backend automatically detects which Python installer to use: - **uv**: Used if `uv` is present in the build or host dependencies - **pip**: Used as the default fallback installer To use `uv` for faster installations, add it to your dependencies: ```toml [package.host-dependencies] uv = "*" ``` # Editable Installations Until profiles are implemented, editable installations are not easily configurable. This is the current behaviour: - `editable` is `true` when installing the package (e.g. with `pixi install`) - `editable` is `false` when building the package (e.g. with `pixi build`) - Set environment variable `BUILD_EDITABLE_PYTHON` to `true` or `false` to enforce a certain behavior ## Default Variants On Windows platforms, the backend automatically sets the following default variants: - `c_compiler`: `vs2022` - Visual Studio 2022 C compiler - `cxx_compiler`: `vs2022` - Visual Studio 2022 C++ compiler These variants are used when you specify compilers in your [`[package.build.config.compilers]`](#compilers) configuration. Note that setting these default variants does not automatically add compilers to your build - you still need to explicitly configure which compilers to use. This default is set to align with conda-forge's switch to Visual Studio 2022 and because [mainstream support for Visual Studio 2019 ended in 2024](https://learn.microsoft.com/en-us/lifecycle/products/visual-studio-2019). The `vs2022` compiler is more widely supported on modern GitHub runners and build environments. You can override these defaults by explicitly setting variants using [`[workspace.build-variants]`](https://pixi.sh/latest/reference/pixi_manifest/#build-variants-optional) in your `pixi.toml`: ```toml [workspace.build-variants] c_compiler = ["vs2019"] cxx_compiler = ["vs2019"] ``` ## Limitations - Requires a PEP 517/518 compliant Python project with `pyproject.toml` - Limited support for complex build customization compared to direct recipe-based approaches - Limited ways to configure editable installations ## See Also - [Building Python Packages](https://pixi.sh/latest/build/python/) - Tutorial for building Python packages with Pixi - [Python Packaging User Guide](https://packaging.python.org/) - Official Python packaging documentation - [PEP 517](https://peps.python.org/pep-0517/) - A build-system independent format for source trees # pixi-build-r The `pixi-build-r` backend is designed for building R packages using `R CMD INSTALL`. It automatically parses the `DESCRIPTION` file to extract metadata and dependencies, and detects whether native code compilation is needed. Warning `pixi-build` is a preview feature, and will change until it is stabilized. This is why we require users to opt in to that feature by adding "pixi-build" to `workspace.preview`. ```toml [workspace] preview = ["pixi-build"] ``` ## Overview This backend automatically generates conda packages from R projects by: - **DESCRIPTION parsing**: Reads package metadata, dependencies (`Imports`, `Depends`, `LinkingTo`), and license information from the standard R `DESCRIPTION` file - **Automatic compiler detection**: Detects native code by checking for a `src/` directory or `LinkingTo` fields, and adds C, C++, and Fortran compilers automatically - **Dependency mapping**: Converts R package names to conda-forge names (e.g., `curl` becomes `r-curl`, `R6` becomes `r-r6`) - **Cross-platform support**: Generates platform-appropriate build scripts for Linux, macOS, and Windows ## Basic Usage To use the R backend in your `pixi.toml`, add it to your package's build configuration: ```toml [workspace] channels = ["https://prefix.dev/conda-forge"] platforms = ["linux-64", "osx-arm64", "win-64"] preview = ["pixi-build"] [package] name = "r-mypackage" version = "1.0.0" [package.build] backend = { name = "pixi-build-r", version = "*" } channels = ["https://prefix.dev/conda-forge"] ``` Your R package should have a standard `DESCRIPTION` file in the project root: ```text Package: mypackage Version: 1.0.0 Title: My R Package Description: A short description of the package. License: MIT Imports: dplyr (>= 1.0), ggplot2 ``` ### Required Dependencies The backend automatically includes the following dependencies: - `r-base` - The R runtime (added to both host and run dependencies) Dependencies listed in `Imports`, `Depends`, and `LinkingTo` fields of the `DESCRIPTION` file are automatically converted to conda packages and added to the recipe. You can add additional dependencies to your [`host-dependencies`](https://pixi.sh/latest/build/dependency_types/) if needed: ```toml [package.host-dependencies] r-base = ">=4.1" ``` ## Configuration Options You can customize the R backend behavior using the `[package.build.config]` section in your `pixi.toml`. The backend supports the following configuration options: ### `extra-args` - **Type**: `Array` - **Default**: `[]` - **Target Merge Behavior**: `Overwrite` - Platform-specific args completely replace base args Extra arguments to pass to `R CMD INSTALL`. ```toml [package.build.config] extra-args = ["--no-multiarch", "--no-test-load"] ``` For target-specific configuration, platform-specific args completely replace the base: ```toml [package.build.config] extra-args = ["--no-multiarch"] [package.build.target.win-64.config] extra-args = ["--no-multiarch", "--no-test-load"] # Result for win-64: ["--no-multiarch", "--no-test-load"] ``` ### `env` - **Type**: `Map` - **Default**: `{}` - **Target Merge Behavior**: `Merge` - Platform environment variables override base variables with same name, others are merged Environment variables to set during the build process. These variables are available during `R CMD INSTALL`. ```toml [package.build.config] env = { R_LIBS_USER = "$PREFIX/lib/R/library" } ``` For target-specific configuration, platform environment variables are merged with base variables: ```toml [package.build.config] env = { COMMON_VAR = "base" } [package.build.target.win-64.config] env = { COMMON_VAR = "windows", WIN_SPECIFIC = "value" } # Result for win-64: { COMMON_VAR = "windows", WIN_SPECIFIC = "value" } ``` ### `extra-input-globs` - **Type**: `Array` - **Default**: `[]` - **Target Merge Behavior**: `Overwrite` - Platform-specific globs completely replace base globs Additional glob patterns to include as input files for the build process. These patterns are added to the default input globs that include R source files, documentation, and build-related files. ```toml [package.build.config] extra-input-globs = [ "inst/**/*", "data/**/*", "vignettes/**/*" ] ``` ### `compilers` - **Type**: `Array` - **Default**: Auto-detected (see below) - **Target Merge Behavior**: `Overwrite` - Platform-specific compilers completely replace base compilers List of compilers to use for the build. By default, the backend auto-detects whether compilers are needed by checking for: 1. A `src/` directory in the package root 1. A `LinkingTo` field in the `DESCRIPTION` file If either is found, compilers default to `["c", "cxx", "fortran"]`. Otherwise, no compilers are added. ```toml [package.build.config] compilers = ["c", "cxx"] # Override auto-detection ``` For target-specific configuration, platform compilers completely replace the base configuration: ```toml [package.build.config] compilers = ["c"] [package.build.target.win-64.config] compilers = ["c", "cxx", "fortran"] # Result for win-64: ["c", "cxx", "fortran"] ``` Auto-Detection Behavior Unlike the Python backend which defaults to no compilers, the R backend actively inspects your package structure. Packages with a `src/` directory or `LinkingTo` dependencies automatically get C, C++, and Fortran compilers. Pure R packages (no `src/`, no `LinkingTo`) get no compilers. You can override this by explicitly setting the `compilers` option: ```toml # Force no compilers even if src/ exists [package.build.config] compilers = [] # Only use C compiler [package.build.config] compilers = ["c"] ``` Comprehensive Compiler Documentation For detailed information about available compilers, platform-specific behavior, and how conda-forge compilers work, see the [Compilers Documentation](../../key_concepts/compilers/). ### `channels` - **Type**: `Array` - **Default**: `["conda-forge"]` - **Target Merge Behavior**: `Overwrite` - Platform-specific channels completely replace base channels Channels to use for resolving R package dependencies. ```toml [package.build.config] channels = ["conda-forge", "r"] ``` ## Dependency Handling ### Automatic Dependency Parsing The backend reads dependencies from the `DESCRIPTION` file: - **`Imports`** and **`Depends`** fields are added to both host and run dependencies - **`LinkingTo`** fields are added to host dependencies only (compile-time headers) - R version constraints are converted to conda format (e.g., `(>= 1.5)` becomes `>=1.5`) - R package names are converted to conda names with the `r-` prefix (e.g., `dplyr` becomes `r-dplyr`) ### Built-in Packages Packages that are included with R (such as `stats`, `utils`, `base`, `methods`, `Matrix`, `MASS`, etc.) are automatically filtered out and not added as separate dependencies. ## Build Process The R backend follows this build process: 1. **DESCRIPTION Parsing**: Reads package metadata and dependencies from the `DESCRIPTION` file 1. **Compiler Detection**: Auto-detects or uses configured compilers based on package structure 1. **Recipe Generation**: Creates a conda recipe with all dependencies converted to conda format 1. **Build Script**: Generates a platform-appropriate script that: - Prints R version information for debugging - Creates the R library directory - Runs `R CMD INSTALL --library= --no-lock ` 1. **Package Creation**: Creates a platform-specific conda package ## Limitations - Requires a standard R `DESCRIPTION` file in the project root - The `DESCRIPTION` file must use the DCF (Debian Control File) format - `Suggests` and `Enhances` dependencies are not automatically included - License mapping from CRAN format to SPDX is best-effort ## See Also - [Build Backends Overview](../) - Overview of all available build backends - [Compilers](../../key_concepts/compilers/) - How pixi-build integrates with conda-forge's compiler infrastructure - [CRAN](https://cran.r-project.org/) - The Comprehensive R Archive Network # Rattler-Build Backend The `pixi-build-rattler-build` backend enables building conda packages using rattler-build recipes. This backend is designed for projects that either have existing recipe.yaml files or where customization is necessary that isn't possible with the currently available backends. Warning `pixi-build` is a preview feature, and will change until it is stabilized. This is why we require users to opt in to that feature by adding "pixi-build" to `workspace.preview`. ```toml [workspace] preview = ["pixi-build"] ``` ## Overview The rattler-build backend: - Uses existing `recipe.yaml` files as build manifests - Supports all standard rattler-build recipe features and selectors - Handles dependency resolution and virtual package detection automatically - Can build multiple outputs from a single recipe ## Usage To use the rattler-build backend in your `pixi.toml`, specify it in your build system configuration: ```toml [package] name = "rattler_build_package" version = "0.1.0" [package.build] backend = { name = "pixi-build-rattler-build", version = "*" } channels = ["https://prefix.dev/conda-forge"] ``` The backend expects a rattler-build recipe file in one of these locations (searched in order): 1. `package.build.config.recipe` if given. 1. `recipe.yaml` or `recipe.yml` in the same directory as the package manifest 1. `recipe/recipe.yaml` or `recipe/recipe.yml` in a subdirectory of the package manifest If the package is defined in the same location as the workspace, it is heavily encouraged to place the recipe file in its own directory `recipe`. Learn more about the `rattler-build`, and its recipe format in its [high level overview](https://rattler.build/latest/highlevel). Warning If you expect your build script to be compatible with incremental compilation (re-using files from previous builds to speed-up future builds), you must ensure that the build directory for these files is set outside of the root directory in order to enable the incremental compilation. This is because we use a clean root directory for each build, to ensure compatibility with recipes which make that assumption. In practice, this may look like changing directory to `../build_dir` in your build script before commencing the build, or passing `../build_dir` as an argument to your build system. ## Specifying dependencies We only allow source dependencies (workspace packages) in project manifest. Binary dependencies are not allowed in the project manifest when using `pixi-build-rattler-build`. This is intentional because: 1. The rattler-build recipe is the source of truth for binary dependencies. It already specifies exact versions, build variants, and whether dependencies go in build/host/run. 1. Allowing binary dependencies in both places would create duplication and potential conflicts (e.g., recipe says "python >=3.10" but project model says "python >=3.9"). 1. Source dependencies are different - they represent workspace packages built from local source. The recipe can reference them by name, but can't know their workspace paths. The project model provides this mapping. This way, the recipe maintains full control over binary dependencies while the project model only provides the workspace structure information that the recipe cannot know. To specify source dependencies, add them to `build-dependencies`, `host-dependencies` or `run-dependencies` in the package manifest: pixi.toml ```toml [package.build-dependencies] a = { path = "../a" } ``` ## Configuration Options The rattler-build backend supports the following TOML configuration options: ### `experimental` - **Type**: `Boolean` - **Default**: `false` - **Target Merge Behavior**: Not allowed - must be set at root level only Enables experimental features in rattler-build. This is required for certain advanced features like the `cache:` functionality for multi-output recipes. ```toml [package.build.config] experimental = true ``` Note: This option cannot be set in target-specific configurations. It must be set at the root `[package.build.config]` level only. ### `recipe` - **Type**: `String` (path) - **Default**: checks for `recipe.yaml`, `recipe.yml`, `recipe/recipe.yaml`, `recipe/recipe.yml` in order. - **Target Merge Behavior**: Not allowed - must be set at root level only Path to the recipe YAML file. ```toml [package.build.config] recipe = "../template/recipe.yaml" ``` Note: This option cannot be set in target-specific configurations. It must be set at the root `[package.build.config]` level only. ### `debug-dir` The backend always writes JSON-RPC request/response logs and the generated intermediate recipe to the `debug` subdirectory inside the work directory (for example `/debug`). The deprecated `debug-dir` configuration option is ignored; if it is still set in a manifest the backend emits a warning to make the change explicit. ### `extra-input-globs` - **Type**: `Array` - **Default**: `[]` - **Target Merge Behavior**: `Overwrite` - Platform-specific globs completely replace base globs Additional glob patterns to include as input files for the build process. These patterns are added to the default input globs that are determined from the recipe sources and package directory structure. ```toml [package.build.config] extra-input-globs = [ "patches/**/*", "scripts/*.sh", "*.md" ] ``` For target-specific configuration, platform-specific globs completely replace the base: ```toml [package.build.config] extra-input-globs = ["*.yaml", "*.md"] [package.build.target.linux-64.config] extra-input-globs = ["*.yaml", "*.md", "*.sh", "patches-linux/**/*"] # Result for linux-64: ["*.yaml", "*.md", "*.sh", "patches-linux/**/*"] ``` ## Build Process The rattler-build backend follows this build process: 1. **Recipe Discovery**: Locates the `recipe.yaml` file in standard locations 1. **Dependency Resolution**: Resolves build, host, and run dependencies from conda channels and workspace 1. **Virtual Package Detection**: Automatically detects system virtual packages 1. **Build Execution**: Runs the build script specified in the recipe 1. **Package Creation**: Creates conda packages according to the recipe specification ## Limitations - Requires an existing rattler-build recipe file - cannot infer build instructions automatically - Build configuration is primarily controlled through the recipe file rather than `pixi.toml` - Cannot specify binary dependencies in the manifest # pixi-build-ros The `pixi-build-ros` backend is designed for building [ROS (Robot Operating System)](https://www.ros.org/) packages using the native ROS build systems. No more requirement to use `colcon` or `catkin_tools` to build your ROS packages. It provides seamless integration with Pixi's package management workflow while supporting ROS1 and ROS2 packages with automatic dependency resolution. Warning `pixi-build` is a preview feature, and will change until it is stabilized. This is why we require users to opt in to that feature by adding "pixi-build" to `workspace.preview`. ```toml [workspace] preview = ["pixi-build"] ``` ## Overview This backend automatically generates conda packages from ROS projects by: - **package.xml Integration**: Automatically reads package metadata (name, version, description, maintainers, dependencies) from your ROS `package.xml` file - **Multi-build system support**: Supports ament_cmake, ament_python, catkin, and cmake build types - **ROS Distribution Support**: Works with both ROS1 and ROS2 distributions (noetic, humble, jazzy, etc.) - **Cross-platform support**: Supports Linux, macOS and Windows - **Automatic dependency mapping**: Maps ROS dependencies to conda packages using RoboStack mappings ## Basic Usage To use the ROS backend in your `pixi.toml`, add it to your package's build configuration: ```toml [workspace] preview = ["pixi-build"] channels = [ "https://prefix.dev/pixi-build-backends", "https://prefix.dev/robostack-jazzy", # or robostack-humble, robostack-noetic, etc. "https://prefix.dev/conda-forge" ] platforms = ["linux-64", "osx-arm64"] [package.build] backend = { name = "pixi-build-ros", version = "*" } [package.build.config] distro = "jazzy" # or "humble", "noetic", etc. ``` Workspace Configuration The workspace can be defined in the `pixi.toml` of the package or in a separate `pixi.toml` at the workspace root. For example, with a workspace structure like this: ```shell tree -L 2 . β”œβ”€β”€ pixi.toml # Workspace configuration └── src └── my_ros_package β”œβ”€β”€ package.xml # ROS package manifest └── pixi.toml # Package configuration ``` Then you can run `pixi build` to create conda packages for your ROS packages. ```shell pixi build ``` When you want to install it into your environment, you can do so by adding the following to your workspace `pixi.toml`: ```toml [dependencies] ros-jazzy-my-ros-package = { path = "." } # or if the package is in a separate pixi.toml # ros-jazzy-my-ros-package = { path = "src/my_ros_package" } ``` Note that you need to specify the `ros-jazzy-` prefix when you use a distro configuration. ### Automatic Metadata Detection The backend will automatically read metadata from your `package.xml` file to populate package information **that is not** explicitly defined in your `pixi.toml`. This includes: - **Package name and version**: Automatically used if not specified in `pixi.toml` - **Description**: Uses the description from `package.xml` - **Maintainers**: Extracted from maintainer fields in `package.xml` - **Homepage**: From URL fields with type "website" in `package.xml` - **Repository**: From URL fields with type "repository" in `package.xml` ```xml my_ros_package 1.0.0 A useful ROS package for navigation John Doe https://github.com/user/my_ros_package https://github.com/user/my_ros_package ``` It would be equivalent to the following `pixi.toml`: ```toml [package] name = "my_ros_package" version = "1.0.0" description = "A useful ROS package for navigation" maintainers = ["John Doe -` format. The `` part of the package name is automatically generated based on the `distro` configuration. ## Configuration Options You can customize the ROS backend behavior using the `[package.build.config]` section in your `pixi.toml`. The backend supports the following configuration options: ### `distro` (Optional) - **Type**: `String` - **Default**: Uses the [automated detection](#automatic-distro-detection) based on the `channels` in the workspace. - **Target Merge Behavior**: `Overwrite` - Platform-specific distro takes precedence over base The ROS distribution to build for. This affects dependency mapping and build configuration. If set the package name will be prefixed with `ros--` automatically, otherwise the package name from `pixi.toml` or `package.xml` is used. ```toml [package.build.config] distro = "jazzy" # or "humble", "noetic", "iron", etc. ``` ### `env` - **Type**: `Map` - **Default**: `{}` - **Target Merge Behavior**: `Merge` - Platform environment variables override base variables with same name, others are merged Environment variables to set during the build process. These variables are available during compilation. ```toml [package.build.config] env = { AMENT_CMAKE_ENVIRONMENT_HOOKS_ENABLED = "1" } ``` #### Automatically injected environment variables The ROS backend keeps the following variables in sync with the selected distro, so you do not need to set them manually in `env`: - `ROS_DISTRO` β€” set to the distro name you configure in `distro`. - `ROS_VERSION` β€” set to `"1"` for ROS 1 distros and `"2"` for ROS 2 distros. These values are available both while evaluating `package.xml` conditionals and during the generated build script. Any custom entries you provide in `env` are merged on top of these defaults. If you explicitly set `ROS_DISTRO` or `ROS_VERSION` in `env`, your values take precedence over the defaults. ### `debug-dir` The backend always writes JSON-RPC request/response logs and the generated intermediate recipe to the `debug` subdirectory inside the work directory (for example `/debug`). The deprecated `debug-dir` configuration option is ignored; if it is still present in a manifest the backend emits a warning so you can safely remove it. ### `extra-input-globs` - **Type**: `Array` - **Default**: `[]` - **Target Merge Behavior**: `Overwrite` - Platform-specific globs completely replace base globs Additional glob patterns to include as input files for the build process. These patterns are added to the default input globs that include ROS-specific files. pixi.toml ```toml [package.build.config] extra-input-globs = [ "launch/**/*.py", "config/*.yaml", "msgs/**/*.msg", "srvs/**/*.srv" ] ``` Default input globs include: - Source files: `**/*.{c,cpp,h,hpp,rs,sh,py,pyx}` - ROS configuration: `package.xml`, `setup.py`, `setup.cfg`, `pyproject.toml` - Build files: `CMakeLists.txt` ### `extra-package-mappings` - **Type**: `List | RelativeFileName>>>` - **Default**: `[]` Additional dependency mappings to apply to the dependency mapping process. These mappings are used to extend the usage of the dependencies in the `package.xml` file. pixi.toml ```toml [package.build.config] extra-package-mappings = [ {"ros-custom" = { ros = ["ros-custom-msgs"] }}, "mapping.yml" ] ``` Or using a toml array of tables: pixi.toml ```toml [[package.build.config.extra-package-mappings]] custom_msgs = { ros = ["custom-messages"] } ``` Or you can use a file directly in the list: pixi.toml ```toml [package.build.config] extra-package-mappings = ["mapping.yml"] ``` The mapping file can contain the following: mapping.yml ```yaml package_name: # The name of the package in the package.xml conda: conda-package-name # Maps to a conda package, e.g. from `conda-forge` package_name2: # The name of the package in the package.xml conda: [package1, package2] # Maps to a list of conda packages ros_package: # The name of the package in the package.xml ros: ros_package # Maps to a RoboStack style package name, e.g. `ros--ros-package` ``` ## Default Variants On Windows platforms, the backend automatically sets the following default variants: - `c_compiler`: `vs2022` - Visual Studio 2022 C compiler - `cxx_compiler`: `vs2022` - Visual Studio 2022 C++ compiler This default is set to align with conda-forge's switch to Visual Studio 2022 and because [mainstream support for Visual Studio 2019 ended in 2024](https://learn.microsoft.com/en-us/lifecycle/products/visual-studio-2019). The `vs2022` compiler is more widely supported on modern GitHub runners and build environments. You can override these defaults by explicitly setting variants using [`[workspace.build-variants]`](https://pixi.sh/latest/reference/pixi_manifest/#build-variants-optional) in your `pixi.toml`: ```toml [workspace.build-variants] c_compiler = ["vs2019"] cxx_compiler = ["vs2019"] ``` ## Build Process The ROS backend follows this build process: 1. **Package Detection**: Parses `package.xml` to determine build type (`ament_cmake`, `ament_python`, `catkin`) 1. **Dependency Resolution**: Maps ROS dependencies to conda packages using RoboStack mappings 1. **Environment Setup**: Configures ROS-specific environment variables 1. **Build Execution**: Uses the appropriate build template based on package type. 1. **Installation**: Installs built artifacts to the conda package prefix ## ROS Package Types The backend supports different ROS package build types: ### ament_cmake (ROS2) For C++ packages using ament build system: ```xml ament_cmake ``` ### ament_python (ROS2) For Python packages using ament build system: ```xml ament_python ``` ### catkin (ROS1) For ROS1 packages using catkin build system: ```xml catkin ``` ## Limitations - **Version constraints**: Dependency versions from `package.xml` are currently ignored - **Conditional dependencies**: Dependencies with conditions are not fully supported yet - **Target-specific dependencies**: Platform-specific dependencies in `package.xml` need manual handling ## See Also - [ROS Documentation](https://docs.ros.org/) - Official ROS documentation - [RoboStack](https://robostack.github.io/) - Conda packages for the Robot Operating System - [ament Build System](https://docs.ros.org/en/rolling/Concepts/Build-System-Development/ament.html) - ROS2 build system - [catkin Build System](http://wiki.ros.org/catkin) - ROS1 build system # pixi-build-rust The `pixi-build-rust` backend is designed for building Rust projects using [Cargo](https://doc.rust-lang.org/cargo/), Rust's native build system and package manager. It provides seamless integration with Pixi's package management workflow while maintaining cross-platform compatibility. Warning `pixi-build` is a preview feature, and will change until it is stabilized. This is why we require users to opt in to that feature by adding "pixi-build" to `workspace.preview`. ```toml [workspace] preview = ["pixi-build"] ``` ## Overview This backend automatically generates conda packages from Rust projects by: - **Using Cargo**: Leverages Rust's native build system for compilation and installation - **Cargo.toml Integration**: Automatically reads package metadata (name, version, description, license, etc.) from your `Cargo.toml` file when not specified in `pixi.toml` - **Cross-platform support**: Works consistently across Linux, macOS, and Windows - **Optimization support**: Automatically detects and integrates with `sccache` for faster compilation - **OpenSSL integration**: Handles OpenSSL linking when available in the environment ## Basic Usage To use the Rust backend in your `pixi.toml`, add it to your package's build configuration: ```toml [package] name = "rust_package" version = "0.1.0" [package.build] backend = { name = "pixi-build-rust", version = "*" } channels = ["https://prefix.dev/conda-forge"] ``` ### Automatic Metadata Detection The backend will automatically read metadata from your `Cargo.toml` file to populate package information **that is not** explicitly defined in your `pixi.toml`. This includes: - **Package name and version**: Automatically used if not specified in `pixi.toml` - **License**: Extracted from `Cargo.toml` license field - **Description**: Uses the description from `Cargo.toml` - **Homepage**: From the homepage field in `Cargo.toml` - **Repository**: From the repository field in `Cargo.toml` - **Documentation**: From the documentation field in `Cargo.toml` For example, if your `Cargo.toml` contains: ```toml [package] name = "my-rust-tool" version = "1.0.0" description = "A useful Rust command-line tool" license = "MIT" homepage = "https://github.com/user/my-rust-tool" repository = "https://github.com/user/my-rust-tool" ``` You can create a minimal `pixi.toml`: ```toml [package.build] backend = { name = "pixi-build-rust", version = "*" } channels = ["https://prefix.dev/conda-forge"] ``` The backend will automatically use the metadata from `Cargo.toml` to generate a complete conda package. It still requires you to specify the `name` and `version` We're in the process of making this optional in `pixi`, but for now, you need to specify them explicitly. This is the tracking issue to fix this in [Pixi](https://github.com/prefix-dev/pixi/issues/4317) ### Required Dependencies The backend automatically includes the following build tools: - `rust` - The Rust compiler and toolchain - `cargo` - Rust's package manager (included with rust) You can add these to your [`build-dependencies`](https://pixi.sh/latest/build/dependency_types/) if you need specific versions: ```toml [package.build-dependencies] rust = "1.70" ``` ## Configuration Options You can customize the Rust backend behavior using the `[package.build.config]` section in your `pixi.toml`. The backend supports the following configuration options: ### `extra-args` - **Type**: `Array` - **Default**: `[]` - **Target Merge Behavior**: `Overwrite` - Platform-specific arguments completely replace base arguments Additional command-line arguments to pass to the `cargo install` command. These arguments are appended to the cargo command that builds and installs your project. ```toml [package.build.config] extra-args = [ "--features", "serde,tokio", "--bin", "my-binary" ] ``` For target-specific configuration, platform arguments completely replace the base configuration: ```toml [package.build.config] extra-args = ["--release"] [package.build.target.linux-64.config] extra-args = ["--features", "linux-specific", "--target", "x86_64-unknown-linux-gnu"] # Result for linux-64: ["--features", "linux-specific", "--target", "x86_64-unknown-linux-gnu"] ``` ### `env` - **Type**: `Map` - **Default**: `{}` - **Target Merge Behavior**: `Merge` - Platform environment variables override base variables with same name, others are merged Environment variables to set during the build process. These variables are available during compilation. ```toml [package.build.config] env = { RUST_LOG = "debug", CARGO_PROFILE_RELEASE_LTO = "true" } ``` For target-specific configuration, platform environment variables are merged with base variables: ```toml [package.build.config] env = { RUST_LOG = "info", COMMON_VAR = "base" } [package.build.target.linux-64.config] env = { COMMON_VAR = "linux", CARGO_PROFILE_RELEASE_LTO = "true" } # Result for linux-64: { RUST_LOG = "info", COMMON_VAR = "linux", CARGO_PROFILE_RELEASE_LTO = "true" } ``` ### `debug-dir` The backend always writes JSON-RPC request/response logs and the generated intermediate recipe to the `debug` subdirectory inside the work directory (for example `/debug`). The deprecated `debug-dir` configuration option is ignored; when present a warning is emitted so you can safely remove the setting. ### `extra-input-globs` - **Type**: `Array` - **Default**: `[]` - **Target Merge Behavior**: `Overwrite` - Platform-specific globs completely replace base globs Additional glob patterns to include as input files for the build process. These patterns are added to the default input globs that include Rust source files (`**/*.rs`), Cargo configuration files (`Cargo.toml`, `Cargo.lock`), build scripts (`build.rs`), and other build-related files. ```toml [package.build.config] extra-input-globs = [ "assets/**/*", "migrations/*.sql", "*.md" ] ``` For target-specific configuration, platform-specific globs completely replace the base: ```toml [package.build.config] extra-input-globs = ["*.txt"] [package.build.target.linux-64.config] extra-input-globs = ["*.txt", "*.so", "linux-configs/**/*"] # Result for linux-64: ["*.txt", "*.so", "linux-configs/**/*"] ``` ### `ignore-cargo-manifest` - **Type**: `Boolean` - **Default**: `false` - **Target Merge Behavior**: `Overwrite` - Platform-specific value overrides base value if set When set to `true`, disables automatic metadata extraction from `Cargo.toml`. The backend will only use metadata explicitly defined in your `pixi.toml` file, ignoring any information from the Cargo manifest. ```toml [package.build.config] ignore-cargo-manifest = true ``` This is useful when: - You want to explicitly control all package metadata through `pixi.toml` - The `Cargo.toml` contains metadata that conflicts with your conda package requirements - When using the `Cargo.toml` results in an error that you cannot resolve. For target-specific configuration: ```toml [package.build.config] ignore-cargo-manifest = false [package.build.target.linux-64.config] ignore-cargo-manifest = true # Result for linux-64: Cargo.toml metadata will be ignored ``` ### `compilers` - **Type**: `Array` - **Default**: `["rust", "c"]` - **Target Merge Behavior**: `Overwrite` - Platform-specific compilers completely replace base compilers List of compilers to use for the build. The backend automatically generates appropriate compiler dependencies using conda-forge's compiler infrastructure. ```toml [package.build.config] compilers = ["rust", "c", "cxx"] ``` For target-specific configuration, platform compilers completely replace the base configuration: ```toml [package.build.config] compilers = ["rust", "c"] [package.build.target.linux-64.config] compilers = ["rust", "c", "cxx"] # Result for linux-64: ["rust", "c", "cxx"] ``` Comprehensive Compiler Documentation For detailed information about available compilers, platform-specific behavior, and how conda-forge compilers work, see the [Compilers Documentation](../../key_concepts/compilers/). ### `binaries` - **Type**: `Array` - **Default**: `[]` - **Target Merge Behavior**: `Overwrite` - Platform-specific binaries completely replace base binaries when set List of specific cargo binaries to install. Each entry is passed to `cargo install` as `--bin `. If the list is empty, Cargo's default behavior is used (all binaries defined by the crate are installed). ```toml [package.build.config] binaries = ["rattler-build"] ``` For target-specific configuration, platform-specific binaries override the base configuration: ```toml [package.build.config] binaries = ["my-cli", "my-helper"] [package.build.target.linux-64.config] binaries = ["my-cli"] # Result for linux-64: only ["my-cli"] ``` ## Build Process The Rust backend follows this build process: 1. **Environment Setup**: Configures OpenSSL paths if available in the environment 1. **Compiler Caching**: Sets up `sccache` as `RUSTC_WRAPPER` if available for faster compilation 1. **Build and Install**: Executes `cargo install` with the following default options: - `--locked`: Use the exact versions from `Cargo.lock` - `--root "$PREFIX"`: Install to the conda package prefix - `--path .`: Install from the current source directory - `--no-track`: Don't track installation metadata - `--force`: Force installation even if already installed - `--bin ` (optional, repeated): Added for each entry in [`[package.build.config.binaries]`](#binaries) 1. **Cache Statistics**: Displays `sccache` statistics if available ## Default Variants On Windows platforms, the backend automatically sets the following default variants: - `c_compiler`: `vs2022` - Visual Studio 2022 C compiler - `cxx_compiler`: `vs2022` - Visual Studio 2022 C++ compiler These variants are used when you specify compilers in your [`[package.build.config.compilers]`](#compilers) configuration. Note that setting these default variants does not automatically add compilers to your build - you still need to explicitly configure which compilers to use. This default is set to align with conda-forge's switch to Visual Studio 2022 and because [mainstream support for Visual Studio 2019 ended in 2024](https://learn.microsoft.com/en-us/lifecycle/products/visual-studio-2019). The `vs2022` compiler is more widely supported on modern GitHub runners and build environments. You can override these defaults by explicitly setting variants using [`[workspace.build-variants]`](https://pixi.sh/latest/reference/pixi_manifest/#build-variants-optional) in your `pixi.toml`: ```toml [workspace.build-variants] c_compiler = ["vs2019"] cxx_compiler = ["vs2019"] ``` ## Limitations - Currently, uses `cargo install` which builds in release mode by default - No support for custom Cargo profiles in the build configuration - Limited workspace support for multi-crate projects ## See Also - [Cargo Documentation](https://doc.rust-lang.org/cargo/) - Official Cargo documentation - [The Rust Programming Language](https://doc.rust-lang.org/book/) - Official Rust book - [sccache](https://github.com/mozilla/sccache) - Shared compilation cache for Rust # Compilers in pixi-build Some `pixi-build` backends support configurable compiler selection through the `compilers` configuration option. This feature integrates with conda-forge's compiler infrastructure to provide cross-platform, ABI-compatible builds. Warning `pixi-build` is a preview feature, and will change until it is stabilized. This is why we require users to opt in to that feature by adding "pixi-build" to `workspace.preview`. ```toml [workspace] preview = ["pixi-build"] ``` ## How Conda-forge Compilers Work Understanding conda-forge's compiler system is essential for effectively using `pixi-build` compiler configuration. ### Compiler Selection and Platform Resolution When you specify `compilers = ["c", "cxx"]` in your `pixi-build` configuration, the backend automatically selects the appropriate platform-specific compiler packages based on your target platform and build variants. If you are cross-compiling the target platform will be the platform you are compiling for. Otherwise, it the target platform is your current platform. If your target platform is `amd64`, this will result in the following packages to be selected by default. | Compiler | Linux | macOS | Windows | | --------- | ------------------- | ----------------- | --------------- | | `c` | `gcc_linux-64` | `clang_osx-64` | `vs2019_win-64` | | `cxx` | `gxx_linux-64` | `clangxx_osx-64` | `vs2019_win-64` | | `fortran` | `gfortran_linux-64` | `gfortran_osx-64` | `vs2019_win-64` | ### Build Variants and Compiler Selection Compiler selection works through a build variant system. Build variants allow you to specify different versions or types of compilers for your builds, creating a build matrix that can target multiple compiler configurations. ### Overriding Compilers in Pixi Workspaces Pixi workspaces provide powerful mechanisms to override compiler variants through build variant configuration. This allows users to customize compiler selection without modifying individual package recipes. To overwrite the default C compiler you can modify your `pixi.toml` file in the workspace root: ```toml # pixi.toml [workspace.build-variants] c_compiler = ["clang"] c_compiler_version = ["11.4"] ``` To overwrite the c/cxx compiler specifically for Windows you can use the `workspace.target` section to specify platform-specific compiler variants: ```toml # pixi.toml [workspace.target.win.build-variants] c_compiler = ["vs2022"] cxx_compiler = ["vs2022"] ``` Or ```toml [workspace.target.win.build-variants] c_compiler = ["vs"] cxx_compiler = ["vs"] c_compiler_version = ["2022"] cxx_compiler_version = ["2022"] ``` #### How Compilers Are Selected When you specify `compilers = ["c"]` in your pixi-build configuration, the system doesn't directly install a package named "c". Instead, it uses a **variant system** to determine the exact compiler package for your platform. 1. **Determine which compilers to add** If you specified the compiler in the configuration, it will use that. If the configuration has this entry `compilers = ["c"]`, the C compiler will be requested. If there's no compiler configuration, the [default](./#backend-specific-defaults) of the backend will be used. 1. **For each compiler, determine the variants to take into account** The variant names follow the pattern `{language}_compiler` and `{language}_compiler_version`. In our example that would lead to `c_compiler` and `c_compiler_version`. 1. **For each variant combination, create an output** Each variant can have multiple values and each combination of these values are outputs that can be selected. For example with the following example multiple `gcc` versions could be used to build this package. ```toml [workspace.build-variants] c_compiler = ["gcc"] c_compiler_version = ["11.4", "14.0"] ``` If `{language}_compiler_version` is not set, then there's no constraint on the compiler version. If `{language}_compiler` is not set, the build-backends set default values for certain languages: - c: `gcc` on Linux, `clang` on osx and `vs2017` on Windows - cxx: `gxx` on Linux, `clangxx` on osx and `vs2017` on Windows - fortran: `gfortran` on Linux, `gfortran` on osx and `vs2017` on Windows - rust: `rust` 1. **Request a package for each output** For each output a package will be requested as build dependency with the following pattern `{compiler}_{target_platform} {compiler_version}`. `compiler` and `compiler_version` has been determined in the step before. `target_platform` is the platform you are compiling for, if you are cross compiling the target platform would differ from your current platform. In our example we would create two outputs. If we build on linux-64, one output would request `gcc_linux-64 11.4` and one would request `gcc_linux-64 14.0` ## Available Compilers Which compilers are available depends on the channels you target but through the conda-forge infrastructure the following compilers are generally available across all platforms. The table below lists the core compilers, specialized compilers, and some backend language-specific compilers that can be configured in `pixi-build`. ### Core Compilers | Compiler | Description | Platforms | | --------- | ---------------- | ---------------------------------------------------- | | `c` | C compiler | Linux (gcc), macOS (clang), Windows (vs2019) | | `cxx` | C++ compiler | Linux (gxx), macOS (clangxx), Windows (vs2019) | | `fortran` | Fortran compiler | Linux (gfortran), macOS (gfortran), Windows (vs2019) | | `rust` | Rust compiler | All platforms | | `go` | Go compiler | All platforms | ### Specialized Compilers | Compiler | Description | Platforms | | -------- | -------------------- | ------------------------------- | | `cuda` | NVIDIA CUDA compiler | Linux, Windows, (limited macOS) | ## Backend-Specific Defaults Only certain `pixi-build` backends support the `compilers` configuration option. Each supporting backend has sensible defaults based on the typical requirements for that language ecosystem: | Backend | Compiler Support | Default Compilers | Rationale | | -------------------------------------------------------------------- | -------------------- | ----------------- | --------------------------------------------------------------------------- | | **[pixi-build-cmake](../../backends/pixi-build-cmake/#compilers)** | βœ… **Supported** | `["cxx"]` | Most CMake projects are C++ | | **[pixi-build-rust](../../backends/pixi-build-rust/#compilers)** | βœ… **Supported** | `["rust"]` | Rust projects need the Rust compiler | | **[pixi-build-python](../../backends/pixi-build-python/#compilers)** | βœ… **Supported** | `[]` | Pure Python packages typically don't need compilers | | **[pixi-build-mojo](../../backends/pixi-build-mojo/#compilers)** | βœ… **Supported** | `[]` | `mojo-compiler` must be specified in the `package.*-dependencies` manually. | | **pixi-build-rattler-build** | ❌ **Not Supported** | N/A | Uses direct `recipe.yaml` - configure compilers directly in recipe | Adding Compiler Support to Other Backends Backend developers can add compiler configuration support by implementing the `compilers` field in their backend configuration and integrating with the shared compiler infrastructure in `pixi-build-backend`. ## Configuration Examples To configure compilers in your `pixi-build` project, you can use the `compilers` configuration option in your `pixi.toml` file. Below are some examples of how to set up compiler configurations for different scenarios. Backend Support Compiler configuration is only available in backends that have specifically implemented this feature. Not all backends support the `compilers` configuration option. Check your backend's documentation to see if it supports compiler configuration. ### Basic Compiler Configuration ```toml # Use default compilers for the backend [package.build.config] # No compilers specified - uses backend defaults # Override with specific compilers [package.build.config] compilers = ["c", "cxx", "fortran"] ``` ### Platform-Specific Compiler Configuration ```toml # Base configuration for most platforms [package.build.config] compilers = ["cxx"] # Linux needs additional CUDA support [package.build.target.linux-64.config] compilers = ["cxx", "cuda"] # Windows needs additional C compiler for some dependencies [package.build.target.win-64.config] compilers = ["c", "cxx"] ``` # Distributing documentation # JFrog Artifactory JFrog Artifactory is an enterprise-grade artifact repository manager that supports conda packages. This guide explains how to configure pixi to use Artifactory as a private conda channel. ## Setting up Artifactory ### 1. Create a conda repository In your Artifactory instance, create a repository with the "Conda" package type. The repository URL will be in the format: `https://my-org.jfrog.io/artifactory//` Artifactory supports different repository types: - **Local repositories**: Store your own private packages. - **Remote repositories**: Cache and mirror upstream channels like conda-forge. This reduces external bandwidth, speeds up downloads, and provides availability even when upstream channels are down. - **Virtual repositories**: Combine multiple local and remote repositories under a single URL. You usually don't need these unless you have more advanced use cases or migrations. A common setup is to create a remote repository that mirrors conda-forge, then combine it with a local repository for internal packages using a virtual repository. ### 2. Generate an identity token To authenticate with Artifactory, you need to generate an identity token: 1. Click on your user profile in the top-right corner and select **Edit Profile** 1. Under **Authentication Settings**, click **Generate an Identity Token** 1. Add a description (e.g., "pixi") and click **Next** 1. Copy the generated **Reference Token** ## Authenticating with pixi Use the `pixi auth login` command to authenticate with your Artifactory instance: ```shell pixi auth login --token https://my-org.jfrog.io ``` This stores the token securely using your system's credential manager. See [Authentication](../authentication/) for more details on credential storage. ## Configuring channels Add your Artifactory channel to your `pixi.toml`: ```toml [workspace] channels = ["https://my-org.jfrog.io/artifactory/channel-1", "conda-forge"] ``` Strict channel priority Pixi uses strict channel priority. Packages are always resolved from the first channel that contains them. In the example above, if a package exists in both your Artifactory channel and conda-forge, the version from Artifactory will always be used. This is useful for: - Overriding specific packages with internal builds - Ensuring consistent package versions across your organization - Using private packages that aren't available on public channels See [Channel Logic](../../advanced/channel_logic/) for more details on how channel priority works. ## Example configuration Here's a complete example using Artifactory with conda-forge as a fallback: ```toml [workspace] name = "my-project" channels = ["https://my-org.jfrog.io/artifactory/internal-packages", "conda-forge"] platforms = ["linux-64", "osx-arm64", "win-64"] [dependencies] python = ">=3.11" # This will come from your Artifactory channel if available there my-internal-package = "*" # These will come from conda-forge (due to channel priority) numpy = ">=1.24" pandas = ">=2.0" ``` ### Forcing a specific channel If you want to ensure a package always comes from a specific channel regardless of priority, use the `channel` key: ```toml [dependencies] # Always use numpy from conda-forge, even if it exists in Artifactory numpy = { version = ">=1.24", channel = "conda-forge" } # Always use internal-lib from Artifactory internal-lib = { version = "*", channel = "https://my-org.jfrog.io/artifactory/internal-packages" } ``` This is useful when you want to override the default channel priority for specific packages. ## GitHub Actions with OIDC For CI/CD pipelines, you can authenticate with Artifactory using OIDC (OpenID Connect) instead of storing long-lived tokens as secrets. This is more secure as tokens are short-lived and automatically rotated. ```yaml - name: Log in to Artifactory uses: jfrog/setup-jfrog-cli@279b1f629f43dd5bc658d8361ac4802a7ef8d2d5 # v4.9.1 id: artifactory env: JF_URL: https://my-org.jfrog.io with: disable-job-summary: true oidc-provider-name: ${{ vars.ARTIFACTORY_OIDC_PROVIDER }} oidc-audience: ${{ vars.ARTIFACTORY_OIDC_AUDIENCE }} - name: Set up Pixi uses: prefix-dev/setup-pixi@82d477f15f3a381dbcc8adc1206ce643fe110fb7 # v0.9.3 with: auth-host: https://my-org.jfrog.io auth-token: ${{ steps.artifactory.outputs.oidc-token }} ``` This requires configuring an OIDC provider in your Artifactory instance that trusts GitHub Actions. See JFrog's documentation on [OIDC integration](https://jfrog.com/help/r/jfrog-platform-administration-documentation/configure-an-oidc-integration) for setup instructions. You can authenticate Pixi with a server like prefix.dev, a private quetz instance or anaconda.org. Different servers use different authentication methods. In this documentation page, we detail how you can authenticate against the different servers and where the authentication information is stored. ```shell Usage: pixi auth login [OPTIONS] Arguments: The host to authenticate with (e.g. repo.prefix.dev) Options: --token The token to use (for authentication with prefix.dev) --username The username to use (for basic HTTP authentication) --password The password to use (for basic HTTP authentication) --conda-token The token to use on anaconda.org / quetz authentication --s3-access-key-id The S3 access key ID --s3-secret-access-key The S3 secret access key --s3-session-token The S3 session token -v, --verbose... Increase logging verbosity -q, --quiet... Decrease logging verbosity --color Whether the log needs to be colored [env: PIXI_COLOR=] [default: auto] [possible values: always, never, auto] --no-progress Hide all progress bars, always turned on if stderr is not a terminal [env: PIXI_NO_PROGRESS=] -h, --help Print help ``` The different options are "token", "conda-token" and "username + password". The token variant implements a standard "Bearer Token" authentication as is used on the prefix.dev platform. A Bearer Token is sent with every request as an additional header of the form `Authentication: Bearer `. The conda-token option is used on anaconda.org and can be used with a quetz server. With this option, the token is sent as part of the URL following this scheme: `conda.anaconda.org/t//conda-forge/linux-64/...`. The last option, username & password, are used for "Basic HTTP Authentication". This is the equivalent of adding `http://user:password@myserver.com/...`. This authentication method can be configured quite easily with a reverse NGinx or Apache server and is thus commonly used in self-hosted systems. ## Examples Login to prefix.dev: ```shell pixi auth login prefix.dev --token pfx_jj8WDzvnuTHEGdAhwRZMC1Ag8gSto8 ``` Login to anaconda.org: ```shell pixi auth login anaconda.org --conda-token xy-72b914cc-c105-4ec7-a969-ab21d23480ed ``` Login to a basic HTTP secured server: ```shell pixi auth login myserver.com --username user --password password ``` Login to an S3 bucket: ```shell pixi auth login s3://my-bucket --s3-access-key-id --s3-secret-access-key # if your key uses a session token, you can also use: pixi auth login s3://my-bucket --s3-access-key-id --s3-secret-access-key --s3-session-token ``` Note S3 authentication is also supported through AWS's typical `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` environment variables, see the [S3 section](../s3/) for more details. ## Where does Pixi store the authentication information? The storage location for the authentication information is system-dependent. By default, Pixi tries to use the keychain to store this sensitive information securely on your machine. On Windows, the credentials are stored in the "credentials manager". Searching for `rattler` (the underlying library Pixi uses) you should find any credentials stored by Pixi (or other rattler-based programs). On macOS, the passwords are stored in the keychain. To access the password, you can use the `Keychain Access` program that comes pre-installed on macOS. Searching for `rattler` (the underlying library Pixi uses) you should find any credentials stored by Pixi (or other rattler-based programs). On Linux, one can use `GNOME Keyring` (or just Keyring) to access credentials that are securely stored by `libsecret`. Searching for `rattler` should list all the credentials stored by Pixi and other rattler-based programs. ## Fallback storage If you run on a server with none of the aforementioned keychains available, then Pixi falls back to store the credentials in an *insecure* JSON file. This JSON file is located at `~/.rattler/credentials.json` and contains the credentials. ## Override the authentication storage You can use the `RATTLER_AUTH_FILE` environment variable to override the default location of the credentials file. When this environment variable is set, it provides the only source of authentication data that is used by pixi. E.g. ```bash export RATTLER_AUTH_FILE=$HOME/credentials.json # You can also specify the file in the command line pixi global install --auth-file $HOME/credentials.json ... ``` Note `RATTLER_AUTH_FILE` has higher precedence than the CLI argument. The JSON should follow the following format: ```json { "*.prefix.dev": { "BearerToken": "your_token" }, "otherhost.com": { "BasicHTTP": { "username": "your_username", "password": "your_password" } }, "conda.anaconda.org": { "CondaToken": "your_token" }, "s3://my-bucket": { "S3Credentials": { "access_key_id": "my-access-key-id", "secret_access_key": "my-secret-access-key", "session_token": null } } } ``` Note: if you use a wildcard in the host, any subdomain will match (e.g. `*.prefix.dev` also matches `repo.prefix.dev`). Lastly you can set the authentication override file in the [global configuration file](../../reference/pixi_configuration/). ## PyPI authentication Currently, we support the following methods for authenticating against PyPI: 1. [keyring](https://pypi.org/project/keyring/) authentication. 1. `.netrc` file authentication. We want to add more methods in the future, so if you have a specific method you would like to see, please let us know. ### Keyring authentication Currently, Pixi supports the uv method of authentication through the python [keyring](https://pypi.org/project/keyring/) library. #### Installing keyring To install keyring you can use `pixi global install`: ```shell pixi global install keyring ``` ```shell pixi global install keyring --with keyrings.google-artifactregistry-auth ``` ```shell pixi global install keyring --with keyrings.artifacts ``` ```shell pixi global install keyring --with keyrings.codeartifact ``` For other registries, you will need to adapt these instructions to add the right keyring backend. #### Configuring your workspace to use keyring Use keyring to store your credentials e.g: ```shell keyring set https://my-index/simple your_username # prompt will appear for your password ``` Add the following configuration to your Pixi manifest, making sure to include `your_username@` in the URL of the registry: ```toml [pypi-options] index-url = "https://your_username@custom-registry.com/simple" ``` After making sure you are logged in, for instance by running `gcloud auth login`, add the following configuration to your Pixi manifest: ```toml [pypi-options] extra-index-urls = ["https://oauth2accesstoken@-python.pkg.dev///simple"] ``` Note To find this URL more easily, you can use the `gcloud` command: ```shell gcloud artifacts print-settings python --project= --repository= --location= ``` After following the [`keyrings.artifacts` instructions](https://github.com/jslorrma/keyrings.artifacts?tab=readme-ov-file#usage) and making sure that keyring works correctly, add the following configuration to your Pixi manifest: ```toml [pypi-options] extra-index-urls = ["https://VssSessionToken@pkgs.dev.azure.com/{organization}/{project}/_packaging/{feed}/pypi/simple/"] ``` Ensure you are logged in e.g via `aws sso login` and add the following configuration to your Pixi manifest: ```toml [pypi-options] extra-index-urls = ["https://aws@-.d.codeartifact..amazonaws.com/pypi//simple/"] ``` #### Installing your environment Either configure your [Global Config](../../reference/pixi_configuration/#pypi-config), or use the flag `--pypi-keyring-provider` which can either be set to `subprocess` (activated) or `disabled`: ```shell # From an existing pixi workspace pixi install --pypi-keyring-provider subprocess ``` ### `.netrc` file `pixi` allows you to access private registries securely by authenticating with credentials stored in a `.netrc` file. - The `.netrc` file can be stored in your home directory (`$HOME/.netrc` for Unix-like systems) - or in the user profile directory on Windows (`%HOME%\_netrc`). - You can also set up a different location for it using the `NETRC` variable (`export NETRC=/my/custom/location/.netrc`). e.g `export NETRC=/my/custom/location/.netrc pixi install` In the `.netrc` file, you store authentication details like this: ```sh machine registry-name login admin password admin ``` For more details, you can access the [.netrc docs](https://www.ibm.com/docs/en/aix/7.2?topic=formats-netrc-file-format-tcpip). One way to bring a Pixi package into production is to containerize it using tools like Docker or Podman. We provide a simple docker image at [`pixi-docker`](https://github.com/prefix-dev/pixi-docker) that contains the Pixi executable on top of different base images. The images are available on [ghcr.io/prefix-dev/pixi](https://ghcr.io/prefix-dev/pixi). There are different tags for different base images available: - `latest` - based on `ubuntu:jammy` - `focal` - based on `ubuntu:focal` - `bullseye` - based on `debian:bullseye` - `noble-cuda-12.9.1` - based on `nvidia/cuda:12.9.1-base-ubuntu24.04` - `noble-cuda-13.0.0` - based on `nvidia/cuda:13.0.0-base-ubuntu24.04` - ... and more All tags For all tags, take a look at the [build script](https://github.com/prefix-dev/pixi-docker/blob/main/.github/workflows/build.yml). Best practices for docker with pixi [@pavelzw](https://github.com/pavelzw) wrote a blog post about [shipping conda environments to production using pixi](https://tech.quantco.com/blog/pixi-production). If you want to know more about best practices using docker with pixi, feel free to check out their blog post. ### Example Usage The following example uses the Pixi docker image as a base image for a multi-stage build. It also makes use of `pixi shell-hook` to not rely on Pixi being installed in the production container. More examples For more examples, take a look at [pavelzw/pixi-docker-example](https://github.com/pavelzw/pixi-docker-example). ```Dockerfile FROM ghcr.io/prefix-dev/pixi:0.41.4 AS build # copy source code, pixi.toml and pixi.lock to the container WORKDIR /app COPY . . # install dependencies to `/app/.pixi/envs/prod` # use `--locked` to ensure the lockfile is up to date with pixi.toml RUN pixi install --locked -e prod # create the shell-hook bash script to activate the environment RUN pixi shell-hook -e prod -s bash > /shell-hook RUN echo "#!/bin/bash" > /app/entrypoint.sh RUN cat /shell-hook >> /app/entrypoint.sh # extend the shell-hook script to run the command passed to the container RUN echo 'exec "$@"' >> /app/entrypoint.sh FROM ubuntu:24.04 AS production WORKDIR /app # only copy the production environment into prod container # please note that the "prefix" (path) needs to stay the same as in the build container COPY --from=build /app/.pixi/envs/prod /app/.pixi/envs/prod COPY --from=build --chmod=0755 /app/entrypoint.sh /app/entrypoint.sh # copy your project code into the container as well COPY ./my_project /app/my_project EXPOSE 8000 ENTRYPOINT [ "/app/entrypoint.sh" ] # run your app inside the pixi environment CMD [ "uvicorn", "my_project:app", "--host", "0.0.0.0" ] ``` [`pixi-pack`](https://github.com/quantco/pixi-pack) is a simple tool that takes an environment and packs it into a compressed archive that can be shipped to the target machine. The corresponding `pixi-unpack` tool can be used to unpack the archive and recreate an environment. Both tools can be installed via ```bash pixi global install pixi-pack pixi-unpack ``` Or by downloading our pre-built binaries from the [releases page](https://github.com/Quantco/pixi-pack/releases). Instead of installing `pixi-pack` and `pixi-unpack` globally, you can also use `pixi exec` to run `pixi-pack` in a temporary environment: ```bash pixi exec pixi-pack pixi exec pixi-unpack environment.tar ``` You can also write `pixi pack` (and `pixi unpack`) if you have `pixi`, and `pixi-pack` and `pixi-unpack` installed globally. You can pack an environment with ```bash pixi-pack --environment prod --platform linux-64 pixi.toml ``` This will create an `environment.tar` file that contains all conda packages required to create the environment. ```text # environment.tar | pixi-pack.json | environment.yml | channel | β”œβ”€β”€ noarch | | β”œβ”€β”€ tzdata-2024a-h0c530f3_0.conda | | β”œβ”€β”€ ... | | └── repodata.json | └── linux-64 | β”œβ”€β”€ ca-certificates-2024.2.2-hbcca054_0.conda | β”œβ”€β”€ ... | └── repodata.json ``` ### `pixi-unpack`: Unpacking an environment With `pixi-unpack environment.tar`, you can unpack the environment on your target system. This will create a new conda environment in `./env` that contains all packages specified in your `pixi.toml`. It also creates an `activate.sh` (or `activate.bat` on Windows) file that lets you activate the environment without needing to have `conda` or `micromamba` installed. ```bash $ pixi-unpack environment.tar $ ls env/ activate.sh environment.tar $ cat activate.sh export PATH="/home/user/project/env/bin:..." export CONDA_PREFIX="/home/user/project/env" . "/home/user/project/env/etc/conda/activate.d/activate_custom_package.sh" ``` ### Cross-platform Packs Since `pixi-pack` just downloads the `.conda` and `.tar.bz2` files from the conda repositories, you can trivially create packs for different platforms. ```bash pixi-pack --platform win-64 ``` Note You can only unpack a pack on a system that has the same platform as the pack was created for. ### Self-Extracting Binaries You can create a self-extracting binary that contains the packed environment and a script that unpacks the environment. This can be useful if you want to distribute the environment to users that don't have `pixi-unpack` installed. ```bash $ pixi-pack --create-executable $ ls environment.sh $ ./environment.sh $ ls env/ activate.sh environment.sh ``` ```powershell PS > pixi-pack --create-executable PS > ls environment.ps1 PS > .\environment.ps1 PS > ls env/ activate.sh environment.ps1 ``` #### Custom pixi-unpack executable path When creating a self-extracting binary, you can specify a custom path or URL to a `pixi-unpack` executable to avoid downloading it from the [default location](https://github.com/Quantco/pixi-pack/releases/latest). You can provide one of the following as the `--pixi-unpack-source`: - a URL to a `pixi-unpack` executable like `https://my.mirror/pixi-pack/pixi-unpack-x86_64-unknown-linux-musl` - a path to a `pixi-unpack` binary like `./pixi-unpack-x86_64-unknown-linux-musl` ##### Example Usage Using a URL: ```bash pixi-pack --create-executable --pixi-unpack-source https://my.mirror/pixi-pack/pixi-unpack-x86_64-unknown-linux-musl ``` Using a path: ```bash pixi-pack --create-executable --pixi-unpack-source ./pixi-unpack-x86_64-unknown-linux-musl ``` Note The produced executable is a simple shell script that contains both the `pixi-unpack` binary as well as the packed environment. ### Inject Additional Packages You can inject additional packages into the environment that are not specified in `pixi.lock` by using the `--inject` flag: ```bash pixi-pack --inject local-package-1.0.0-hbefa133_0.conda pixi.toml ``` This can be particularly useful if you build the package itself and want to include the built package in the environment but still want to use `pixi.lock` from the workspace. ### PyPi support You can also pack PyPi wheel packages into your environment. `pixi-pack` only supports wheel packages and not source distributions. If you happen to use source distributions, you can ignore them by using the `--ignore-pypi-non-wheel` flag. This will skip the bundling of PyPi packages that are source distributions. The `--inject` option also supports wheels. ```bash pixi-pack --ignore-pypi-non-wheel --inject my_webserver-0.1.0-py3-none-any.whl ``` Warning In contrast to injecting from conda packages, we cannot verify that injected wheels are compatible with the target environment. Please make sure the packages are compatible. ### Mirror and S3 middleware You can use mirror middleware by creating a configuration file as described in the [pixi documentation](../../reference/pixi_configuration/#mirror-configuration) and referencing it using `--config`. config.toml ```toml [mirrors] "https://conda.anaconda.org/conda-forge" = ["https://my.artifactory/conda-forge"] ``` If you are using [S3 in pixi](../s3/), you can also add the appropriate S3 config in your config file and reference it. config.toml ```toml [s3-options.my-s3-bucket] endpoint-url = "https://s3.eu-central-1.amazonaws.com" region = "eu-central-1" force-path-style = false ``` ### Setting maximum number of parallel downloads ```toml [concurrency] downloads = 5 ``` Use `pixi-pack --config config.toml` to use the custom configuration file. See [pixi docs](../../reference/pixi_configuration/#concurrency) for more information. ### Cache Downloaded Packages You can cache downloaded packages to speed up subsequent pack operations by using the `--use-cache` flag: ```bash pixi-pack --use-cache ~/.pixi-pack/cache ``` This will store all downloaded packages in the specified directory and reuse them in future pack operations. The cache follows the same structure as conda channels, organizing packages by platform subdirectories (e.g., linux-64, win-64, etc.). Using a cache is particularly useful when: - Creating multiple packs with overlapping dependencies - Working with large packages that take time to download - Operating on machines with limited bandwidth - Running CI/CD pipelines where package caching can significantly improve build times ### Unpacking Without pixi-pack If you don't have `pixi-pack` available on your target system, and do not want to use self-extracting binaries (see above), you can still install the environment if you have `conda` or `micromamba` available. Just unarchive the `environment.tar`, then you have a local channel on your system where all necessary packages are available. Next to this local channel, you will find an `environment.yml` file that contains the environment specification. You can then install the environment using `conda` or `micromamba`: ```bash tar -xvf environment.tar micromamba create -p ./env --file environment.yml # or conda env create -p ./env --file environment.yml ``` Note The `environment.yml` and `repodata.json` files are only for this use case, `pixi-unpack` does not use them. Note Both `conda` and `mamba` are always installing pip as a side effect when they install python, see [`conda`'s documentation](https://docs.conda.io/projects/conda/en/25.1.x/user-guide/configuration/settings.html#add-pip-as-python-dependency-add-pip-as-python-dependency). This is different from how `pixi` works and can lead to solver errors when using `pixi-pack`'s compatibility mode since `pixi` doesn't include `pip` by default. You can fix this issue in two ways: - Add `pip` to your `pixi.lock` file using `pixi add pip`. - Configuring `conda` (or `mamba`) to not install `pip` by default by running `conda config --set add_pip_as_python_dependency false` (or by adding `add_pip_as_python_dependency: False` to your `~/.condarc`) # Prefix.dev Prefix.dev offers a fast, modern package hosting solution for Conda packages. ## Setting up your own Channel on prefix.dev First, sign up for an account on prefix.dev, using Github, Google or your email address. Create a channel by navigating to `Channels` and clicking "New Channel" Fill in the channel creation form: choose a *name*, a description and whether the channel should be public or private. Public channels are accessible without authentication. You can also use a GitHub avatar URL as a channel logo (e.g. `https://github.com/myaccount.png`). You have your channel! Now you can start uploading packages or adding members. ## Adding more channel members To manage members, navigate to your channel's settings and click on **Members** in the sidebar. To invite a new member, click **Invite member**, search for their username and select a role (e.g. Contributor or Viewer), then click **Add**. Note: there can be only a single channel *owner*, but you can transfer channel ownership in the channel settings as well. ## Uploading packages You can upload packages directly through the web interface. Navigate to **Upload Package** in the channel settings sidebar. Drag and drop `.conda` or `.tar.bz2` files (up to 1 GB) into the upload area, or click to select files from your filesystem. Alternatively, you can upload packages using the `pixi` (or `rattler-build`) CLI tool. To do so locally, you need to generate an API key for your user account (User -> Settings -> Api Keys). ```bash pixi upload prefix --channel --api-key $PREFIX_API_KEY ``` ## Using the channel in pixi Once your channel is set up and has packages, you can use it in your `pixi.toml`: ```toml [workspace] channels = ["https://prefix.dev/"] ``` For private channels, you need to authenticate first: ```bash pixi auth login --token https://prefix.dev ``` ## Deleting or transferring a channel Under **Delete or Transfer** in the channel settings, you can transfer ownership of the channel to another user or permanently delete the channel and all its packages. Warning Deleting a channel is irreversible and will remove all packages associated with it. Proceed with caution. ## Trusted Publishing Trusted publishing allows CI/CD pipelines to upload packages to your channel without needing long-lived API tokens. Instead, it uses OIDC (OpenID Connect) to establish trust between your CI provider and prefix.dev. This is more secure because credentials are short-lived and automatically scoped to specific workflows. Prefix.dev supports trusted publishing from **GitHub Actions**, **GitLab CI/CD**, and **Google Cloud**. ### Setting up a trusted publisher Navigate to **Trusted Publishers** in your channel settings sidebar and fill in the required fields: - **GitHub Username or Organization Name** β€” the owner of the repository - **Repository Name** β€” the repository that will publish packages - **Name of the Workflow File** β€” the workflow file that triggers the upload (e.g. `release-workflow.yml`) - **Environment Name** (optional) β€” restrict publishing to a specific GitHub environment (e.g. `production`) ### Using trusted publishing in GitHub Actions Once configured, your GitHub Actions workflow can upload packages without any stored secrets: ```yaml jobs: build-and-upload: runs-on: ubuntu-latest permissions: id-token: write # Required for OIDC token steps: - uses: actions/checkout@v4 - uses: prefix-dev/setup-pixi@v0.8.0 - run: pixi run build - run: pixi upload prefix --channel ./my-pkg*.conda ``` The `rattler-build-action` automatically handles the OIDC token exchange with prefix.dev when trusted publishing is configured for the repository and workflow. If you want to use S3 object storage to fetch your packages, you can use the `s3://` protocol as a channel. pixi.toml ```toml [workspace] # ... channels = ["s3://my-bucket/custom-channel"] ``` In the bucket, your objects need to adhere to the standard conda repository structure: ```text my-bucket/ custom-channel/ noarch/ repodata.json ... linux-64/ repodata.json ... ``` Pixi supports two ways to configure access to your S3 bucket: 1. Using AWS credentials from environment variables or AWS configuration files, like in any other AWS tool 1. Using pixi's configuration in combination with storing the credentials in pixi's authentication storage These two options are mutually exclusive! Specifying `s3-options` (see below) will deactivate the AWS credentials fetching. You can either use the AWS credentials from the conventional locations (by not specifying `s3-options`) or from pixi's authentication storage (by specifying `s3-options`). ## Using AWS configuration You can specify `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` in your environment variables for Pixi to use them. You can also specify `AWS_CONFIG_FILE` and `AWS_PROFILE` to use a custom AWS configuration file and profile. aws.config ```cfg [profile conda] sso_account_id = 123456789012 sso_role_name = PowerUserAccess sso_start_url = https://my-company.awsapps.com/start sso_region = eu-central-1 region = eu-central-1 output = json ``` CLI usage ```bash $ export AWS_CONFIG_FILE=/path/to/aws.config $ export AWS_PROFILE=conda $ aws sso login Attempting to automatically open the SSO authorization page in your default browser. If the browser does not open or you wish to use a different device to authorize this request, open the following URL: https://my-company.awsapps.com/start/#/device Then enter the code: DTBC-WFXC Successfully logged into Start URL: https://my-company.awsapps.com/start $ pixi search -c s3://my-s3-bucket/channel my-private-package # ... ``` ci.yml ```yaml jobs: ci: runs-on: ubuntu-latest steps: - name: Check out repository uses: actions/checkout@v4 # temporary credentials via OIDC - name: Log in to AWS uses: aws-actions/configure-aws-credentials@v4 with: role-to-assume: arn:aws:iam::123456789012:role/github-poweruser aws-region: eu-central-1 - name: Set up pixi # AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY are set by aws-actions/configure-aws-credentials uses: prefix-dev/setup-pixi@v0.8.3 ``` ## Using Pixi's Configuration You can specify the `workspace.s3-options` in your `pixi.toml` file. This might be useful when you want to use a custom S3-compatible host and not AWS's configuration. pixi.toml ```toml [workspace.s3-options.my-bucket] endpoint-url = "https://my-s3-host" region = "us-east-1" force-path-style = false ``` You need to configure this per bucket you use, i.e. use `[workspace.s3-options.]`. ```bash $ pixi auth login --aws-access-key-id=... --aws-secret-access-key=... s3://my-s3-bucket Authenticating with s3://my-s3-bucket $ pixi search my-private-package # ... ``` You can also specify the `s3-options` in your [Pixi configuration](../../reference/pixi_configuration/). Global configuration ```toml [s3-options.my-bucket] endpoint-url = "https://my-s3-host" region = "us-east-1" force-path-style = false ``` ci.yml ```yaml jobs: ci: runs-on: ubuntu-latest steps: - name: Check out repository uses: actions/checkout@v4 # temporary credentials via OIDC - name: Log in to AWS uses: aws-actions/configure-aws-credentials@v4 id: aws with: role-to-assume: arn:aws:iam::123456789012:role/github-poweruser aws-region: eu-central-1 - name: Set up pixi # AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY are set by aws-actions/configure-aws-credentials uses: prefix-dev/setup-pixi@v0.8.3 with: auth-s3-access-key-id: ${{ steps.aws.outputs.aws-access-key-id }} auth-s3-secret-access-key: ${{ steps.aws.outputs.aws-secret-access-key }} auth-s3-session-token: ${{ steps.aws.outputs.aws-session-token }} auth-host: s3://my-s3-bucket ``` ## Public S3 Buckets Public buckets that don't need authentication can be used by just specifying the endpoint as a regular `https` URL. For example, on AWS, you might have a bucket that is publicly accessible via `https://my-public-bucket.s3.eu-central-1.amazonaws.com`. pixi.toml ```toml [workspace] channels = ["https://my-public-bucket.s3.eu-central-1.amazonaws.com/channel"] ``` Note that for this, you need to configure your S3 bucket in such a way that it allows public access. On AWS, you need the `GetObject` and `ListBucket` permissions for this. Here is an example policy for AWS S3: Bucket policy ```json { "Version": "2012-10-17", "Statement": [ { "Sid": "PublicReadGetObject", "Effect": "Allow", "Principal": "*", "Action": "s3:GetObject", "Resource": "arn:aws:s3:::my-public-bucket/*" }, { "Sid": "PublicReadListBucket", "Effect": "Allow", "Principal": "*", "Action": "s3:ListBucket", "Resource": "arn:aws:s3:::my-public-bucket" } ] } ``` Cloudflare R2 also supports public buckets through a Cloudflare-managed `r2.dev` subdomain or a custom domain under your control, see [here](https://developers.cloudflare.com/r2/buckets/public-buckets/). ## S3-Compatible Storage Many other cloud providers offer S3-compatible storage APIs. You can use them with Pixi by specifying the `s3-options` in your manifest file. ### MinIO pixi.toml ```toml endpoint-url = "https://minio.example.com" region = "us-east-1" force-path-style = true ``` ### Cloudflare R2 pixi.toml ```toml endpoint-url = "https://.eu.r2.cloudflarestorage.com" region = "WEUR" force-path-style = false ``` ### Wasabi pixi.toml ```toml endpoint-url = "https://s3.de-1.wasabisys.com" region = "de-1" force-path-style = false ``` ### Backblaze B2 pixi.toml ```toml endpoint-url = "https://s3.us-west-004.backblazeb2.com" region = "us-west-004" force-path-style = true ``` ### Google Cloud Storage Note Pixi also supports `gcs://` URLs. pixi.toml ```toml endpoint-url = "https://storage.googleapis.com" region = "us-east-1" force-path-style = false ``` ### Hetzner Object Storage pixi.toml ```toml endpoint-url = "https://fsn1.your-objectstorage.com" region = "US" force-path-style = false ``` ## Uploading to S3 You can upload packages to S3 using `pixi upload s3`: ```bash pixi upload s3 \ --bucket my-s3-bucket \ --channel my-channel \ --region us-east-1 \ --endpoint-url https://my-s3-host \ my_package.conda ``` Use `pixi upload s3 --help` for all available options. When using `rattler-build` to build a `.conda` package you can also use `rattler-build upload s3`: for more information, see [rattler-build's documentation](https://rattler-build.prefix.dev/latest/authentication_and_upload/#s3). ### Re-indexing S3 buckets After Uploading new Packages Every time you upload new packages to your package repository, the `repodata.json` file needs to be updated. This is done automatically for conda package servers like anaconda.org or prefix.dev. For S3 buckets, on the other hand, we need to do this manually since an S3 bucket is only a storage system and not a package server. To re-index an S3 bucket, you can use the `rattler-index` package which is available on [conda-forge](https://prefix.dev/channels/conda-forge/packages/rattler-index). ```shell pixi exec rattler-index s3 s3://my-s3-bucket/my-channel \ --endpoint-url https://my-s3-host \ --region us-east-1 \ --force-path-style \ --access-key-id \ --secret-access-key ``` # Integration documentation We created [prefix-dev/setup-pixi](https://github.com/prefix-dev/setup-pixi) to facilitate using pixi in CI. ## Usage ```yaml - uses: prefix-dev/setup-pixi@v0.9.4 with: pixi-version: v0.66.0 cache: true auth-host: prefix.dev auth-token: ${{ secrets.PREFIX_DEV_TOKEN }} - run: pixi run test ``` Pin your action versions Since pixi is not yet stable, the API of this action may change between minor versions. Please pin the versions of this action to a specific version (i.e., `prefix-dev/setup-pixi@v0.9.4`) to avoid breaking changes. You can automatically update the version of this action by using [Dependabot](https://docs.github.com/en/code-security/dependabot/working-with-dependabot/keeping-your-actions-up-to-date-with-dependabot). Put the following in your `.github/dependabot.yml` file to enable Dependabot for your GitHub Actions: .github/dependabot.yml ```yaml version: 2 updates: - package-ecosystem: github-actions directory: / schedule: interval: monthly # (1)! groups: dependencies: patterns: - "*" cooldown: default-days: 7 ``` 1. or `daily`, `weekly` ## Features To see all available input arguments, see the [`action.yml`](https://github.com/prefix-dev/setup-pixi/blob/main/action.yml) file in `setup-pixi`. The most important features are described below. ### Caching The action supports caching of the project and global pixi environments. By default, project environment caching is enabled if a `pixi.lock` file is present. It will then use the `pixi.lock` file to generate a hash of the environment and cache it. If the cache is hit, the action will skip the installation and use the cached environment. You can specify the behavior by setting the `cache` input argument. Global environment caching is disabled by default and can be enabled by setting the `global-cache` input to `true`. As there is no lockfile for global environments, the cache will expire at the end of every month to ensure it does not go stale. Customize your cache key If you need to customize your cache-key, you can use the `cache-key` and `global-cache-key` input arguments. These will be the prefixes of the cache keys. The full cache keys will be `-` and `--` respectively. Only save caches on `main` In order to not exceed the [10 GB cache size limit](https://docs.github.com/en/actions/using-workflows/caching-dependencies-to-speed-up-workflows#usage-limits-and-eviction-policy) as fast, you might want to restrict when the cache is saved. This can be done by setting the `cache-write` argument. ```yaml - uses: prefix-dev/setup-pixi@v0.9.4 with: cache: true cache-write: ${{ github.event_name == 'push' && github.ref_name == 'main' }} ``` ### Multiple environments With pixi, you can create multiple environments for different requirements. You can also specify which environment(s) you want to install by setting the `environments` input argument. This will install all environments that are specified and cache them. ```toml [workspace] name = "my-package" channels = ["conda-forge"] platforms = ["linux-64"] [dependencies] python = ">=3.11" pip = "*" polars = ">=0.14.24,<0.21" [feature.py311.dependencies] python = "3.11.*" [feature.py312.dependencies] python = "3.12.*" [environments] py311 = ["py311"] py312 = ["py312"] ``` #### Multiple environments using a matrix The following example will install the `py311` and `py312` environments in different jobs. ```yaml test: runs-on: ubuntu-latest strategy: matrix: environment: [py311, py312] steps: - uses: actions/checkout@v4 - uses: prefix-dev/setup-pixi@v0.9.4 with: environments: ${{ matrix.environment }} ``` #### Install multiple environments in one job The following example will install both the `py311` and the `py312` environment on the runner. ```yaml - uses: prefix-dev/setup-pixi@v0.9.4 with: environments: >- # (1)! py311 py312 - run: | pixi run -e py311 test pixi run -e py312 test ``` 1. separated by spaces, equivalent to ```yaml environments: py311 py312 ``` Caching behavior if you don't specify environments If you don't specify any environment, the `default` environment will be installed and cached, even if you use other environments. ### Global Environments You can specify `pixi global install` commands by setting the `global-environments` input argument. This will create one environment per line, and install them. This is useful in particular to install executables that are needed for `pixi install` to work properly. For instance, the `keyring`, or `gcloud` executables. The following example shows how to install both in separate global environments. By default, global environments are not cached. You can enable caching by setting the `global-cache` input to `true`. ```yaml - uses: prefix-dev/setup-pixi@v0.9.4 with: global-environments: | google-cloud-sdk keyring --with keyrings.google-artifactregistry-auth - run: | gcloud --version keyring --list-backends ``` ### Authentication There are currently five ways to authenticate with pixi: - using a token - using a username and password - using a conda-token - using an S3 key pair - using keyring for PyPI registries For more information, see [Authentication](../../../deployment/authentication/). Handle secrets with care Please only store sensitive information using [GitHub secrets](https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions). Do not store them in your repository. When your sensitive information is stored in a GitHub secret, you can access it using the `${{ secrets.SECRET_NAME }}` syntax. These secrets will always be masked in the logs. #### Token Specify the token using the `auth-token` input argument. This form of authentication (bearer token in the request headers) is mainly used at [prefix.dev](https://prefix.dev). ```yaml - uses: prefix-dev/setup-pixi@v0.9.4 with: auth-host: prefix.dev auth-token: ${{ secrets.PREFIX_DEV_TOKEN }} ``` #### Username and password Specify the username and password using the `auth-username` and `auth-password` input arguments. This form of authentication (HTTP Basic Auth) is used in some enterprise environments with [artifactory](https://jfrog.com/artifactory) for example. ```yaml - uses: prefix-dev/setup-pixi@v0.9.4 with: auth-host: custom-artifactory.com auth-username: ${{ secrets.PIXI_USERNAME }} auth-password: ${{ secrets.PIXI_PASSWORD }} ``` #### Conda-token Specify the conda-token using the `conda-token` input argument. This form of authentication (token is encoded in URL: `https://my-quetz-instance.com/t//get/custom-channel`) is used at [anaconda.org](https://anaconda.org) or with [quetz instances](https://github.com/mamba-org/quetz). ```yaml - uses: prefix-dev/setup-pixi@v0.9.4 with: auth-host: anaconda.org # (1)! auth-conda-token: ${{ secrets.CONDA_TOKEN }} ``` 1. or my-quetz-instance.com #### S3 Specify the S3 key pair using the `auth-access-key-id` and `auth-secret-access-key` input arguments. You can also specify the session token using the `auth-session-token` input argument. ```yaml - uses: prefix-dev/setup-pixi@v0.9.4 with: auth-host: s3://my-s3-bucket auth-s3-access-key-id: ${{ secrets.ACCESS_KEY_ID }} auth-s3-secret-access-key: ${{ secrets.SECRET_ACCESS_KEY }} auth-s3-session-token: ${{ secrets.SESSION_TOKEN }} # (1)! ``` 1. only needed if your key uses a session token See the [S3 section](../../../deployment/s3/) for more information about S3 authentication. #### PyPI keyring provider You can specify whether to use keyring to look up credentials for PyPI. ```text - uses: prefix-dev/setup-pixi@v0.9.4 with: pypi-keyring-provider: subprocess # one of 'subprocess', 'disabled' ``` ### Custom shell wrapper `setup-pixi` allows you to run command inside of the pixi environment by specifying a custom shell wrapper with `shell: pixi run bash -e {0}`. This can be useful if you want to run commands inside of the pixi environment, but don't want to use the `pixi run` command for each command. ```yaml - run: | # (1)! python --version pip install --no-deps -e . shell: pixi run bash -e {0} ``` 1. everything here will be run inside of the pixi environment You can even run Python scripts like this: ```yaml - run: | # (1)! import my_package print("Hello world!") shell: pixi run python {0} ``` 1. everything here will be run inside of the pixi environment If you want to use PowerShell, you need to specify `-Command` as well. ```yaml - run: | # (1)! python --version | Select-String "3.11" shell: pixi run pwsh -Command {0} # pwsh works on all platforms ``` 1. everything here will be run inside of the pixi environment How does it work under the hood? Under the hood, the `shell: xyz {0}` option is implemented by creating a temporary script file and calling `xyz` with that script file as an argument. This file does not have the executable bit set, so you cannot use `shell: pixi run {0}` directly but instead have to use `shell: pixi run bash {0}`. There are some custom shells provided by GitHub that have slightly different behavior, see [`jobs..steps[*].shell`](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsshell) in the documentation. See the [official documentation](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#custom-shell) and [ADR 0277](https://github.com/actions/runner/blob/main/docs/adrs/0277-run-action-shell-options.md) for more information about how the `shell:` input works in GitHub Actions. #### One-off shell wrapper using `pixi exec` With `pixi exec`, you can also run a one-off command inside a temporary pixi environment. ```yaml - run: | # (1)! zstd --version shell: pixi exec --spec zstd -- bash -e {0} ``` 1. everything here will be run inside of the temporary pixi environment ```yaml - run: | # (1)! import ruamel.yaml # ... shell: pixi exec --spec python=3.11.* --spec ruamel.yaml -- python {0} ``` 1. everything here will be run inside of the temporary pixi environment See [here](../../../reference/cli/pixi/exec/) for more information about `pixi exec`. ### Environment activation Instead of using a custom shell wrapper, you can also make all pixi-installed binaries available to subsequent steps by "activating" the installed environment in the currently running job. To this end, `setup-pixi` adds all environment variables set when executing `pixi run` to `$GITHUB_ENV` and, similarly, adds all path modifications to `$GITHUB_PATH`. As a result, all installed binaries can be accessed without having to call `pixi run`. ```yaml - uses: prefix-dev/setup-pixi@v0.9.4 with: activate-environment: true ``` If you are installing multiple environments, you will need to specify the name of the environment that you want to be activated. ```yaml - uses: prefix-dev/setup-pixi@v0.9.4 with: environments: >- py311 py312 activate-environment: py311 ``` Activating an environment may be more useful than using a custom shell wrapper as it allows non-shell based steps to access binaries on the path. However, be aware that this option augments the environment of your job. ### `--frozen` and `--locked` You can specify whether `setup-pixi` should run `pixi install --frozen` or `pixi install --locked` depending on the `frozen` or the `locked` input argument. See the [official documentation](../../../reference/cli/pixi/install/#update-options) for more information about the `--frozen` and `--locked` flags. ```yaml - uses: prefix-dev/setup-pixi@v0.9.4 with: locked: true # or frozen: true ``` If you don't specify anything, the default behavior is to run `pixi install --locked` if a `pixi.lock` file is present and `pixi install` otherwise. ### Debugging There are two types of debug logging that you can enable. #### Debug logging of the action The first one is the debug logging of the action itself. This can be enabled by for the action by re-running the action in debug mode: Debug logging documentation For more information about debug logging in GitHub Actions, see [the official documentation](https://docs.github.com/en/actions/monitoring-and-troubleshooting-workflows/enabling-debug-logging). #### Debug logging of pixi The second type is the debug logging of the pixi executable. This can be specified by setting the `log-level` input. ```yaml - uses: prefix-dev/setup-pixi@v0.9.4 with: log-level: vvv # (1)! ``` 1. One of `q`, `default`, `v`, `vv`, or `vvv`. If nothing is specified, `log-level` will default to `default` or `vv` depending on if [debug logging is enabled for the action](#debug-logging-of-the-action). ### Self-hosted runners On self-hosted runners, it may happen that some files are persisted between jobs. This can lead to problems or secrets getting leaked between job runs. To avoid this, you can use the `post-cleanup` input to specify the post cleanup behavior of the action (i.e., what happens *after* all your commands have been executed). If you set `post-cleanup` to `true`, the action will delete the following files: - `.pixi` environment - the pixi binary - the rattler cache - other rattler files in `~/.rattler` If nothing is specified, `post-cleanup` will default to `true`. On self-hosted runners, you also might want to alter the default pixi install location to a temporary location. You can use `pixi-bin-path: ${{ runner.temp }}/bin/pixi` to do this. ```yaml - uses: prefix-dev/setup-pixi@v0.9.4 with: post-cleanup: true pixi-bin-path: ${{ runner.temp }}/bin/pixi # (1)! ``` 1. `${{ runner.temp }}\Scripts\pixi.exe` on Windows You can also use a preinstalled local version of pixi on the runner by not setting any of the `pixi-version`, `pixi-url` or `pixi-bin-path` inputs. This action will then try to find a local version of pixi in the runner's PATH. ### Using the `pyproject.toml` as a manifest file for pixi. `setup-pixi` will automatically pick up the `pyproject.toml` if it contains a `[tool.pixi.workspace]` section and no `pixi.toml`. This can be overwritten by setting the `manifest-path` input argument. ```yaml - uses: prefix-dev/setup-pixi@v0.9.4 with: manifest-path: pyproject.toml ``` ### Working directory for monorepos If you're working with a monorepo where your pixi project is in a subdirectory, you can use the `working-directory` input to specify where pixi should look for manifest files (`pixi.toml` or `pyproject.toml`). ```text - uses: prefix-dev/setup-pixi@v0.9.4 with: working-directory: ./packages/my-project ``` This will make pixi look for `pixi.toml` or `pyproject.toml` in the `./packages/my-project` directory instead of the repository root. All pixi commands will be executed from this working directory. Also in other steps The `working-directory` input only affects commands run by `setup-pixi` itself. For subsequent `run:` steps, you need to set the working directory separately: ```text - run: pixi run test working-directory: ./packages/my-project ``` You can combine `working-directory` with `manifest-path` if needed: ```text - uses: prefix-dev/setup-pixi@v0.9.4 with: working-directory: ./packages/my-project manifest-path: custom-pixi.toml ``` ### Only install pixi If you only want to install pixi and not install the current workspace, you can use the `run-install` option. ```text - uses: prefix-dev/setup-pixi@v0.9.4 with: run-install: false ``` ### Download pixi from a custom URL You can also download pixi from a custom URL by setting the `pixi-url` input argument. Optionally, you can combine this with the `pixi-url-headers` input argument to supply additional headers for the download request, such as a bearer token. ```text - uses: prefix-dev/setup-pixi@v0.9.4 with: pixi-url: https://pixi-mirror.example.com/releases/download/v0.48.0/pixi-x86_64-unknown-linux-musl pixi-url-headers: '{"Authorization": "Bearer ${{ secrets.PIXI_MIRROR_BEARER_TOKEN }}"}' ``` The `pixi-url` input argument can also be a [Handlebars](https://handlebarsjs.com/) template string. It will be rendered with the following variables: - `version`: The version of pixi that is being installed (`latest` or a version like `v0.48.0`). - `latest`: A boolean indicating if the version is `latest`. - `pixiFile`: The name of the pixi binary to download, as determined by the system of the runner (e.g., `pixi-x86_64-unknown-linux-musl`). By default, `pixi-url` is equivalent to the following template: ```text - uses: prefix-dev/setup-pixi@v0.9.4 with: pixi-url: | {{#if latest~}} https://github.com/prefix-dev/pixi/releases/latest/download/{{pixiFile}} {{~else~}} https://github.com/prefix-dev/pixi/releases/download/{{version}}/{{pixiFile}} {{~/if}} ``` ### Setting inputs from environment variables Alternatively to setting the inputs in the `with` section, you can also set each of them using environment variables. The corresponding environment variable names are derived from the input names by converting them to uppercase, replacing hyphens with underscores, and prefixing them with `SETUP_PIXI_`. For example, the `pixi-bin-path` input can be set using the `SETUP_PIXI_PIXI_BIN_PATH` environment variable. This is particularly useful if executing the action on a self-hosted runner. Inputs always take precedence over environment variables. ## More examples If you want to see more examples, you can take a look at the [GitHub Workflows of the `setup-pixi` repository](https://github.com/prefix-dev/setup-pixi/blob/main/.github/workflows/test.yml). You can leverage GitHub Actions in combination with [pavelzw/pixi-diff-to-markdown](https://github.com/pavelzw/pixi-diff-to-markdown) to automatically update your lockfiles similar to dependabot or renovate in other ecosystems. Dependabot/Renovate support for pixi You can track native Dependabot support for pixi in [dependabot/dependabot-core #2227](https://github.com/dependabot/dependabot-core/issues/2227#issuecomment-1709069470). ## How to use To get started, create a new GitHub Actions workflow file in your repository. .github/workflows/update-lockfiles.yml ```yaml name: Update lockfiles permissions: # (1)! contents: write pull-requests: write on: workflow_dispatch: schedule: - cron: 0 5 1 * * # (2)! jobs: pixi-update: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: Set up pixi uses: prefix-dev/setup-pixi@v0.8.3 with: run-install: false - name: Update lockfiles run: | set -o pipefail pixi update --json | pixi exec pixi diff-to-markdown >> diff.md - name: Create pull request uses: peter-evans/create-pull-request@v7 with: token: ${{ secrets.GITHUB_TOKEN }} commit-message: Update pixi lockfile title: Update pixi lockfile body-path: diff.md branch: update-pixi base: main labels: pixi delete-branch: true add-paths: pixi.lock ``` 1. Needed for `peter-evans/create-pull-request` 1. Runs at 05:00, on day 1 of the month In order for this workflow to work, you need to set "Allow GitHub Actions to create and approve pull requests" to true in your repository settings (in "Actions" -> "General"). Tip If you don't have any `pypi-dependencies`, you can use `pixi update --json --no-install` to speed up diff generation. ## Triggering CI in automated PRs In order to prevent accidental recursive GitHub Workflow runs, GitHub decided to not trigger any workflows on automated PRs when using the default `GITHUB_TOKEN`. There are a couple of ways how to work around this limitation. You can find excellent documentation for this in `peter-evans/create-pull-request`, see [here](https://github.com/peter-evans/create-pull-request/blob/main/docs/concepts-guidelines.md#triggering-further-workflow-runs). ## Customizing the summary You can customize the summary by either using command-line-arguments of `pixi-diff-to-markdown` or by specifying the configuration in `pixi.toml` under `[tool.pixi-diff-to-markdown]`. See the [pixi-diff-to-markdown documentation](https://github.com/pavelzw/pixi-diff-to-markdown) or run `pixi-diff-to-markdown --help` for more information. ## Using reusable workflows If you want to use the same workflow in multiple repositories in your GitHub organization, you can create a reusable workflow. You can find more information in the [GitHub documentation](https://docs.github.com/en/actions/using-workflows/reusing-workflows). Native Pixi support on YouTrack There is a tracking issue for native Pixi support in PyCharm, [PY-79041](https://youtrack.jetbrains.com/issue/PY-79041). Feel free to upvote it if it is relevant to you. For CLion, you can track [CPP-42761](https://youtrack.jetbrains.com/issue/CPP-42761). ## Pycharm You can use PyCharm with Pixi environments by using the `conda` shim provided by the [pixi-pycharm](https://github.com/pavelzw/pixi-pycharm) package. *An [alternate approach](#alt-approach) that does not use the shim is also described below.* To get started, add `pixi-pycharm` to your Pixi workspace. ```bash pixi add pixi-pycharm ``` This will ensure that the conda shim is installed in your workspace's environment. Having `pixi-pycharm` installed, you can now configure PyCharm to use your Pixi environments. Go to the *Add Python Interpreter* dialog (bottom right corner of the PyCharm window) and select *Conda Environment*. Set *Conda Executable* to the full path of the `conda` file (on Windows: `conda.bat`) which is located in `.pixi/envs/default/libexec`. You can get the path using the following command: ```bash pixi run 'echo $CONDA_PREFIX/libexec/conda' ``` ```bash pixi run 'echo $CONDA_PREFIX\\libexec\\conda.bat' ``` This is an executable that tricks PyCharm into thinking it's the proper `conda` executable. Under the hood it redirects all calls to the corresponding `pixi` equivalent. Use the conda shim from this Pixi workspace Please make sure that this is the `conda` shim from this Pixi workspace and not another one. If you use multiple Pixi workspaces, you might have to adjust the path accordingly as PyCharm remembers the path to the conda executable. Having selected the environment, PyCharm will now use the Python interpreter from your Pixi environment. PyCharm should now be able to show you the installed packages as well. You can now run your programs and tests as usual. Mark `.pixi` as excluded In order for PyCharm to not get confused about the `.pixi` directory, please mark it as excluded. Also, when using a remote interpreter, you should exclude the `.pixi` directory on the remote machine. Instead, you should run `pixi install` on the remote machine and select the conda shim from there. ### Multiple environments If your workspace uses [multiple environments](../../../workspace/multi_environment/) to tests different Python versions or dependencies, you can add multiple environments to PyCharm by specifying *Use existing environment* in the *Add Python Interpreter* dialog. You can then specify the corresponding environment in the bottom right corner of the PyCharm window. ### Multiple Pixi workspaces When using multiple Pixi workspaces, remember to select the correct *Conda Executable* for each workspace as mentioned above. It also might come up that you have multiple environments with the same name. It is recommended to rename the environments to something unique. ### Debugging Logs are written to `~/.cache/pixi-pycharm.log`. You can use them to debug problems. Please attach the logs when [filing a bug report](https://github.com/pavelzw/pixi-pycharm/issues/new?template=bug-report.md). ### Install as an optional dependency In some cases, you might only want to install `pixi-pycharm` on your local dev-machines but not in production. To achieve this, we can use [multiple environments](../../../workspace/multi_environment/). ```toml [workspace] name = "multi-env" version = "0.1.0" requires-python = ">=3.12" dependencies = ["numpy"] [tool.pixi.workspace] channels = ["conda-forge"] platforms = ["linux-64"] [tool.pixi.feature.lint.dependencies] ruff = "*" [tool.pixi.feature.dev.dependencies] pixi-pycharm = "*" [tool.pixi.environments] # The production environment is the default feature set. # Adding a solve group to make sure the same versions are used in the `default` and `prod` environments. prod = { solve-group = "main" } # Setup the default environment to include the dev features. # By using `default` instead of `dev` you'll not have to specify the `--environment` flag when running `pixi run`. default = { features = ["dev"], solve-group = "main" } # The lint environment doesn't need the default feature set but only the `lint` feature # and thus can also be excluded from the solve group. lint = { features = ["lint"], no-default-feature = true } ``` Now you as a user can run `pixi shell`, which will start the default environment. In production, you then just run `pixi run -e prod COMMAND`, and the minimal prod environment is installed. ### Alternate approach using environments.txt There is another approach for configuring PyCharm that avoids the need for the pixi-pycharm shim. It requires that you have conda installed locally (PyCharm will detect it automatically if installed in a standard location). To configure an interpreter for a new workspace: 1. Edit conda's environment list located at `~/.conda/environments.txt`. Simply append the full file paths of any pixi environments you wish to include, e.g.: ```text ... /Users/jdoe/my-workspace/.pixi/envs/default /Users/jdoe/my-workspace/.pixi/envs/dev ``` 1. In PyCharm, when adding the interpreter for your workspace, scroll down to the bottom of the Python Interpreter dropdown menu and choose *Show All ...* to bring up the Python Interpreters dialog. 1. Select the `+` button to add a new local existing conda interpreter using the standard conda location and choose the desired prefix from the list. (If you edited the environment file while PyCharm was running, you may need to reload the environments.) 1. This will add the environment but will automatically give it a name matching the last component of the directory path, which will often just be `default` for pixi environments. This is particularly problematic if you work on many workspaces. You can change PyCharm's name for the environment by clicking on the pencil icon or using the right-click dropdown menu. 1. Once you have added and renamed the environments, select the desired interpreter to use in PyCharm from the list. If your workspace uses more than one environment, you can switch between them by selecting interpreter name in the status bar at the bottom of the PyCharm window and selecting the interpreter for the desired interpreter from the list. Note that this will trigger PyCharm reindexing and might not be very fast. As with the pixi-pycharm shim, you should avoid using the PyCharm UI to attempt to add or remove packages from your environments and you should make sure to [exclude the `.pixi` directory from PyCharm indexing](#exclude-.pixi). ## Direnv In order to use Direnv with [Jetbrains](https://www.jetbrains.com/ides/) products you first have to install the [Direnv plugin](https://plugins.jetbrains.com/plugin/15285-direnv-integration). Then follow the instructions in our [Direnv doc page](../../third_party/direnv/). Now your Jetbrains IDE will be run within the selected Pixi environment. ## Basic usage Using JupyterLab with Pixi is very simple. You can just create a new Pixi workspace and add the `jupyterlab` package to it. The full example is provided under the following [Github link](https://github.com/prefix-dev/pixi/tree/main/examples/jupyterlab). ```bash pixi init pixi add jupyterlab ``` This will create a new Pixi workspace and add the `jupyterlab` package to it. You can then start JupyterLab using the following command: ```bash pixi run jupyter lab ``` If you want to add more "kernels" to JupyterLab, you can simply add them to your current workspace – as well as any dependencies from the scientific stack you might need. ```bash pixi add bash_kernel ipywidgets matplotlib numpy pandas # ... ``` ### What kernels are available? You can easily install more "kernels" for JupyterLab. The `conda-forge` repository has a number of interesting additional kernels - not just Python! - [**`bash_kernel`**](https://prefix.dev/channels/conda-forge/packages/bash_kernel) A kernel for bash - [**`xeus-cpp`**](https://prefix.dev/channels/conda-forge/packages/xeus-cpp) A C++ kernel based on the new clang-repl - [**`xeus-cling`**](https://prefix.dev/channels/conda-forge/packages/xeus-cling) A C++ kernel based on the slightly older Cling - [**`xeus-lua`**](https://prefix.dev/channels/conda-forge/packages/xeus-lua) A Lua kernel - [**`xeus-sql`**](https://prefix.dev/channels/conda-forge/packages/xeus-sql) A kernel for SQL - [**`r-irkernel`**](https://prefix.dev/channels/conda-forge/packages/r-irkernel) An R kernel ## Advanced usage If you want to have only one instance of JupyterLab running but still want per-directory Pixi environments, you can use one of the kernels provided by the [**`pixi-kernel`**](https://prefix.dev/channels/conda-forge/packages/pixi-kernel) package. ### Configuring JupyterLab To get started, create a Pixi workspace, add `jupyterlab` and `pixi-kernel` and then start JupyterLab: ```bash pixi init pixi add jupyterlab pixi-kernel pixi run jupyter lab ``` This will start JupyterLab and open it in your browser. `pixi-kernel` searches for a manifest file, either `pixi.toml` or `pyproject.toml`, in the same directory of your notebook or in any parent directory. When it finds one, it will use the environment specified in the manifest file to start the kernel and run your notebooks. You can use `pixi` to manage your R dependencies. The conda-forge channel contains a wide range of R packages that can be installed using `pixi`. ## Installing R packages R packages are usually prefixed with `r-` in the conda-forge channel. To install an R package, you can use the following command: ```bash pixi add r- # for example pixi add r-ggplot2 ``` ## Using R packages in RStudio To use the R packages installed by `pixi` in RStudio, you need to run `rstudio` from an activated environment. This can be achieved by running RStudio from `pixi shell` or from a task in the `pixi.toml` file. ## Full example The full example can be found here: [RStudio example](https://github.com/prefix-dev/pixi/tree/main/examples/r). Here is an example of a `pixi.toml` file that sets up an RStudio task: ```toml [workspace] name = "r" channels = ["conda-forge"] platforms = ["linux-64", "osx-64", "osx-arm64"] [target.linux.tasks] rstudio = "rstudio" [target.osx.tasks] rstudio = "open -a rstudio" # or alternatively with the full path: # rstudio = "/Applications/RStudio.app/Contents/MacOS/RStudio" [dependencies] r = ">=4.3,<5" r-ggplot2 = ">=3.5.0,<3.6" ``` Once RStudio has loaded, you can execute the following R code that uses the `ggplot2` package: ```R # Load the ggplot2 package library(ggplot2) # Load the built-in 'mtcars' dataset data <- mtcars # Create a scatterplot of 'mpg' vs 'wt' ggplot(data, aes(x = wt, y = mpg)) + geom_point() + labs(x = "Weight (1000 lbs)", y = "Miles per Gallon") + ggtitle("Fuel Efficiency vs. Weight") ``` Note This example assumes that you have installed RStudio system-wide. We are working on updating RStudio as well as the R interpreter builds on Windows for maximum compatibility with `pixi`. [Visual Studio Code](https://code.visualstudio.com/) is a popular editor that can be extended to support most programming languages by installing the suitable extension. ## Python Extension First, install the Python extension from the [marketplace](https://marketplace.visualstudio.com/items?itemName=ms-python.python). Typically, the extension will detect and select the Pixi default environment automatically as soon as you open a Python file. In case it doesn't or you want to select a different environment, you can open the environment selector to select the environment of your choice. ## Direnv Extension Direnv provides a language agnostic way of running VSCode in a Pixi environment. First, install the Direnv extension from the [marketplace](https://marketplace.visualstudio.com/items?itemName=mkhl.direnv). Then follow the instructions in our [Direnv doc page](../../third_party/direnv/). ## Devcontainer Extension [VSCode Devcontainers](https://code.visualstudio.com/docs/devcontainers/containers) are a popular tool to develop on a workspace with a consistent environment. They are also used in [GitHub Codespaces](https://github.com/features/codespaces) which makes it a great way to develop on a workspace without having to install anything on your local machine. To use pixi inside of a devcontainer, follow these steps: Create a new directory `.devcontainer` in the root of your workspace. Then, create the following two files in the `.devcontainer` directory: .devcontainer/Dockerfile ```dockerfile FROM mcr.microsoft.com/devcontainers/base:jammy ARG PIXI_VERSION=v0.66.0 RUN curl -L -o /usr/local/bin/pixi -fsSL --compressed "https://github.com/prefix-dev/pixi/releases/download/${PIXI_VERSION}/pixi-$(uname -m)-unknown-linux-musl" \ && chmod +x /usr/local/bin/pixi \ && pixi info # set some user and workdir settings to work nicely with vscode USER vscode WORKDIR /home/vscode RUN echo 'eval "$(pixi completion -s bash)"' >> /home/vscode/.bashrc ``` .devcontainer/devcontainer.json ```json { "name": "my-workspace", "build": { "dockerfile": "Dockerfile", "context": "..", }, "customizations": { "vscode": { "settings": {}, "extensions": ["ms-python.python", "charliermarsh.ruff", "GitHub.copilot"] } }, "features": { "ghcr.io/devcontainers/features/docker-in-docker:2": {} }, "mounts": ["source=${localWorkspaceFolderBasename}-pixi,target=${containerWorkspaceFolder}/.pixi,type=volume"], "postCreateCommand": "sudo chown vscode .pixi && pixi install" } ``` Put `.pixi` in a mount In the above example, we mount the `.pixi` directory into a volume. This is needed since the `.pixi` directory shouldn't be on a case insensitive filesystem (default on macOS, Windows) but instead in its own volume. There are some conda packages (for example [ncurses-feedstock#73](https://github.com/conda-forge/ncurses-feedstock/issues/73)) that contain files that only differ in case which leads to errors on case insensitive filesystems. ## Secrets If you want to authenticate to a private conda channel, you can add secrets to your devcontainer. .devcontainer/devcontainer.json ```json { "build": "Dockerfile", "context": "..", "options": [ "--secret", "id=prefix_dev_token,env=PREFIX_DEV_TOKEN", ], // ... } ``` .devcontainer/Dockerfile ```dockerfile # ... RUN --mount=type=secret,id=prefix_dev_token,uid=1000 \ test -s /run/secrets/prefix_dev_token \ && pixi auth login --token "$(cat /run/secrets/prefix_dev_token)" https://repo.prefix.dev ``` These secrets need to be present either as an environment variable when starting the devcontainer locally or in your [GitHub Codespaces settings](https://github.com/settings/codespaces) under `Secrets`. [Zed](https://zed.dev/) is a code editor that provides support for many languages out of the box. By installing extensions more languages can be supported. ## Python Zed supports Pixi and Python out of the box. If Zed hasn't done so already, select a suitable Pixi environment in the environment selector and you are good to go! ## Direnv Zed supports Direnv out of the box. Set up Direnv with Pixi as described in our [Direnv page](../../third_party/direnv/) and Zed will activate the environment automatically. # Pixi Extensions `Pixi` allows you to extend its functionality with various extensions. When executing e.g. `pixi diff`, Pixi will search for the executable `pixi-diff` in your PATH and in your pixi global directories. Then it will execute it by passing any additional arguments to it. ## How Extensions Work Pixi extensions are standalone executables that follow a simple naming convention: they must be named `pixi-{command}` where `{command}` is the name of the subcommand you want to add. When you run `pixi {command}`, Pixi will automatically discover and execute the corresponding `pixi-{command}` executable. For example: - `pixi diff` β†’ looks for `pixi-diff` executable - `pixi pack` β†’ looks for `pixi-pack` executable - `pixi deploy` β†’ looks for `pixi-deploy` executable ## Extension Discovery Pixi discovers extensions by searching for `pixi-*` executables in the following locations, in order: ### 1. PATH Environment Variable Pixi searches all directories in your `PATH` environment variable for executables with the `pixi-` prefix. ### 2. `pixi global` Directories Pixi also searches in directories managed by `pixi global`, which allows for organized extension management without cluttering your system PATH. When you run `pixi --list`, all discovered extensions are automatically listed alongside all built-in commands, making the commands easily discoverable. ## Installing Extensions ### Using `pixi global` (Recommended) The easiest way to install Pixi extensions is using `pixi global install`: ```bash # Install a single extension pixi global install pixi-pack # Install multiple extensions at once pixi global install pixi-pack pixi-diff ``` This approach has several advantages: - **Isolated environments**: Each extension gets its own environment, preventing dependency conflicts - **Automatic discovery**: Extensions are automatically found by Pixi without modifying PATH - **Easy management**: Use `pixi global list` and `pixi global remove` to manage extensions - **Consistent experience**: Extensions appear in `pixi --list` with all the built-in commands, just like how `Cargo` handles it ### Manual Installation You can also install extensions manually by placing the executable in any directory in your PATH: ```bash # Download or build the extension curl -L https://github.com/user/pixi-myext/releases/download/v1.0.0/pixi-myext -o pixi-myext chmod +x pixi-myext mv pixi-myext ~/.local/bin/ ``` ## Contributing Extensions ### Creating an Extension 1. **Choose a descriptive name**: Your extension should be named `pixi-{command}` where `{command}` clearly describes its functionality. 1. **Create the executable**: Extensions can be written in any language (Rust, Python, shell scripts, etc.) as long as they produce an executable binary. 1. **Handle arguments**: Extensions receive all arguments passed after the command name. ### Example: Simple Python Extension ```python #!/usr/bin/env python3 import sys def main(): name = sys.argv[1] if len(sys.argv) > 1 else "World" print(f"Hello, {name}!") if __name__ == "__main__": main() ``` Save this as `pixi-hello`, make it executable (`chmod +x pixi-hello`), and place it in your PATH. Usage: `pixi hello Alice` outputs `Hello, Alice!` ## Best Practices - **Use standard argument parsing**: Libraries like `clap` (Rust) or `argparse` (Python) provide consistent behavior - **Support `--help`**: Users expect this standard flag - **Follow UNIX conventions**: Use exit code 0 for success, non-zero for errors - **Work with Pixi environments**: Extensions should respect Pixi's environment management ## Command Suggestions Pixi includes intelligent command suggestions powered by string similarity. If you mistype a command name, Pixi will suggest the closest match from both built-in commands and available extensions: ```bash $ pixi pck error: unrecognized subcommand 'pck` tip: a similar subcommand exists: 'pack' ``` This works for both built-in commands and any extensions you have installed, making extension discovery seamless. ## Getting Help - **List available extensions**: Run `pixi --list` to see all available extensions - **Community**: Join our [Discord](https://discord.gg/kKV8ZxyzY4) for discussions and support ## See Also - [Pixi Diff](../pixi_diff/) - Compare lock files and environments - [Pixi Inject](../pixi_inject/) - Inject dependencies into existing environments - [Pixi Skills](../pixi_skills/) - Manage and install coding agent skills across LLM backends - [Global Tools](../../../global_tools/introduction/) - Managing global tool installations [pixi-browse](https://github.com/pavelzw/pixi-browse) is an interactive terminal UI for browsing conda package metadata. Explore packages, versions, dependencies, and more from any conda channel, right from your terminal. ## Features - **Browse packages** from any conda channel (conda-forge, prefix.dev, etc.) - **Fuzzy search** to quickly filter through thousands of packages - **Inspect versions** grouped by platform with collapsible sections - **View detailed metadata** including dependencies, license, checksums, build info, and timestamps - **Inspect package contents** β€” file listings and `about.json` extracted directly from artifacts - **Clickable links** to source repositories, maintainer GitHub profiles, and provenance commits - **Download artifacts** directly to your working directory - **Vim-style keybindings** for fast keyboard-driven navigation ## Installation ```bash pixi global install pixi-browse ``` Or use it without installation: ```bash pixi exec pixi-browse ``` ## Usage ```bash # Browse conda-forge (default) pixi browse # Browse a different channel pixi browse -c prefix.dev/conda-forge # Restrict to specific platforms pixi browse -p linux-64 -p osx-arm64 ``` It can happen that you want to know what changed in your lockfile after repeatedly adding and removing dependencies within a pull request. For this, you can use [pavelzw/pixi-diff](https://github.com/pavelzw/pixi-diff) to calculate the differences between two lockfiles. This can be leveraged in combination with [pavelzw/pixi-diff-to-markdown](https://github.com/pavelzw/pixi-diff-to-markdown) to generate a markdown file that shows the diff in a human-readable format. With [charmbracelet/glow](https://github.com/charmbracelet/glow), you can even render the markdown file in the terminal. Install the tools globally All of the above-mentioned tools are available on conda-forge and can be installed using [`pixi global install`](../../../global_tools/introduction/). ```bash pixi global install pixi-diff pixi-diff-to-markdown glow-md ``` `pixi diff --before pixi.lock.old --after pixi.lock.new` will output a JSON object that contains the differences between the two lockfiles similar to [`pixi update --json`](../../../reference/cli/pixi/update/). ```bash $ pixi diff --before pixi.lock.old --after pixi.lock.new { "version": 1, "environment": { "default": { "osx-arm64": [ { "name": "libmpdec", "before": null, "after": { "conda": "https://conda.anaconda.org/conda-forge/osx-arm64/libmpdec-4.0.0-h99b78c6_0.conda", "sha256": "f7917de9117d3a5fe12a39e185c7ce424f8d5010a6f97b4333e8a1dcb2889d16", "md5": "7476305c35dd9acef48da8f754eedb40", "depends": [ "__osx >=11.0" ], "license": "BSD-2-Clause", "license_family": "BSD", "size": 69263, "timestamp": 1723817629767 }, "type": "conda" }, // ... ``` Named pipes can be handy for comparing lockfiles from different states in your git history: ```bash # bash / zsh pixi diff --before <(git show HEAD~20:pixi.lock) --after pixi.lock # fish pixi diff --before (git show HEAD~20:pixi.lock | psub) --after pixi.lock ``` Or specify either the "before" or "after" lockfile via stdin: ```bash git show HEAD~20:pixi.lock | pixi diff --before - --after pixi.lock ``` This can be integrated with [`pixi-diff-to-markdown`](https://github.com/pavelzw/pixi-diff-to-markdown) to generate a markdown file that shows the diff in a human-readable format: ```bash pixi diff <(git show HEAD~20:pixi.lock) pixi.lock | pixi diff-to-markdown > diff.md ``` pixi-diff-to-markdown in GitHub Actions updates For other usages of [`pixi-diff-to-markdown`](https://github.com/pavelzw/pixi-diff-to-markdown), see also our page about [updating lockfiles using GitHub Actions](../../ci/updates_github_actions/). You can view this generated markdown file in your terminal using [`glow`](https://github.com/charmbracelet/glow). ```bash glow diff.md --tui ``` You can also view the markdown file directly from stdin using [`glow`](https://github.com/charmbracelet/glow). ```bash pixi diff <(git show HEAD~20:pixi.lock) pixi.lock | pixi diff-to-markdown | glow --tui ``` [pixi-inject](https://github.com/pavelzw/pixi-inject) is a simple executable that injects a conda package into an existing pixi environment. ```text pixi inject --environment default --package my-package-0.1.0-py313h8aa417a_0.conda ``` You can also specify a custom conda prefix to inject the package into. ```text pixi inject --prefix /path/to/conda/env --package my-package-0.1.0-py313h8aa417a_0.conda ``` Pixi installs your environments to `.pixi/envs/` by default. If you want to install your environment to an arbitrary location on your system, you can use [`pixi-install-to-prefix`](https://github.com/pavelzw/pixi-install-to-prefix). You can install `pixi-install-to-prefix` with: ```bash pixi global install pixi-install-to-prefix ``` Instead of installing `pixi-install-to-prefix` globally, you can also use `pixi exec` to run `pixi-install-to-prefix` in a temporary environment: ```bash pixi exec pixi-install-to-prefix ./my-environment ``` ```text Usage: pixi-install-to-prefix [OPTIONS] Arguments: The path to the prefix where you want to install the environment Options: -l, --lockfile The path to the pixi lockfile [default: pixi.lock] -e, --environment The name of the pixi environment to install [default: default] -p, --platform The platform you want to install for [default: ] -c, --config The path to the pixi config file. By default, no config file is used -s, --shell The shell(s) to generate activation scripts for. Default: see README --no-activation-scripts Disable the generation of activation scripts -v, --verbose... Increase logging verbosity -q, --quiet... Decrease logging verbosity -h, --help Print help ``` [pixi-skills](https://github.com/pavelzw/pixi-skills) manages and installs coding agent skills across multiple LLM backends. It discovers skills packaged in pixi environments and installs them into the configuration directories of various coding agents via symlinks. For a detailed explanation of the motivation and design behind pixi-skills, see the blog post [Managing Agent Skills with Your Package Manager](https://pavel.pink/blog/pixi-skills). ## Installation ```bash pixi global install pixi-skills ``` ## Concepts ### Skills A skill is a directory containing a `SKILL.md` file with YAML frontmatter: ```markdown --- name: my-skill description: "Does something useful for the agent" --- Skill instructions go here as Markdown. The agent reads this file to understand what the skill does. ``` The `name` field is optional and defaults to the directory name. The `description` field is required. ### skill-forge A collection of ready-to-use skills is available as conda packages on the [skill-forge](https://prefix.dev/channels/skill-forge) channel ([source](https://github.com/pavelzw/skill-forge)). To use skills from skill-forge, add the channel and the desired skill packages to your `pixi.toml`: ```toml [workspace] channels = ["conda-forge", "https://prefix.dev/skill-forge"] [dependencies] polars = ">=1,<2" [feature.dev.dependencies] agent-skill-polars = "*" ``` ### Scopes - **Local** skills are discovered from the current project's pixi environment at `.pixi/envs//share/agent-skills/`. - **Global** skills are discovered from globally installed pixi packages at `~/.pixi/envs/agent-skill-*/share/agent-skills/`. Skills are installed as relative symlinks for portability. ## Usage ### Manage skills interactively ```bash # Interactive mode - prompts for backend and scope pixi skills manage # Specify backend and scope directly pixi skills manage --backend claude --scope local ``` This opens an interactive checkbox selector where you can choose which skills to install or uninstall. ### List available skills ```bash # List all local and global skills pixi skills list # List only local skills pixi skills list --scope local # List skills from a specific pixi environment pixi skills list --env myenv ``` ### Show installed skills ```bash # Show installed skills across all backends pixi skills status # Show installed skills for a specific backend pixi skills status --backend claude ``` `conda-deny` in one command: In your favorite `pixi` workspace, run: ```bash pixi exec conda-deny check --osi ``` This will check your workspace for license compliance against the list of [OSI approved licenses](https://opensource.org/licenses). [conda-deny](https://github.com/Quantco/conda-deny) is a CLI tool for checking software environment dependencies for license compliance. Compliance is checked with regard to an allowlist of licenses provided by the user. ### πŸ’Ώ Installation You can install `conda-deny` using `pixi`: ```bash pixi global install conda-deny ``` Or by downloading our pre-built binaries from the [releases page](https://github.com/quantco/conda-deny/releases). ### 🎯 Usage `conda-deny` can be configured in your `pixi.toml` or `pyproject.toml` (`pixi.toml` is preferred). The tool expects a configuration in the following format: ```toml [tool.conda-deny] #-------------------------------------------------------- # General setup options: #-------------------------------------------------------- license-allowlist = "https://raw.githubusercontent.com/quantco/conda-deny/main/tests/test_remote_base_configs/conda-deny-license_allowlist.toml" # or ["license_allowlist.toml", "other_license_allowlist.toml"] platform = "linux-64" # or ["linux-64", "osx-arm64"] environment = "default" # or ["default", "py39", "py310", "prod"] lockfile = "environment/pixi.lock" # or ["environment1/pixi.lock", "environment2/pixi.lock"] # lockfile also supports glob patterns: # lockfile = "environments/**/*.lock" #-------------------------------------------------------- # License allowlist directly in configuration file: #-------------------------------------------------------- safe-licenses = ["MIT", "BSD-3-Clause"] ignore-packages = [ { package = "make", version = "0.1.0" }, ] ``` After the installation, you can run `conda-deny check` in your workspace. This checks the dependencies defined by your `pixi.lock` against your allowlist. ### πŸ”’ Authorized access to allowlist If a Bearer Token is needed to access your allowlist, you can provide it using `CONDA_DENY_BEARER_TOKEN`. An example use case would be a private repository containing your allowlist. ### Output Formats `conda-deny` supports different output formats via the `--output` (or `-o`) flag. Output formatting works for both, the `list` and the `check` command. ```bash $ conda-deny list --output csv package_name,version,license,platform,build,safe _openmp_mutex,4.5,BSD-3-Clause,linux-aarch64,2_gnu,false _openmp_mutex,4.5,BSD-3-Clause,linux-64,2_gnu,false ... ``` ```bash $ conda-deny list --output json-pretty { "unsafe": [ { "build": "conda_forge", "license": { "Invalid": "None" }, "package_name": "_libgcc_mutex", "platform": "linux-64", "version": "0.1" }, { "build": "h57d6b7b_14", "license": { "Invalid": "LGPL-2.0-or-later AND LGPL-2.0-or-later WITH exceptions AND GPL-2.0-or-later AND MPL-2.0" }, "package_name": "_sysroot_linux-aarch64_curr_repodata_hack", "platform": "noarch", "version": "4" }, ... ``` Tip By running `conda-deny bundle`, `conda-deny` will create a directory containing all your dependencies' original license files. This can come in handy when creating SBOMs or sharing compliance information with other people. `direnv` is a tool which automatically activates an environment as soon as you enter a directory with a `.envrc` file that you accepted at some point. This tutorial will demonstrate how to use `direnv` with Pixi\`. First install `direnv` by running the following command: ```bash pixi global install direnv ``` Then create a `.envrc` file in your Pixi workspace root with the following content: .envrc ```shell watch_file pixi.lock # (1)! eval "$(pixi shell-hook)" # (2)! ``` 1. This ensures that every time your `pixi.lock` changes, `direnv` invokes the shell-hook again. 1. This installs the environment if needed, and activates it. `direnv` ensures that the environment is deactivated when you leave the directory. ```shell $ cd my-project direnv: error /my-project/.envrc is blocked. Run `direnv allow` to approve its content $ direnv allow direnv: loading /my-project/.envrc βœ” Project in /my-project is ready to use! direnv: export +CONDA_DEFAULT_ENV +CONDA_PREFIX +PIXI_ENVIRONMENT_NAME +PIXI_ENVIRONMENT_PLATFORMS +PIXI_PROJECT_MANIFEST +PIXI_PROJECT_NAME +PIXI_PROJECT_ROOT +PIXI_PROJECT_VERSION +PIXI_PROMPT ~PATH $ which python /my-project/.pixi/envs/default/bin/python $ cd .. direnv: unloading $ which python python not found ``` While `direnv` comes with [hooks for the common shells](https://direnv.net/docs/hook.html), these hooks into the shell should not be relied on when using and IDE. Here you can see how to set up `direnv` for your favorite editor: - [VSCode](../../editor/vscode/#direnv-extension) - [Jetbrains](../../editor/jetbrains/#direnv) - [Zed](../../editor/zed/) [Starship](https://starship.rs) is a cross-platform and cross-shell prompt for developers, similar to oh-my-zsh, but with a focus on performance and simplicity. It also has full Pixi support. You can install it using the following command: ```bash pixi global install starship ``` For information about how to configure and set up starship, see the [official documentation](https://starship.rs/config/#pixi). In order for starship to always find the right python executable, you can adjust its configuration file. ~/.config/starship.toml ```toml [python] # customize python binary path for pixi python_binary = [ # this is the python from PATH if in a pixi shell # (assuming you don't have python on your global PATH) "python", # fall back to pixi's python if it's available ".pixi/envs/default/bin/python", ] ``` By default, starship uses 🧚🏻 as pixi's symbol. You can adjust it as follows if you want a different symbol ~/.config/starship.toml ```toml [pixi] symbol = "πŸ“¦ " ``` As starship already displays a custom message when a pixi environment is active, you can disable pixi's custom PS1: ```text pixi config set shell.change-ps1 "false" ``` # Advanced documentation All logic regarding the decision which dependencies can be installed from which channel is done by the instruction we give the solver. The actual code regarding this is in the [`rattler_solve`](https://github.com/conda/rattler/blob/02e68c9539c6009cc1370fbf46dc69ca5361d12d/crates/rattler_solve/src/resolvo/mod.rs) crate. This might however be hard to read. Therefore, this document will continue with simplified flow charts. ## Channel Specific Dependencies When a user defines a channel per dependency, the solver needs to know the other channels are unusable for this dependency. ```toml [workspace] channels = ["conda-forge", "my-channel"] [dependencies] packgex = { version = "*", channel = "my-channel" } ``` In the `packagex` example, the solver will understand that the package is only available in `my-channel` and will not look for it in `conda-forge`. The flowchart of the logic that excludes all other channels: ``` flowchart TD A[Start] --> B[Given a Dependency] B --> C{Channel Specific Dependency?} C -->|Yes| D[Exclude All Other Channels for This Package] C -->|No| E{Any Other Dependencies?} E -->|Yes| B E -->|No| F[End] D --> E ``` ## Channel Priority Channel priority is dictated by the order in the `workspace.channels` array, where the first channel is the highest priority. For instance: ```toml [workspace] channels = ["conda-forge", "my-channel", "your-channel"] ``` If the package is found in `conda-forge` the solver will not look for it in `my-channel` and `your-channel`, because it tells the solver they are excluded. If the package is not found in `conda-forge` the solver will look for it in `my-channel` and if it **is** found there it will tell the solver to exclude `your-channel` for this package. This diagram explains the logic: ``` flowchart TD A[Start] --> B[Given a Dependency] B --> C{Loop Over Channels} C --> D{Package in This Channel?} D -->|No| C D -->|Yes| E{"Is this the first channel for this package?"} E -->|Yes| F[Include Package in Candidates] E -->|No| G[Exclude Package from Candidates] F --> H{Any Other Channels?} G --> H H -->|Yes| C H -->|No| I{Any Other Dependencies?} I -->|No| J[End] I -->|Yes| B ``` This method ensures the solver only adds a package to the candidates if it's found in the highest priority channel available. If you have 10 channels and the package is found in the 5th channel it will exclude the next 5 channels from the candidates if they also contain the package. ## Use Case: pytorch and nvidia with conda-forge A common use case is to use `pytorch` with `nvidia` drivers, while also needing the `conda-forge` channel for the main dependencies. ```toml [workspace] channels = ["nvidia/label/cuda-11.8.0", "nvidia", "conda-forge", "pytorch"] platforms = ["linux-64"] [dependencies] cuda = {version = "*", channel="nvidia/label/cuda-11.8.0"} pytorch = {version = "2.0.1.*", channel="pytorch"} torchvision = {version = "0.15.2.*", channel="pytorch"} pytorch-cuda = {version = "11.8.*", channel="pytorch"} python = "3.10.*" ``` What this will do is get as much as possible from the `nvidia/label/cuda-11.8.0` channel, which is actually only the `cuda` package. Then it will get all packages from the `nvidia` channel, which is a little more and some packages overlap the `nvidia` and `conda-forge` channel. Like the `cuda-cudart` package, which will now only be retrieved from the `nvidia` channel because of the priority logic. Then it will get the packages from the `conda-forge` channel, which is the main channel for the dependencies. But the user only wants the pytorch packages from the `pytorch` channel, which is why `pytorch` is added last and the dependencies are added as channel specific dependencies. We don't define the `pytorch` channel before `conda-forge` because we want to get as much as possible from the `conda-forge` as the pytorch channel is not always shipping the best versions of all packages. For example, it also ships the `ffmpeg` package, but only an old version which doesn't work with the newer pytorch versions. Thus breaking the installation if we would skip the `conda-forge` channel for `ffmpeg` with the priority logic. ## Force a Specific Channel Priority If you want to force a specific priority for a channel, you can use the `priority` (int) key in the channel definition. The higher the number, the higher the priority. Non specified priorities are set to 0 but the index in the array still counts as a priority, where the first in the list has the highest priority. This priority definition is mostly important for [multiple environments](../../workspace/multi_environment/) with different channel priorities, as by default feature channels are prepended to the workspace channels. ```toml [workspace] name = "test_channel_priority" platforms = ["linux-64", "osx-64", "win-64", "osx-arm64"] channels = ["conda-forge"] [feature.a] channels = ["nvidia"] [feature.b] channels = [ "pytorch", {channel = "nvidia", priority = 1}] [feature.c] channels = [ "pytorch", {channel = "nvidia", priority = -1}] [environments] a = ["a"] b = ["b"] c = ["c"] ``` This example creates 4 environments, `a`, `b`, `c`, and the default environment. Which will have the following channel order: | Environment | Resulting Channels order | | ----------- | ---------------------------------- | | default | `conda-forge` | | a | `nvidia`, `conda-forge` | | b | `nvidia`, `pytorch`, `conda-forge` | | c | `pytorch`, `conda-forge`, `nvidia` | Check priority result with `pixi info` Using `pixi info` you can check the priority of the channels in the environment. ```bash pixi info Environments ------------ Environment: default Features: default Channels: conda-forge Dependency count: 0 Target platforms: linux-64 Environment: a Features: a, default Channels: nvidia, conda-forge Dependency count: 0 Target platforms: linux-64 Environment: b Features: b, default Channels: nvidia, pytorch, conda-forge Dependency count: 0 Target platforms: linux-64 Environment: c Features: c, default Channels: pytorch, conda-forge, nvidia Dependency count: 0 Target platforms: linux-64 ``` `pixi info` prints out useful information to debug a situation or to get an overview of your machine/workspace. This information can also be retrieved in `json` format using the `--json` flag, which can be useful for programmatically reading it. Running pixi info in the pixi repo ```text ➜ pixi info Pixi version: 0.13.0 Platform: linux-64 Virtual packages: __unix=0=0 : __linux=6.5.12=0 : __glibc=2.36=0 : __cuda=12.3=0 : __archspec=1=x86_64 Cache dir: /home/user/.cache/rattler/cache Auth storage: /home/user/.rattler/credentials.json Workspace ------------ Version: 0.13.0 Manifest file: /home/user/development/pixi/pixi.toml Last updated: 25-01-2024 10:29:08 Environments ------------ default Features: default Channels: conda-forge Dependency count: 10 Dependencies: pre-commit, rust, openssl, pkg-config, git, mkdocs, mkdocs-material, pillow, cairosvg, compilers Target platforms: linux-64, osx-arm64, win-64, osx-64 Tasks: docs, test-all, test, build, lint, install, build-docs ``` ## Global info The first part of the info output is information that is always available and tells you what Pixi can read on your machine. ### Platform This defines the platform you're currently on according to pixi. If this is incorrect, please file an issue on the [Pixi repo](https://github.com/prefix-dev/pixi). ### Virtual packages The virtual packages that Pixi can find on your machine. In the Conda ecosystem, you can depend on virtual packages. These packages aren't real dependencies that are going to be installed, but rather are being used in the solve step to find if a package can be installed on the machine. A simple example: When a package depends on Cuda drivers being present on the host machine it can do that by depending on the `__cuda` virtual package. In that case, if Pixi cannot find the `__cuda` virtual package on your machine the installation will fail. ### Cache dir The directory where Pixi stores its cache. Checkout the [cache documentation](../../workspace/environment/#caching-packages) for more information. ### Auth storage Check the [authentication documentation](../../deployment/authentication/) ### Cache size \[requires `--extended`\] The size of the previously mentioned "Cache dir" in Mebibytes. ## Workspace info Everything below `Workspace` is info about the workspace you're currently in. This info is only available if your path has a [manifest file](../../reference/pixi_manifest/). ### Manifest file The path to the [manifest file](../../reference/pixi_manifest/) that describes the workspace. ### Last updated The last time the lock file was updated, either manually or by Pixi itself. ## Environment info The environment info defined per environment. If you don't have any environments defined, this will only show the `default` environment. ### Features This lists which features are enabled in the environment. For the default this is only `default` ### Channels The list of channels used in this environment. ### Dependency count The amount of dependencies defined that are defined for this environment (not the amount of installed dependencies). ### Dependencies The list of dependencies defined for this environment. ### Target platforms The platforms the workspace has defined. ## Overview Sometimes our direct dependency declares outdated intermediate dependency or is too tight to solve with other direct dependencies. In this case, we can override the intermediate dependency in our `pyproject.toml`or `pixi.toml` file. Note This option is not recommended unless you know what you are doing, as uv will ignore all the version constraints of the dependency and use the version you specified. ## Example ### Override a dependency version ```toml # pyproject.toml [tool.pixi.pypi-options.dependency-overrides] numpy = ">=2.0.0" ``` or in `pixi.toml`: ```toml # pixi.toml [pypi-options.dependency-overrides] numpy = ">=2.0.0" ``` This will override the version of `numpy` used by all dependencies to be at least `2.0.0`, regardless of what the dependencies specify. This is useful if you need a specific version of a library that is not compatible with the versions specified by your dependencies. ### Override a dependency version in a specific feature it can also be specified in feature level, ```toml [features.dev.pypi-options.dependency-overrides] numpy = ">=2.0.0" ``` This will override the version of `numpy` used by all dependencies in the `dev` feature to be at least `2.0.0`, regardless of what the dependencies specify when the `dev` feature is enabled. ### Interact with other overrides For a specific environment, all the `dependency-overrides` defined in different features will be combined in the order they were defined. If the same dependency is overridden multiple times, we'll use the override from the **prior** feature in that environment. Also, the default feature will always come, and come last in the list of all overrides. ```toml # pixi.toml [pypi-options] dependency-overrides = { numpy = ">=2.1.0" } [pypi-dependencies] numpy = ">=1.25.0" [feature.dev.pypi-options.dependency-overrides] numpy = "==2.0.0" [feature.outdated.pypi-options.dependency-overrides] numpy = "==1.21.0" [environments] dev = ["dev"] outdated = ["outdated"] conflict_a=["outdated", "dev"] conflict_b=["dev","outdated"] ``` the following constrains are merged out: default: `numpy >= 2.1.0` dev: `numpy == 2.0.0` outdated: `numpy == 1.21.0` conflict_a: `numpy == 1.21.0` (from `outdated`) conflict_b: `numpy == 2.0.0` (from `dev`) This may contrast with the intuition that all overrides are applied and combined to a result. It is done this way to avoid conflicts and confusion: Since users are granted fully control over the overrides, it is up to them to choose the right overrides for an environment. The `pixi shell` command is similar to `conda activate` but works a little different under the hood. Instead of requiring a change to your `~/.bashrc` or other files, it will launch a fresh shell. That also means that, instead of `conda deactivate`, it's enough to just exit the current shell, e.g. by pressing `Ctrl+D`. ```shell pixi shell ``` On Unix systems the shell command works by creating a "fake" PTY session that will start the shell, and then send a string like `source /tmp/activation-env-12345.sh` to the `stdin` in order to activate the environment. If you would peek under the hood of the the `shell` command, then you would see that this is the first thing executed in the new shell session. The temporary script that we generate ends with `echo "PIXI_ENV_ACTIVATED"` which is used to detect if the environment was activated successfully. If we do not receive this string after three seconds, we will issue a warning to the user. ## Shell Completions Shell completions for tools in your project are loaded automatically inside `pixi shell`. This means that if a package in your environment ships completions (e.g. for `git` or `cargo`), they will be available without any extra configuration. ## Issues With Pixi Shell As explained, `pixi shell` only works well if we execute the activation script *after* launching shell. Certain commands that are run in the `~/.bashrc` might swallow the activation command, and the environment won't be activated. For example, if your `~/.bashrc` contains code like the following, `pixi shell` has little chance to succeed: ```shell # on WSL - the `wsl.exe` somehow takes over `stdin` and prevents `pixi shell` from succeeding wsl.exe -d wsl-vpnkit --cd /app service wsl-vpnkit start # on macOS or Linux, some users start fish or nushell from their `bashrc` # If you wish to start an alternative shell from bash, it's better to do so # from `~/.bash_profile` or `~/.profile` if [[ $- = *i* ]]; then exec ~/.pixi/bin/fish fi ``` In order to fix this, we would advise you to follow the steps below to use `pixi shell-hook` instead. ## Traditional `conda activate`-like activation If you prefer to use the traditional `conda activate`-like activation, you can use the `pixi shell-hook` command. ```shell $ which python python not found $ eval "$(pixi shell-hook)" $ (default) which python /path/to/project/.pixi/envs/default/bin/python ``` For example, with `bash` and `zsh` you can use the following command: ```shell eval "$(pixi shell-hook)" ``` Custom activation function With the `--manifest-path` option you can also specify which environment to activate. If you want to add a `bash` function to your `~/.bashrc` that will activate the environment, you can use the following command: ```shell function pixi_activate() { # default to current directory if no path is given local manifest_path="${1:-.}" eval "$(pixi shell-hook --manifest-path $manifest_path)" } ``` After adding this function to your `~/.bashrc`/`~/.zshrc`, you can activate the environment by running: With fish, you can also evaluate the output of `pixi shell-hook`: ```fish pixi shell-hook | source ``` Or, if you want to add a function to your `~/.config/fish/config.fish`: ```fish function pixi_activate # default to current directory if no path is given set -l manifest_path $argv[1] test -z "$manifest_path"; and set manifest_path "." pixi shell-hook --manifest-path "$manifest_path" | source end ``` After adding this function to your `~/.config/fish/config.fish`, you can activate the environment by running: ```shell pixi_activate # or with a specific manifest pixi_activate ~/projects/my_project ``` Using direnv See our [direnv page](../../integration/third_party/direnv/) on how to leverage `pixi shell-hook` to integrate with direnv. Only on Unix-like systems The following approach only works on Unix-like systems (i.e. Linux and macOS) since Windows does not support shebang lines. For simple scripts, you can use [`pixi exec`](../../reference/cli/pixi/exec/) to run them directly without needing to take care of installing dependencies or setting up an environment. This can be done by adding a [shebang line]() at the top of the script, which tells the system how to execute the script. Usually, a shebang line starts with `#!/usr/bin/env` followed by the name of the interpreter to use. Instead of adding an interpreter, you can also just add `pixi exec` at the beginning of the script. The only requirement for your script is that you must have `pixi` installed on your system. Making the script executable You might need to make the script executable by running `chmod +x my-script.sh`. use-bat.sh ```bash #!/usr/bin/env -S pixi exec --spec bat -- bash -e bat my-file.json ``` Explanation what's happening The `#!` are magic characters that tell your system how to execute the script (take everything after the `#!` and append the file name). The `/usr/bin/env` is used to find `pixi` in the system's `PATH`. The `-S` option tells `/usr/bin/env` to use the first argument as the interpreter and the rest as arguments to the interpreter. `pixi exec --spec bat` creates a temporary environment containing only [`bat`](https://github.com/sharkdp/bat). `bash -e` (separated with `--`) is the command that is executed in this environment. So in total, `pixi exec --spec bat -- bash -e use-bat.sh` is being executed when you run `./use-bat.sh`. You can also write self-contained python files that ship with their dependencies. This example shows a very simple CLI that installs a Pixi environment to an arbitrary prefix using [`py-rattler`](https://conda.github.io/rattler/py-rattler) and [`typer`](https://typer.tiangolo.com). install-pixi-environment-to-prefix.py ```python #!/usr/bin/env -S pixi exec --spec py-rattler>=0.10.0,<0.11 --spec typer>=0.15.0,<0.16 -- python import asyncio from pathlib import Path from typing import get_args from rattler import install as rattler_install from rattler import LockFile, Platform from rattler.platform.platform import PlatformLiteral from rattler.networking import Client, MirrorMiddleware, AuthenticationMiddleware import typer app = typer.Typer() async def _install( lock_file_path: Path, environment_name: str, platform: Platform, target_prefix: Path, ) -> None: lock_file = LockFile.from_path(lock_file_path) environment = lock_file.environment(environment_name) if environment is None: raise ValueError(f"Environment {environment_name} not found in lock file {lock_file_path}") records = environment.conda_repodata_records_for_platform(platform) if not records: raise ValueError(f"No records found for platform {platform} in lock file {lock_file_path}") await rattler_install( records=records, target_prefix=target_prefix, client=Client( middlewares=[ MirrorMiddleware({"https://conda.anaconda.org/conda-forge": ["https://repo.prefix.dev/conda-forge"]}), AuthenticationMiddleware(), ] ), ) @app.command() def install( lock_file_path: Path = Path("pixi.lock").absolute(), environment_name: str = "default", platform: str = str(Platform.current()), target_prefix: Path = Path("env").absolute(), ) -> None: """ Installs a pixi.lock file to a custom prefix. """ if platform not in get_args(PlatformLiteral): raise ValueError(f"Invalid platform {platform}. Must be one of {get_args(PlatformLiteral)}") asyncio.run( _install( lock_file_path=lock_file_path, environment_name=environment_name, platform=Platform(platform), target_prefix=target_prefix, ) ) if __name__ == "__main__": app() ``` # Reference documentation ## Configurable Environment Variables Pixi can also be configured via environment variables. | Name | Description | Default | | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `PIXI_HOME` | Defines the directory where pixi puts its global data. | [HOME](https://docs.rs/dirs/latest/dirs/fn.home_dir.html)/.pixi | | `PIXI_CACHE_DIR` | Defines the directory where pixi puts its cache. | - If `PIXI_CACHE_DIR` is not set, the `RATTLER_CACHE_DIR` environment variable is used. - If that is not set, `XDG_CACHE_HOME/pixi` is used when the directory exists. - If that is not set, the default cache directory of [rattler::default_cache_dir](https://docs.rs/rattler/latest/rattler/fn.default_cache_dir.html) is used. | | `RATTLER_AUTH_FILE` | Overrides the default location of the credentials file. When set, this is the only source of authentication data used by pixi. See [authentication docs](../../deployment/authentication/#override-the-authentication-storage) for the file format. | - If `RATTLER_AUTH_FILE` is not set, the system keyring is used. - If no keyring is available, file storage from `~/.rattler/credentials.json` is used. - Additionally, `.netrc` file authentication is checked. | ## Environment Variables Set By Pixi The following environment variables are set by Pixi, when using the `pixi run`, `pixi shell`, or `pixi shell-hook` command: - `PIXI_PROJECT_ROOT`: The root directory of the project. - `PIXI_PROJECT_NAME`: The name of the project. - `PIXI_PROJECT_MANIFEST`: The path to the manifest file (`pixi.toml`). - `PIXI_PROJECT_VERSION`: The version of the project. - `PIXI_PROMPT`: The prompt to use in the shell, also used by `pixi shell` itself. - `PIXI_ENVIRONMENT_NAME`: The name of the environment, defaults to `default`. - `PIXI_ENVIRONMENT_PLATFORMS`: Comma separated list of platforms supported by the project. - `CONDA_PREFIX`: The path to the environment. (Used by multiple tools that already understand conda environments) - `CONDA_DEFAULT_ENV`: The name of the environment. (Used by multiple tools that already understand conda environments) - `PATH`: We prepend the `bin` directory of the environment to the `PATH` variable, so you can use the tools installed in the environment directly. - `INIT_CWD`: ONLY IN `pixi run`: The directory where the command was run from. Note Even though the variables are environment variables these cannot be overridden. E.g. you can not change the root of the project by setting `PIXI_PROJECT_ROOT` in the environment. ## Environment Variable Priority The following priority rule applies for environment variables: `task.env` > `activation.env` > `activation.scripts` > activation scripts of dependencies > outside environment variables. Variables defined at a higher priority will override those defined at a lower priority. Warning In older versions of Pixi, this priority was not well-defined, and there are a number of known deviations from the current priority which exist in some older versions. Please see the warning in [the advanced tasks documentation](../../workspace/advanced_tasks/#environment-variables) for further details and migration guidance. ##### Example 1: `task.env` > `activation.env` In `pixi.toml`, we defined an environment variable `HELLO_WORLD` in both `tasks.hello` and `activation.env`. When we run `echo $HELLO_WORLD`, it will output: ```text Hello world! ``` pixi.toml ```toml [tasks.hello] cmd = "echo $HELLO_WORLD" env = { HELLO_WORLD = "Hello world!" } [activation.env] HELLO_WORLD = "Activate!" ``` ##### Example 2: `activation.env` > `activation.scripts` In `pixi.toml`, we defined the same environment variable `DEBUG_MODE` in both `activation.env` and in the activation script file `setup.sh`. When we run `echo Debug mode: $DEBUG_MODE`, it will output: ```bash Debug mode: enabled ``` pixi.toml ```toml [activation.env] DEBUG_MODE = "enabled" [activation] scripts = ["setup.sh"] ``` setup.sh ```bash export DEBUG_MODE="disabled" ``` ##### Example 3: `activation.scripts` > activation scripts of dependencies In `pixi.toml`, we have our local activation script and a dependency `my-package` that also sets environment variables through its activation scripts. When we run `echo Library path: $LIB_PATH`, it will output: ```text Library path: /my/lib ``` pixi.toml ```toml [activation] scripts = ["local_setup.sh"] [dependencies] my-package = "*" # This package has its own activation scripts that set LIB_PATH="/dep/lib" ``` local_setup.sh ```bash export LIB_PATH="/my/lib" ``` ##### Example 4: activation scripts of dependencies > outside environment variable If we have a dependency that sets `PYTHON_PATH` and the same variable is already set in the outside environment. When we run `echo Python path: $PYTHON_PATH`, it will output: ```bash Python path: /pixi/python ``` ```text # Outside environment export PYTHON_PATH="/system/python" ``` pixi.toml ```toml [dependencies] python-utils = "*" # This package sets PYTHON_PATH="/pixi/python" in its activation scripts ``` ##### Example 5: Complex Example - All priorities combined In `pixi.toml`, we define the same variable `APP_CONFIG` across multiple levels: pixi.toml ```toml [tasks.start] cmd = "echo Config: $APP_CONFIG" env = { APP_CONFIG = "task-specific" } [activation.env] APP_CONFIG = "activation-env" [activation] scripts = ["app_setup.sh"] [dependencies] config-loader = "*" # Sets APP_CONFIG="dependency-config" ``` app_setup.sh ```bash export APP_CONFIG="activation-script" ``` ```bash # Outside environment export APP_CONFIG="system-config" ``` Since `task.env` has the highest priority, when we run `pixi run start` it will output: ```text Config: task-specific ``` # The Configuration of Pixi Itself Apart from the [workspace specific configuration](../pixi_manifest/) Pixi supports configuration options which are not required for the workspace to work but are local to the machine. The configuration is loaded in the following order: | **Priority** | **Location** | **Comments** | | ------------ | ---------------------------------------------------------------------- | ------------------------------------------------ | | 7 | Command line arguments (`--tls-no-verify`, `--change-ps1=false`, etc.) | Configuration via command line arguments | | 6 | `your_project/.pixi/config.toml` | Project-specific configuration | | 5 | `$PIXI_HOME/config.toml` | Global configuration in `PIXI_HOME`. | | 4 | `$HOME/.pixi/config.toml` | Global configuration in the user home directory. | | 3 | `$XDG_CONFIG_HOME/pixi/config.toml` | XDG compliant user-specific configuration | | 2 | `$HOME/.config/pixi/config.toml` | User-specific configuration | | 1 | `/etc/pixi/config.toml` | System-wide configuration | | **Priority** | **Location** | **Comments** | | ------------ | ---------------------------------------------------------------------- | ------------------------------------------------ | | 7 | Command line arguments (`--tls-no-verify`, `--change-ps1=false`, etc.) | Configuration via command line arguments | | 6 | `your_project/.pixi/config.toml` | Project-specific configuration | | 5 | `$PIXI_HOME/config.toml` | Global configuration in `PIXI_HOME`. | | 4 | `$HOME/.pixi/config.toml` | Global configuration in the user home directory. | | 3 | `$HOME/Library/Application Support/pixi/config.toml` | User-specific configuration | | 2 | `$XDG_CONFIG_HOME/pixi/config.toml` | XDG compliant user-specific configuration | | 1 | `/etc/pixi/config.toml` | System-wide configuration | | **Priority** | **Location** | **Comments** | | ------------ | ---------------------------------------------------------------------- | ------------------------------------------------ | | 6 | Command line arguments (`--tls-no-verify`, `--change-ps1=false`, etc.) | Configuration via command line arguments | | 5 | `your_project\.pixi\config.toml` | Project-specific configuration | | 4 | `%PIXI_HOME%\config.toml` | Global configuration in `PIXI_HOME`. | | 3 | `%USERPROFILE%\.pixi\config.toml` | Global configuration in the user home directory. | | 2 | `%APPDATA%\pixi\config.toml` | User-specific configuration | | 1 | `C:\ProgramData\pixi\config.toml` | System-wide configuration | Note The highest priority wins. If a configuration file is found in a higher priority location, the values from the configuration read from lower priority locations are overwritten. Note To find the locations where `pixi` looks for configuration files, run `pixi info -vvv`. ## Configuration options Naming convention in configuration In Pixi `0.20.1` and older the global configuration options used `snake_case` which we've changed to `kebab-case` for consistency with the rest of the configuration. For backwards compatibility, the following configuration options can still be written in `snake_case`: ```text - `default_channels` - `change_ps1` - `tls_no_verify` - `authentication_override_file` - `mirrors` and its sub-options - `repodata_config` and its sub-options ``` The following reference describes all available configuration options. ### `default-channels` The default channels to select when running `pixi init` or `pixi global install`. This defaults to only conda-forge. config.toml ```toml default-channels = ["conda-forge"] ``` Note The `default-channels` are only used when initializing a new workspace. Once initialized the `channels` are used from the workspace manifest. ### `shell` - `change-ps1`: When set to `false`, the `(pixi)` prefix in the shell prompt is removed. This applies to the `pixi shell` subcommand. You can override this from the CLI with `--change-ps1`. - `force-activate`: When set to `true` the re-activation of the environment will always happen. This is used in combination with the [`experimental`](#experimental) feature `use-environment-activation-cache`. - `source-completion-scripts`: When set to `false`, Pixi will not source the autocompletion scripts of the environment when going into the shell. config.toml ```toml [shell] change-ps1 = false force-activate = true source-completion-scripts = false ``` ### `tls-no-verify` When set to true, TLS certificate verification is disabled for all network connections, including both conda channels and PyPI registries. You can override this from the CLI with `--tls-no-verify`. Warning This is a security risk and should only be used for testing purposes or internal networks. This is a global setting that affects all connections. If you only need to bypass TLS verification for specific PyPI hosts, consider using [`pypi-config.allow-insecure-host`](#pypi-config) instead for more granular control. Implementation detail and limitations For PyPI operations, since uv does not support a global TLS verification disable flag, pixi automatically adds all configured PyPI index hosts to the trusted hosts list when `tls-no-verify` is enabled. For the main PyPI index, `files.pythonhosted.org` (the download host) is also automatically added. **Important limitation:** If your custom PyPI index redirects package downloads to a different host (e.g., a separate CDN or artifact server), that download host will not be automatically trusted, even with `tls-no-verify` set. In these cases, you *must* manually add the download host to [`pypi-config.allow-insecure-host`](#pypi-config). config.toml ```toml tls-no-verify = false ``` ### `tls-root-certs` Controls which TLS root certificates are used for HTTPS connections. This affects both conda channels and PyPI registries. Available options: - `webpki` (default): Uses bundled Mozilla root certificates. This is the most portable option. - `native`: Uses the system certificate store. Required for corporate environments with custom CA certificates. - `all`: Uses both bundled Mozilla certificates and the system certificate store. You can override this from the CLI with `--tls-root-certs`. Build-dependent behavior This setting only has an effect with `rustls-tls` builds (standalone pixi binaries from GitHub releases). For `native-tls` builds (conda-forge packages), the system's TLS library is used, which always uses system certificates. In this case, the setting is accepted but has no effect. config.toml ```toml # Which TLS root certificates to use for HTTPS connections. # Options: "webpki" (bundled Mozilla roots), "native" (system store), "all" (both) # Default is "webpki" for portability. Use "native" or "all" for corporate environments # with custom CA certificates. # Note: This setting only has an effect with rustls-tls builds (standalone pixi). # For native-tls builds (conda-forge), system certificates are always used. tls-root-certs = "native" ``` ### `authentication-override-file` Override from where the authentication information is loaded. Usually, we try to use the keyring to load authentication data from, and only use a JSON file as a fallback. This option allows you to force the use of a JSON file. Read more in the authentication section. config.toml ```toml authentication-override-file = "/path/to/your/override.json" ``` ### `detached-environments` The directory where Pixi stores the workspace environments, what would normally be placed in the `.pixi/envs` folder in a workspace's root. It doesn't affect the environments built for `pixi global`. The location of environments created for a `pixi global` installation can be controlled using the `PIXI_HOME` environment variable. Warning We recommend against using this because any environment created for a workspace is no longer placed in the same folder as the workspace. This creates a disconnect between the workspace and its environments and manual cleanup of the environments is required when deleting the workspace. However, in some cases, this option can still be very useful, for instance to: - force the installation on a specific filesystem/drive. - install environments locally but keep the workspace on a network drive. - let a system-administrator have more control over all environments on a system. This field can consist of two types of input. - A boolean value, `true` or `false`, which will enable or disable the feature respectively. (not `"true"` or `"false"`, this is read as `false`) - A string value, which will be the absolute path to the directory where the environments will be stored. config.toml ```toml detached-environments = true ``` or: config.toml ```toml detached-environments = "/opt/pixi/envs" ``` The environments will be stored in the [cache directory](../../workspace/environment/#caching-packages) when this option is `true`. When you specify a custom path the environments will be stored in that directory. The resulting directory structure will look like this: ```shell /opt/pixi/envs β”œβ”€β”€ pixi-6837172896226367631 β”‚ └── envs └── NAME_OF_PROJECT-HASH_OF_ORIGINAL_PATH β”œβ”€β”€ envs # the runnable environments └── solve-group-envs # If there are solve groups ``` ### `pinning-strategy` The strategy to use for pinning dependencies when running `pixi add`. The default is `semver` but you can set the following: - `no-pin`: No pinning, resulting in an unconstraint dependency. `*` - `semver`: Pinning to the latest version that satisfies the semver constraint. Resulting in a pin to major for most versions and to minor for `v0` versions. - `exact-version`: Pinning to the exact version, `1.2.3` -> `==1.2.3`. - `major`: Pinning to the major version, `1.2.3` -> `>=1.2.3, <2`. - `minor`: Pinning to the minor version, `1.2.3` -> `>=1.2.3, <1.3`. - `latest-up`: Pinning to the latest version, `1.2.3` -> `>=1.2.3`. config.toml ```toml pinning-strategy = "no-pin" ``` ### `mirrors` Configuration for conda channel-mirrors, more info [below](#mirror-configuration). config.toml ```toml [mirrors] # redirect all requests for conda-forge to the prefix.dev mirror "https://conda.anaconda.org/conda-forge" = ["https://prefix.dev/conda-forge"] # redirect all requests for bioconda to one of the three listed mirrors # Note: for repodata we try the first mirror first. "https://conda.anaconda.org/bioconda" = [ "https://conda.anaconda.org/bioconda", # OCI registries are also supported "oci://ghcr.io/channel-mirrors/bioconda", # S3-compatible storage is also supported "s3://my-s3-bucket/bioconda", "https://prefix.dev/bioconda", ] ``` ### `proxy-config` `pixi` respects the proxy environments such as `https_proxy` with the highest priority. Also we can set the proxies in `proxy-config` table of the `pixi` config, which affect all the pixi network actions, such as resolve, self-update, download, etc. Now `proxy-config` table supports the following options: - `https` and `http`: The proxy url for https:// or http:// url, works like `https_proxy` and `http_proxy` environments. - `non-proxy-hosts`: A list of domains which should bypass proxies. config.toml ```toml [proxy-config] http = "http://proxy.example.com:8080/" https = "http://proxy.example.com:8080/" non-proxy-hosts = [".cn", "localhost", "[::1]"] ``` ### `repodata-config` Configuration for repodata fetching. config.toml ```toml [repodata-config] # disable fetching of jlap, bz2 or zstd repodata files. # This should only be used for specific old versions of artifactory and other non-compliant # servers. disable-bzip2 = true # don't try to download repodata.json.bz2 disable-jlap = true # don't try to download repodata.jlap [default: true] disable-sharded = true # don't try to download sharded repodata disable-zstd = true # don't try to download repodata.json.zst ``` The above settings can be overridden on a per-channel basis by specifying a channel prefix in the configuration. config.toml ```toml [repodata-config."https://prefix.dev"] disable-sharded = false ``` ### `pypi-config` To setup a certain number of defaults for the usage of PyPI registries. You can use the following configuration options: - `index-url`: The default index URL to use for PyPI packages. This will be added to a manifest file on a `pixi init`. - `extra-index-urls`: A list of additional URLs to use for PyPI packages. This will be added to a manifest file on a `pixi init`. - `keyring-provider`: Allows the use of the [keyring](https://pypi.org/project/keyring/) python package to store and retrieve credentials. - `allow-insecure-host`: A list of host names (without protocol or port) for which TLS certificate verification should be disabled when accessing PyPI registries. This is useful when working with internal PyPI mirrors that use self-signed certificates. For disabling TLS verification globally for all connections, use [`tls-no-verify`](#tls-no-verify) instead. config.toml ```toml [pypi-config] # Main index url index-url = "https://pypi.org/simple" # list of additional urls extra-index-urls = ["https://pypi.org/simple2"] # can be "subprocess" or "disabled" keyring-provider = "subprocess" # allow insecure connections to host allow-insecure-host = ["localhost:8080"] ``` `index-url` and `extra-index-urls` are *not* globals Unlike pip, these settings, with the exception of `keyring-provider` will only modify the `pixi.toml`/`pyproject.toml` file and are not globally interpreted when not present in the manifest. This is because we want to keep the manifest file as complete and reproducible as possible. ### `s3-options` Configuration for S3 authentication. This will lead to Pixi not using AWS's default credentials but instead use the credentials from the Pixi authentication storage, see the [S3 section](../../deployment/s3/) for more information. config.toml ```toml [s3-options.my-bucket] endpoint-url = "https://my-s3-compatible-host.com" force-path-style = true region = "us-east-1" ``` ### `concurrency` Configure multiple settings to limit or extend the concurrency of pixi. config.toml ```toml [concurrency] # The maximum number of concurrent downloads # Defaults to 50 as that was found to be a good balance between speed and stability downloads = 5 # The maximum number of concurrent dependency resolves # Defaults to a heuristic based on the number of cores on the system solves = 2 ``` Set them through the CLI with: ```shell pixi config set concurrency.solves 1 pixi config set concurrency.downloads 12 ``` ### `run-post-link-scripts` Configure whether pixi should execute `post-link` and `pre-unlink` scripts or not. Some packages contain post-link scripts (`bat` or `sh` files) that are executed after a package is installed. We deem these scripts as insecure because they can contain arbitrary code that is executed on the user's machine without the user's consent. By default, the value of `run-post-link-scripts` is set to `false` which prevents the execution of these scripts. However, you can opt-in on a global (or workspace) basis by setting the value to `insecure` (e.g. by running `pixi config set --local run-post-link-scripts insecure`). In the future we are planning to add a `sandbox` mode to execute these scripts in a controlled environment. config.toml ```toml run-post-link-scripts = "false" # set to "insecure" to allow running post-link scripts ``` ### `tool-platform` Defines the platform used when installing "tools" like build backends. By default pixi uses the platform of the current system, but you can override it to use a different platform. This can be useful if you are running pixi on an architecture for which there is fewer support for certain build backends. config.toml ```toml tool-platform = "win-64" # force tools like build backends to be installed for a specific platform ``` Virtual packages The virtual packages for the tool platform are detected from the current system. If the tool platform is for a different operating system than the current system, no virtual packages will be used. ## Experimental This allows the user to set specific experimental features that are not yet stable. Please write a GitHub issue and add the flag `experimental` to the issue if you find issues with the feature you activated. ### Caching environment activations Turn this feature on from configuration with the following command: ```shell # For all of your workspaces pixi config set experimental.use-environment-activation-cache true --global # For a specific workspace pixi config set experimental.use-environment-activation-cache true --local ``` This will cache the environment activation in the `.pixi/activation-env-v0` folder in the workspace root. It will create a json file for each environment that is activated, and it will be used to activate the environment in the future. ```bash > tree .pixi/activation-env-v0/ .pixi/activation-env-v0/ β”œβ”€β”€ activation_default.json └── activation_lint.json > cat .pixi/activation-env-v0/activation_lint.json {"hash":"8d8344e0751d377a","environment_variables":{}} ``` - The `hash` is a hash of the data on that environment in the `pixi.lock`, plus some important information on the environment activation. Like `[activation.scripts]` and `[activation.env]` from the manifest file. - The `environment_variables` are the environment variables that are set when activating the environment. You can ignore the cache by running: ```text pixi run/shell/shell-hook --force-activate ``` Set the configuration with: config.toml ```toml [experimental] # Enable the use of the environment activation cache use-environment-activation-cache = true ``` Why is this experimental? This feature is experimental because the cache invalidation is very tricky, and we don't want to disturb users that are not affected by activation times. ## Mirror configuration You can configure mirrors for conda channels. We expect that mirrors are exact copies of the original channel. The implementation will look for the mirror key (a URL) in the `mirrors` section of the configuration file and replace the original URL with the mirror URL. To also include the original URL, you have to repeat it in the list of mirrors. The mirrors are prioritized based on the order of the list. We attempt to fetch the repodata (the most important file) from the first mirror in the list. The repodata contains all the SHA256 hashes of the individual packages, so it is important to get this file from a trusted source. You can also specify mirrors for an entire "host", e.g. config.toml ```toml [mirrors] "https://conda.anaconda.org" = ["https://prefix.dev/"] # prefix.dev doesn't mirror conda-forge's label channels # pixi uses the longest matching prefix for the mirror "https://conda.anaconda.org/conda-forge/label" = [ "https://conda.anaconda.org/conda-forge/label", ] ``` This will forward all request to channels on anaconda.org to prefix.dev. Channels that are not currently mirrored on prefix.dev will fail in the above example. You can override the behavior for specific channels (like conda-forge's label channels) by providing a longer prefix that points to itself. ### OCI Mirrors You can also specify mirrors on the OCI registry. There is a public mirror on the Github container registry (ghcr.io) that is maintained by the conda-forge team. You can use it like this: config.toml ```toml [mirrors] "https://conda.anaconda.org/conda-forge" = [ "oci://ghcr.io/channel-mirrors/conda-forge", ] ``` The GHCR mirror also contains `bioconda` packages. You can search the [available packages on Github](https://github.com/orgs/channel-mirrors/packages). ### Mirrors for PyPi resolving and PyPi package downloading The mirrors also affect the PyPi resolving and downloading steps of `uv`. You can set mirrors for the main pypi index and extra indices. But the base part of downloading urls may vary from their index urls. For example, the default pypi index is `https://pypi.org/simple`, and the package downloading urls are in the form of `https://files.pythonhosted.org/packages/

/

//.whl`. You need two mirror config entries for `https://pypi.org/simple` and `https://files.pythonhosted.org/packages`. The `pixi.toml` is the workspace manifest, also known as the Pixi workspace configuration file. It specifies environments for a workspace, and the package dependency requirements for those environments. It can also specify tasks which can run in those environments, as well as many other configuration options. A `toml` file is structured in different tables. This document will explain the usage of the different tables. Tip We also support the `pyproject.toml` file. It has the same structure as the `pixi.toml` file. except that you need to prepend the tables with `tool.pixi` instead of just the table name. For example, the `[workspace]` table becomes `[tool.pixi.workspace]`. There are also some small extras that are available in the `pyproject.toml` file, checkout the [pyproject.toml](../../python/pyproject_toml/) documentation for more information. ## Manifest discovery The manifest can be found at the following locations. | **Priority** | **Location** | **Comments** | | ------------ | ------------------------------- | ------------------------------------------------------------------------------ | | 6 | `--manifest-path` | Command-line argument | | 5 | `pixi.toml` | In your current working directory. | | 4 | `pyproject.toml` | In your current working directory. | | 3 | `pixi.toml` or `pyproject.toml` | Iterate through all parent directories. The first discovered manifest is used. | | 1 | `$PIXI_PROJECT_MANIFEST` | If `$PIXI_IN_SHELL` is set. This happens with `pixi shell` or `pixi run`. | Note If multiple locations exist, the manifest with the highest priority will be used. ## The `workspace` table The minimally required information in the `workspace` table is: ```toml [workspace] channels = ["conda-forge"] name = "project-name" platforms = ["linux-64"] ``` ### `channels` This is a list that defines the channels used to fetch the packages from. If you want to use channels hosted on `anaconda.org` you only need to use the name of the channel directly. ```toml channels = ["conda-forge", "robostack", "bioconda", "nvidia", "pytorch"] ``` Channels situated on the file system are also supported with **absolute** file paths: ```toml channels = ["conda-forge", "file:///home/user/staged-recipes/build_artifacts"] ``` To access private or public channels on [prefix.dev](https://prefix.dev/channels) or [Quetz](https://github.com/mamba-org/quetz) use the url including the hostname: ```toml channels = ["conda-forge", "https://repo.prefix.dev/channel-name"] ``` ### `platforms` Defines the list of platforms that the workspace supports. Pixi solves the dependencies for all these platforms and puts them in the lock file (`pixi.lock`). ```toml platforms = ["win-64", "linux-64", "osx-64", "osx-arm64"] ``` The available platforms (except `noarch` and `unknown`) are listed [here](https://docs.rs/rattler_conda_types/latest/rattler_conda_types/platform/enum.Platform.html) Special macOS and Windows ARM behavior To support both architectures on macOS or Windows, include both platforms in your list. ```toml # Specific environment for all platforms platforms = ["osx-64", "osx-arm64", "win-64", "win-arm64"] # Environments that run on both Intel and ARM setups but using the emulators: platforms = ["osx-64", "win-64"] ``` | OS | Platform | Architecture | Notes | | ------- | ----------- | ------------- | -------------------------------------------------------------------------------------------------------------------------------------- | | macOS | `osx-64` | Intel | Runs on Apple Silicon via [Rosetta](https://developer.apple.com/documentation/apple-silicon/about-the-rosetta-translation-environment) | | macOS | `osx-arm64` | Apple Silicon | Optimized binaries for Apple Silicon (recommended). | | Windows | `win-64` | Intel/AMD64 | Runs on ARM processors with [Prism](https://learn.microsoft.com/en-us/windows/arm/apps-on-arm-x86-emulation) | | Windows | `win-arm64` | ARM64 | Optimized binaries for ARM, not all packages support this yet. | ### `name` (optional) The name of the workspace. If the name is not specified, the name of the directory that contains the workspace is used. ```toml name = "project-name" ``` ### `version` (optional) The version of the workspace. This should be a valid version based on the conda Version Spec. See the [version documentation](https://docs.rs/rattler_conda_types/latest/rattler_conda_types/struct.Version.html), for an explanation of what is allowed in a Version Spec. ```toml version = "1.2.3" ``` ### `authors` (optional) This is a list of authors of the workspace. ```toml authors = ["John Doe ", "Marie Curie "] ``` ### `description` (optional) This should contain a short description of the workspace. ```toml description = "A simple description" ``` ### `license` (optional) The license as a valid [SPDX](https://spdx.org/licenses/) string (e.g. MIT AND Apache-2.0) ```toml license = "MIT" ``` ### `license-file` (optional) Relative path to the license file. ```toml license-file = "LICENSE.md" ``` ### `readme` (optional) Relative path to the README file. ```toml readme = "README.md" ``` ### `homepage` (optional) URL of the workspace homepage. ```toml homepage = "https://pixi.sh" ``` ### `repository` (optional) URL of the workspace source repository. ```toml repository = "https://github.com/prefix-dev/pixi" ``` ### `documentation` (optional) URL of the workspace documentation. ```toml documentation = "https://pixi.sh" ``` ### `conda-pypi-map` (optional) Mapping of channel name or URL to location of mapping that can be URL/Path. Mapping should be structured in `json` format where `conda_name`: `pypi_package_name`. Example: local/robostack_mapping.json ```json { "jupyter-ros": "my-name-from-mapping", "boltons": "boltons-pypi" } ``` If `conda-forge` is not present in `conda-pypi-map` `pixi` will use `prefix.dev` mapping for it. ```toml conda-pypi-map = { conda-forge = "https://example.com/mapping", "https://repo.prefix.dev/robostack" = "local/robostack_mapping.json"} ``` It is also possible to disable fetching external mpping by adding an empty map to the list ```toml conda-pypi-map = { conda-forge = "map.json" } ``` map.json ```json {} ``` ### `channel-priority` (optional) This is the setting for the priority of the channels in the solver step. Options: - `strict`: **Default**, The channels are used in the order they are defined in the `channels` list. Only packages from the first channel that has the package are used. This ensures that different variants for a single package are not mixed from different channels. Using packages from different incompatible channels like `conda-forge` and `main` can lead to hard to debug ABI incompatibilities. We strongly recommend not to switch the default. - `disabled`: There is no priority, all package variants from all channels will be set per package name and solved as one. Care should be taken when using this option. Since package variants can come from *any* channel when you use this mode, packages might not be compatible. This can cause hard to debug ABI incompatibilities. We strongly discourage using this option. ```toml channel-priority = "disabled" ``` `channel-priority = "disabled"` is a security risk Disabling channel priority may lead to unpredictable dependency resolutions. This is a possible security risk as it may lead to packages being installed from unexpected channels. It's advisable to maintain the default strict setting and order channels thoughtfully. If necessary, specify a channel directly for a dependency. ```toml [workspace] # Putting conda-forge first solves most issues channels = ["conda-forge", "channel-name"] [dependencies] package = {version = "*", channel = "channel-name"} ``` ### `solve-strategy` (optional) This is the setting for the strategy used in the solver step. Options: - `highest`: **Default**, Solve all packages to the highest compatible version. - `lowest`: Solve all packages to the lowest compatible version. - `lowest-direct`: Solve only direct dependency packages to the lowest compatible version. Transitive dependencies are still sorted using the `highest` strategy. ```toml solve-strategy = "lowest" ``` Note When multiple features used in an environment set a specific solve strategy, the one from the left-most feature declared in the environment is used. ```toml [feature.one] solve-strategy = "lowest" [feature.two] solve-strategy = "lowest-direct" [environments] combined = ["two", "one"] # <- The solve strategy from feature `two` is used ``` ### `requires-pixi` (optional) The required version spec for `pixi` itself to resolve and build the workspace. If unset (**Default**), any version is ok. If set, it must be a string to a valid conda version spec, and the version of a running `pixi` must match the required spec before resolving or building the workspace, or exit with an error when not match. For example, with the following manifest, `pixi shell` will fail on `pixi 0.39.0`, but success after upgrading to `pixi 0.40.0`: ```toml [workspace] requires-pixi = ">=0.40" ``` The upper bound can also be limit like this: ```toml [workspace] requires-pixi = ">=0.40,<1.0" ``` Note This option should be used to improve the reproducibility of building the workspace. A complicated requirement spec may be an obstacle to setup the build environment. ### `exclude-newer` (optional) When specified this will exclude any package from consideration that is newer than the specified date. This is useful to reproduce installations regardless of new package releases. The date may be specified in the following formats: - As an [RFC 3339](https://www.rfc-editor.org/rfc/rfc3339.html) timestamp (e.g. `2023-10-01T00:00:00Z`) - As a date in the format `YYYY-MM-DD` (e.g. `2023-10-01`) in the systems time zone. Both PyPi and conda packages are considered. Note Note that for Pypi package indexes the package index must support the `upload-time` field as specified in [`PEP 700`](https://peps.python.org/pep-0700/). If the field is not present for a given distribution, the distribution will be treated as unavailable. PyPI provides `upload-time` for all packages. ### `build-variants` (optional) Preview Feature Build variants require the `pixi-build` preview feature to be enabled: ```toml [workspace] preview = ["pixi-build"] ``` Build variants allow you to specify different dependency versions for building packages in your workspace, creating a "build matrix" that targets multiple configurations. This is particularly useful for testing packages against different compiler versions, Python versions, or other critical dependencies. Build variants are defined as key-value pairs where each key represents a dependency name and the value is a list of version specifications to build against. #### Basic Usage ```toml [workspace.build-variants] python = ["3.11.*", "3.12.*"] c_compiler_version = ["11.4", "14.0"] ``` #### How Build Variants Work When build variants are specified, Pixi will: 1. **Create variant combinations**: Generate all possible combinations of the specified variants 1. **Build separate packages**: Create distinct package builds for each variant combination 1. **Resolve dependencies**: Ensure each variant resolves with compatible dependency versions 1. **Generate unique build strings**: Each variant gets a unique build identifier in the package name #### Platform-Specific Variants Build variants can also be specified per-platform: ```toml [workspace.build-variants] python = ["3.11.*", "3.12.*"] # Windows-specific variants [workspace.target.win-64.build-variants] python = ["3.11.*"] # Only Python 3.11 on Windows c_compiler = ["vs2019"] # Linux-specific variants [workspace.target.linux-64.build-variants] c_compiler = ["gcc"] c_compiler_version = ["11.4", "13.0"] ``` #### Common Use Cases - **Multi-version Python packages**: Build against Python 3.11 and 3.12 - **Compiler variants**: Test with different compiler versions for C/C++ packages - **Dependency compatibility**: Ensure packages work with different versions of key dependencies - **Cross-platform builds**: Different build configurations per operating system For detailed examples and tutorials, see the [build variants documentation](../../build/variants/). ### `build-variants-files` (optional) Preview Feature Build variant files require the `pixi-build` preview feature to be enabled: ```toml [workspace] preview = ["pixi-build"] ``` Use `build-variants-files` to reference external variant definitions from YAML files. Paths are resolved relative to the workspace root and processed in the listed orderβ€”entries from earlier files take precedence over values loaded from later ones. ```toml [workspace] build-variants-files = [ "./pinning/conda_build_config.yaml", "./variants/overrides.yaml", ] ``` Each entry must point to either a `conda_build_config.yaml` or another `.yaml` file that defines build variants. If the file is called `conda_build_config.yaml`, it will attempt to parse it with a subset of [`conda-build`'s variant syntax](https://docs.conda.io/projects/conda-build/en/stable/resources/variants.html#using-variants-with-the-conda-build-api). Otherwise, it will use `rattler-build`'s syntax as outlined in the [rattler-build documentation](https://rattler.build/latest/variants/#variant-configuration). ## The `tasks` table Tasks are a way to automate certain custom commands in your workspace. For example, a `lint` or `format` step. Tasks in a Pixi workspace are essentially cross-platform shell commands, with a unified syntax across platforms. For more in-depth information, check the [Advanced tasks documentation](../../workspace/advanced_tasks/). Pixi's tasks are run in a Pixi environment using `pixi run` and are executed using the [`deno_task_shell`](../../workspace/advanced_tasks/#our-task-runner-deno_task_shell). ```toml [tasks] simple = "echo This is a simple task" cmd = { cmd="echo Same as a simple task but now more verbose" } depending = { cmd="echo run after simple", depends-on="simple" } alias = { depends-on=["depending"] } download = { cmd="curl -o file.txt https://example.com/file.txt" , outputs=["file.txt"] } build = { cmd="npm build", cwd="frontend", inputs=["frontend/package.json", "frontend/*.js"] } run = { cmd="python run.py $ARGUMENT", env={ ARGUMENT="value" }} # Set an environment variable backend = { cmd="pytest", env={ BACKEND="{{ backend }}" }, args=[{arg="backend", default="numpy"}] } # Template strings in env format = { cmd="black $INIT_CWD" } # runs black where you run pixi run format clean-env = { cmd="python isolated.py", clean-env=true } # Only on Unix! test = { cmd="pytest", default-environment="test" } # Set a default pixi environment ``` You can modify this table using [`pixi task`](../cli/pixi/task/). Note Specify different tasks for different platforms using the [target](#the-target-table) table Info If you want to hide a task from showing up with `pixi task list` or `pixi info`, you can prefix the name with `_`. For example, if you want to hide `depending`, you can rename it to `_depending`. ## The `system-requirements` table The system requirements are used to define minimal system specifications used during dependency resolution. For example, we can define a unix system with a specific minimal libc version. ```toml [system-requirements] libc = "2.28" ``` or make the workspace depend on a specific version of `cuda`: ```toml [system-requirements] cuda = "12" ``` The options are: - `linux`: The minimal version of the linux kernel. - `libc`: The minimal version of the libc library. Also allows specifying the family of the libc library. e.g. `libc = { family="glibc", version="2.28" }` - `macos`: The minimal version of the macOS operating system. - `cuda`: The minimal version of the CUDA library. More information in the [system requirements documentation](../../workspace/system_requirements/). ## The `pypi-options` table The `pypi-options` table is used to define options that are specific to PyPI registries. These options can be specified either at the root level, which will add it to the default options feature, or on feature level, which will create a union of these options when the features are included in the environment. The options that can be defined are: - `index-url`: replaces the main index url. - `extra-index-urls`: adds an extra index url. - `find-links`: similar to `--find-links` option in `pip`. - `no-build-isolation`: disables build isolation, can only be set per package. - `no-build`: don't build source distributions. - `no-binary`: don't use pre-build wheels. - `index-strategy`: allows for specifying the index strategy to use. - `prerelease-mode`: controls whether pre-release versions are allowed during dependency resolution. - `skip-wheel-filename-check`: allows installing wheels with version mismatches between filename and metadata. These options are explained in the sections below. Most of these options are taken directly or with slight modifications from the [uv settings](https://docs.astral.sh/uv/reference/settings/). If any are missing that you need feel free to create an issue [requesting](https://github.com/prefix-dev/pixi/issues) them. ### Alternative registries Strict Index Priority Unlike pip, because we make use of uv, we have a strict index priority. This means that the first index is used where a package can be found. The order is determined by the order in the toml file. Where the `extra-index-urls` are preferred over the `index-url`. Read more about this on the [uv docs](https://docs.astral.sh/uv/pip/compatibility/#packages-that-exist-on-multiple-indexes) Often you might want to use an alternative or extra index for your workspace. This can be done by adding the `pypi-options` table to your `pixi.toml` file, the following options are available: - `index-url`: replaces the main index url. If this is not set the default index used is `https://pypi.org/simple`. **Only one** `index-url` can be defined per environment. - `extra-index-urls`: adds an extra index url. The urls are used in the order they are defined. And are preferred over the `index-url`. These are merged across features into an environment. - `find-links`: which can either be a path `{path = './links'}` or a url `{url = 'https://example.com/links'}`. This is similar to the `--find-links` option in `pip`. These are merged across features into an environment. An example: ```toml [pypi-options] index-url = "https://pypi.org/simple" extra-index-urls = ["https://example.com/simple"] find-links = [{path = './links'}] ``` There are some [examples](https://github.com/prefix-dev/pixi/tree/main/examples/pypi-custom-registry) in the Pixi repository, that make use of this feature. Authentication Methods To read about existing authentication methods for private registries, please check the [PyPI Authentication](../../deployment/authentication/#pypi-authentication) section. ### No Build Isolation Even though build isolation is a good default. One can choose to **not** isolate the build for a certain package name, this allows the build to access the `pixi` environment. This is convenient if you want to use `torch` or something similar for your build-process. ```toml [dependencies] pytorch = "2.4.0" [pypi-options] no-build-isolation = ["detectron2"] [pypi-dependencies] detectron2 = { git = "https://github.com/facebookresearch/detectron2.git", rev = "5b72c27ae39f99db75d43f18fd1312e1ea934e60"} ``` Setting `no-build-isolation` also affects the order in which PyPI packages are installed. Packages are installed in that order: - conda packages in one go - packages with build isolation in one go - packages without build isolation installed in the order they are added to `no-build-isolation` It is also possible to remove all packages from build isolation by setting the `no-build-isolation` to `true`. ```toml [pypi-options] no-build-isolation = true ``` Conda dependencies define the build environment To use `no-build-isolation` effectively, use conda dependencies to define the build environment. These are installed before the PyPI dependencies are resolved, this way these dependencies are available during the build process. In the example above adding `torch` as a PyPI dependency would be ineffective, as it would not yet be installed during the PyPI resolution phase. ### No Build When enabled, resolving will not run arbitrary Python code. The cached wheels of already-built source distributions will be reused, but operations that require building distributions will exit with an error. Can be either set per package or globally. ```toml [pypi-options] # No sdists allowed no-build = true # default is false ``` or: ```toml [pypi-options] no-build = ["package1", "package2"] ``` When features are merged, the following priority is adhered: `no-build = true` > `no-build = ["package1", "package2"]` > `no-build = false` So, to expand: if `no-build = true` is set for *any* feature in the environment, this will be used as the setting for the environment. ### No Binary Don't install pre-built wheels. The given packages will be built and installed from source. The resolver will still use pre-built wheels to extract package metadata, if available. Can be either set per package or globally. ```toml [pypi-options] # Never use pre-build wheels no-binary = true # default is false ``` or: ```toml [pypi-options] no-binary = ["package1", "package2"] ``` When features are merged, the following priority is adhered: `no-binary = true` > `no-binary = ["package1", "package2"]` > `no-binary = false` So, to expand: if `no-binary = true` is set for *any* feature in the environment, this will be used as the setting for the environment. ### Index Strategy The strategy to use when resolving against multiple index URLs. Description modified from the [uv](https://docs.astral.sh/uv/reference/settings/#index-strategy) documentation: By default, `uv` and thus `pixi`, will stop at the first index on which a given package is available, and limit resolutions to those present on that first index (first-match). This prevents *dependency confusion* attacks, whereby an attack can upload a malicious package under the same name to a secondary index. One index strategy per environment Only one `index-strategy` can be defined per environment or solve-group, otherwise, an error will be shown. #### Possible values: - **"first-index"**: Only use results from the first index that returns a match for a given package name - **"unsafe-first-match"**: Search for every package name across all indexes, exhausting the versions from the first index before moving on to the next. Meaning if the package `a` is available on index `x` and `y`, it will prefer the version from `x` unless you've requested a package version that is **only** available on `y`. - **"unsafe-best-match"**: Search for every package name across all indexes, preferring the *best* version found. If a package version is in multiple indexes, only look at the entry for the first index. So given index, `x` and `y` that both contain package `a`, it will take the *best* version from either `x` or `y`, but should **that version** be available on both indexes it will prefer `x`. PyPI only The `index-strategy` only changes PyPI package resolution and not conda package resolution. ### Prerelease Mode The strategy to use when considering pre-release versions during dependency resolution. Description taken from the [uv documentation](https://docs.astral.sh/uv/reference/settings/#prerelease). By default, `pixi` will allow pre-release versions when a package only has pre-release versions available, or when a pre-release version is explicitly requested in the version specifier (e.g., `>=1.0.0a1`). One prerelease mode per environment Only one `prerelease-mode` can be defined per environment or solve-group, otherwise, an error will be shown. #### Possible values: - **"disallow"**: Disallow all pre-release versions. - **"allow"**: Allow all pre-release versions. - **"if-necessary"**: Allow pre-release versions if all versions of a package are pre-release. - **"explicit"**: Allow pre-release versions for first-party packages with explicit pre-release markers in their version requirements. - **"if-necessary-or-explicit"** (default): Allow pre-release versions if all versions of a package are pre-release, or if the package has an explicit pre-release marker in its version requirements. Example: ```toml [pypi-options] prerelease-mode = "allow" # Allow all pre-release versions ``` ### Skip Wheel Filename Check By default, `uv` validates that wheel filenames match the package metadata (name and version) inside the wheel. This validation ensures that wheels are correctly named and helps prevent installation of malformed packages. However, in some cases you may need to install wheels where the filename version doesn't match the metadata version. The `skip-wheel-filename-check` option allows you to disable this validation. One skip-wheel-filename-check per environment Only one `skip-wheel-filename-check` can be defined per environment or solve-group, otherwise, an error will be shown. #### Possible values: - **`false`** (default): Perform wheel filename validation. Installation will fail if filename and metadata don't match. - **`true`**: Skip wheel filename validation. Allow installing wheels with mismatched filename and metadata versions. #### Precedence The `UV_SKIP_WHEEL_FILENAME_CHECK` environment variable takes precedence over the `skip-wheel-filename-check` pypi-option. This allows for temporary overrides without modifying the manifest. Example: ```toml [pypi-options] # Allow installing malformed wheels skip-wheel-filename-check = true ``` Or set per feature: ```toml [feature.special.pypi-options] # Only for this feature's environment skip-wheel-filename-check = true ``` ## The `dependencies` table(s) Details regarding the dependencies For more detail regarding the dependency types, make sure to check the [Run, Host, Build](../../build/dependency_types/) dependency documentation. This section defines what dependencies you would like to use for your workspace. There are multiple dependencies tables. The default is `[dependencies]`, which are dependencies that are shared across platforms. Dependencies are defined using a [VersionSpec](https://docs.rs/rattler_conda_types/latest/rattler_conda_types/version_spec/enum.VersionSpec.html). A `VersionSpec` combines a [Version](https://docs.rs/rattler_conda_types/latest/rattler_conda_types/struct.Version.html) with an optional operator. Need to specify build strings or more specific packages? For detailed information on specifying build strings and advanced package specifications, see the [Package Specifications](../../concepts/package_specifications/) guide. Some examples are: ```toml # Use this exact package version package0 = "==1.2.3" # Use 1.2.3 up to 1.3.0 package1 = "~=1.2.3" # Use larger than 1.2 lower and equal to 1.4 package2 = ">1.2,<=1.4" # Bigger or equal than 1.2.3 or lower not including 1.0.0 package3 = ">=1.2.3|<1.0.0" ``` Dependencies can also be defined as a mapping where it is using a matchspec ```toml package0 = { version = ">=1.2.3", channel="conda-forge" } package1 = { version = ">=1.2.3", build="py34_0" } ``` Tip The dependencies can be easily added using the `pixi add` command line. Running `add` for an existing dependency will replace it with the newest it can use. Note To specify different dependencies for different platforms use the [target](#the-target-table) table ### `dependencies` Add any conda package dependency that you want to install into the environment. Don't forget to add the channel to the `workspace` table should you use anything different than `conda-forge`. Even if the dependency defines a channel that channel should be added to the `workspace.channels` list. ```toml [dependencies] python = ">3.9,<=3.11" rust = "==1.72" pytorch-cpu = { version = "~=1.1", channel = "pytorch" } ``` ### `constraints` The `constraints` table lets you restrict the versions of conda packages that *may* be installed without explicitly requiring them. A constraint is only enforced when the package in question is actually present in the environment (pulled in by another dependency); if the package is not needed, the constraint is silently ignored. This is useful for two common scenarios: - **Preventing known-bad versions** – you know that a transitive dependency has a regression in a certain version range and you want to rule it out without adding a hard dependency. - **Coordinating optional packages** – your project works with or without an optional library, but if that library is installed it must be a specific generation (e.g. CUDA 12 vs 11). ```toml [workspace] channels = ["conda-forge"] platforms = ["linux-64", "osx-arm64", "win-64"] [dependencies] # openssl will be pulled in transitively; this constraint # ensures we never end up with a vulnerable 1.x release. requests = ">=2.28" [constraints] openssl = ">=3.0" ``` Constraints use the same [VersionSpec](https://docs.rs/rattler_conda_types/latest/rattler_conda_types/version_spec/enum.VersionSpec.html) syntax as `[dependencies]`. Note Constraints do **not** cause a package to be installed. They only restrict which version is acceptable *if* the package is already being installed. Use `[dependencies]` when you actually need the package to be present. #### Platform-specific constraints Like `[dependencies]`, constraints can be made platform-specific using the [`[target]`](#the-target-table) table: ```toml [constraints] openssl = ">=3.0" [target.linux-64.constraints] # Tighten the constraint further on Linux openssl = ">=3.0.7" ``` #### Per-feature constraints and merging Constraints can also be scoped to a [feature](#the-feature-table). When an environment is composed of multiple features, constraints from **all active features are concatenated**, exactly like `[dependencies]`. This means each feature can independently constrain transitive dependencies, and the resulting environment must satisfy all of them simultaneously. ```toml [dependencies] python = ">=3.11" [feature.cuda.dependencies] pytorch-gpu = ">=2.0" # When the cuda feature is active, enforce a compatible CUDA toolkit version [feature.cuda.constraints] cuda = ">=12.0" [feature.cuda11.constraints] cuda = "<12" [environments] gpu = ["cuda"] legacy-gpu = ["cuda11"] ``` In the `gpu` environment the solver sees `cuda = ">=12.0"` as a constraint; in the `legacy-gpu` environment it sees `cuda = "<12"`. If both features were active in the same environment the solver would receive both constraints and would need to find a version that satisfies all of them. ### `pypi-dependencies` Details regarding the PyPI integration We use [`uv`](https://github.com/astral-sh/uv), which is a new fast pip replacement written in Rust. We integrate uv as a library, so we use the uv resolver, to which we pass the conda packages as 'locked'. This disallows uv from installing these dependencies itself, and ensures it uses the exact version of these packages in the resolution. This is unique amongst conda based package managers, which usually just call pip from a subprocess. The uv resolution is included in the lock file directly. Pixi directly supports depending on PyPI packages, the PyPA calls a distributed package a 'distribution'. There are [Source](https://packaging.python.org/en/latest/specifications/source-distribution-format/) and [Binary](https://packaging.python.org/en/latest/specifications/binary-distribution-format/) distributions both of which are supported by pixi. These distributions are installed into the environment after the conda environment has been resolved and installed. PyPI packages are not indexed on [prefix.dev](https://prefix.dev/channels) but can be viewed on [pypi.org](https://pypi.org/). Important considerations - **Stability**: PyPI packages might be less stable than their conda counterparts. Prefer using conda packages in the `dependencies` table where possible. #### Version specification: These dependencies don't follow the [conda MatchSpec](https://rattler.prefix.dev/py-rattler/match_spec#matchspec) specification. The `version` is a string specification of the version according to [PEP404/PyPA](https://packaging.python.org/en/latest/specifications/version-specifiers/). Additionally, a list of extra's can be included, which are essentially optional dependencies. Note that this `version` is distinct from the conda MatchSpec type. See the example below to see how this is used in practice: ```toml [dependencies] # When using pypi-dependencies, python is needed to resolve pypi dependencies # make sure to include this python = ">=3.6" [pypi-dependencies] fastapi = "*" # This means any version (the wildcard `*` is a pixi addition, not part of the specification) pre-commit = "~=3.5.0" # This is a single version specifier # Using the toml map allows the user to add `extras` pandas = { version = ">=1.0.0", extras = ["dataframe", "sql"]} # git dependencies # With ssh flask = { git = "ssh://git@github.com/pallets/flask" } # With https and a specific revision httpx = { git = "https://github.com/encode/httpx.git", rev = "c7c13f18a5af4c64c649881b2fe8dbd72a519c32"} # With https and a specific branch boltons = { git = "https://github.com/mahmoud/boltons.git", branch = "master" } # With https and a specific tag boltons = { git = "https://github.com/mahmoud/boltons.git", tag = "25.0.0" } # With https, specific tag and some subdirectory boltons = { git = "https://github.com/mahmoud/boltons.git", tag = "25.0.0", subdirectory = "some-subdir" } # You can also directly add a source dependency from a path, tip keep this relative to the root of the workspace. minimal-project = { path = "./minimal-project", editable = true} # You can also use a direct url, to either a `.tar.gz` or `.zip`, or a `.whl` file click = { url = "https://github.com/pallets/click/releases/download/8.1.7/click-8.1.7-py3-none-any.whl" } # You can also just the default git repo, it will checkout the default branch pytest = { git = "https://github.com/pytest-dev/pytest.git"} ``` Using git SSH URLs When using SSH URLs in git dependencies, make sure to have your SSH key added to your SSH agent. You can do this by running `ssh-add` which will prompt you for your SSH key passphrase. Make sure that the `ssh-add` agent or service is running and you have a generated public/private SSH key. For more details on how to do this, check the [Github SSH documentation](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent). #### Full specification The full specification of a PyPI dependencies that Pixi supports can be split into the following fields: ##### `extras` A list of extras to install with the package. e.g. `["dataframe", "sql"]` The extras field works with all other version specifiers as it is an addition to the version specifier. ```toml pandas = { version = ">=1.0.0", extras = ["dataframe", "sql"]} pytest = { git = "URL", extras = ["dev"]} black = { url = "URL", extras = ["cli"]} minimal-project = { path = "./minimal-project", editable = true, extras = ["dev"]} ``` ##### `version` The version of the package to install. e.g. `">=1.0.0"` or `*` which stands for any version, this is Pixi specific. Version is our default field so using no inline table (`{}`) will default to this field. ```toml py-rattler = "*" ruff = "~=1.0.0" pytest = {version = "*", extras = ["dev"]} ``` ##### `index` The index parameter allows you to specify the URL of a custom package index for the installation of a specific package. This feature is useful when you want to ensure that a package is retrieved from a particular source, rather than from the default index. For example, to use some other than the official Python Package Index (PyPI) at https://pypi.org/simple, you can use the `index` parameter: ```toml torch = { version = "*", index = "https://download.pytorch.org/whl/cu118" } ``` This is useful for PyTorch specifically, as the registries are pinned to different CUDA versions. Learn more about installing PyTorch [here](../../python/pytorch/). ##### `git` A git repository to install from. This support both https:// and ssh:// urls. Use `git` in combination with `rev` or `subdirectory`: - `rev`: A specific revision to install. e.g. `rev = "0106aced5faa299e6ede89d1230bd6784f2c3660` - `subdirectory`: A subdirectory to install from. `subdirectory = "src"` or `subdirectory = "src/packagex"` ```toml # Note don't forget the `ssh://` or `https://` prefix! pytest = { git = "https://github.com/pytest-dev/pytest.git"} httpx = { git = "https://github.com/encode/httpx.git", rev = "c7c13f18a5af4c64c649881b2fe8dbd72a519c32"} py-rattler = { git = "ssh://git@github.com/conda/rattler.git", subdirectory = "py-rattler" } ``` ##### `path` A local path to install from. e.g. `path = "./path/to/package"` We would advise to keep your path projects in the workspace, and to use a relative path. Set `editable` to `true` to install in editable mode, this is highly recommended as it is hard to reinstall if you're not using editable mode. e.g. `editable = true` ```toml minimal-project = { path = "./minimal-project", editable = true} ``` ##### `url` A URL to install a wheel or sdist directly from an url. ```toml pandas = {url = "https://files.pythonhosted.org/packages/3d/59/2afa81b9fb300c90531803c0fd43ff4548074fa3e8d0f747ef63b3b5e77a/pandas-2.2.1.tar.gz"} ``` Did you know you can use: `add --pypi`? Use the `--pypi` flag with the `add` command to quickly add PyPI packages from the CLI. E.g `pixi add --pypi flask` *This does not support all the features of the `pypi-dependencies` table yet.* #### Source dependencies (`sdist`) The [Source Distribution Format](https://packaging.python.org/en/latest/specifications/source-distribution-format/) is a source based format (sdist for short), that a package can include alongside the binary wheel format. Because these distributions need to be built, the need a python executable to do this. This is why python needs to be present in a conda environment. Sdists usually depend on system packages to be built, especially when compiling C/C++ based python bindings. Think for example of Python SDL2 bindings depending on the C library: SDL2. To help built these dependencies we activate the conda environment that includes these pypi dependencies before resolving. This way when a source distribution depends on `gcc` for example, it's used from the conda environment instead of the system. ## The `activation` table The activation table is used for specialized activation operations that need to be run when the environment is activated. There are two types of activation operations a user can modify in the manifest: - `scripts`: A list of scripts that are run when the environment is activated. - `env`: A mapping of environment variables that are set when the environment is activated. These activation operations will be run before the `pixi run` and `pixi shell` commands. Note The script specified in the `scripts` section are not directly sourced in the `pixi shell`, but rather they are called, and the environment variables they set are then set in the `pixi shell`, so any defined function or other non-environment variable modification to the environment will be ignored. Note The activation operations are run by the system shell interpreter as they run before an environment is available. This means that it runs as `cmd.exe` on windows and `bash` on linux and osx (Unix). Only `.sh`, `.bash` and `.bat` files are supported. And the environment variables are set in the shell that is running the activation script, thus take note when using e.g. `$` or `%`. If you have scripts or env variable per platform use the [target](#the-target-table) table. ```toml [activation] scripts = ["env_setup.sh"] env = { ENV_VAR = "value" } # To support windows platforms as well add the following [target.win-64.activation] scripts = ["env_setup.bat"] [target.linux-64.activation.env] ENV_VAR = "linux-value" # You can also reference existing environment variables, but this has # to be done separately for unix-like operating systems and Windows [target.unix.activation.env] ENV_VAR = "$OTHER_ENV_VAR/unix-value" [target.win.activation.env] ENV_VAR = "%OTHER_ENV_VAR%\\windows-value" ``` ## The `target` table The target table is a table that allows for platform specific configuration. Allowing you to make different sets of tasks or dependencies per platform. The target table is currently implemented for the following sub-tables: - [`activation`](#the-activation-table) - [`dependencies`](#dependencies) - [`constraints`](#constraints) - [`tasks`](#the-tasks-table) The target table is defined using `[target.PLATFORM.SUB-TABLE]`. E.g `[target.linux-64.dependencies]` The platform can be any of: - `win`, `osx`, `linux` or `unix` (`unix` matches `linux` and `osx`) - or any of the (more) specific [target platforms](#platforms), e.g. `linux-64`, `osx-arm64` The sub-table can be any of the specified above. To make it a bit more clear, let's look at an example below. Currently, Pixi combines the top level tables like `dependencies` with the target-specific ones into a single set. Which, in the case of dependencies, can both add or overwrite dependencies. In the example below, we have `cmake` being used for all targets but on `osx-64` or `osx-arm64` a different version of python will be selected. ```toml [dependencies] cmake = "3.26.4" python = "3.10" [target.osx.dependencies] python = "3.11" ``` Here are some more examples: ```toml [target.win-64.activation] scripts = ["setup.bat"] [target.win-64.dependencies] msmpi = "~=10.1.1" [target.win-64.build-dependencies] vs2022_win-64 = "19.36.32532" [target.win-64.tasks] tmp = "echo $TEMP" [target.osx-64.dependencies] clang = ">=16.0.6" ``` ## The `feature` and `environments` tables The `feature` table allows you to define features that can be used to create different `[environments]`. The `[environments]` table allows you to define different environments. The design is explained in the [this design document](../../workspace/multi_environment/). Simplest example ```toml [feature.test.dependencies] pytest = "*" [environments] test = ["test"] ``` This will create an environment called `test` that has `pytest` installed. ### The `feature` table The `feature` table allows you to define the following fields per feature. - `dependencies`: Same as the [dependencies](#dependencies). - `constraints`: Same as the [constraints](#constraints). - `pypi-dependencies`: Same as the [pypi-dependencies](#pypi-dependencies). - `pypi-options`: Same as the [pypi-options](#the-pypi-options-table). - `system-requirements`: Same as the [system-requirements](#the-system-requirements-table). - `activation`: Same as the [activation](#the-activation-table). - `platforms`: Same as the [platforms](#platforms). Unless overridden, the `platforms` of the feature will be those defined at workspace level. - `channels`: Same as the [channels](#channels). Unless overridden, the `channels` of the feature will be those defined at workspace level. - `channel-priority`: Same as the [channel-priority](#channel-priority-optional). - `solve-strategy`: Same as the [solve-strategy](#solve-strategy-optional). - `target`: Same as the [target](#the-target-table). - `tasks`: Same as the [tasks](#the-tasks-table). These tables are all also available without the `feature` prefix. When those are used we call them the `default` feature. This is a protected name you can not use for your own feature. Cuda feature table example ```toml [feature.cuda] activation = {scripts = ["cuda_activation.sh"]} # Results in: ["nvidia", "conda-forge"] when the default is `conda-forge` channels = ["nvidia"] dependencies = {cuda = "x.y.z", cudnn = "12.0"} constraints = {cuda = ">=12.0"} pypi-dependencies = {torch = "==1.9.0"} platforms = ["linux-64", "osx-arm64"] system-requirements = {cuda = "12"} tasks = { warmup = "python warmup.py" } target.osx-arm64 = {dependencies = {mlx = "x.y.z"}} ``` Cuda feature table example but written as separate tables ```toml [feature.cuda.activation] scripts = ["cuda_activation.sh"] [feature.cuda.dependencies] cuda = "x.y.z" cudnn = "12.0" [feature.cuda.pypi-dependencies] torch = "==1.9.0" [feature.cuda.system-requirements] cuda = "12" [feature.cuda.tasks] warmup = "python warmup.py" [feature.cuda.target.osx-arm64.dependencies] mlx = "x.y.z" # Channels and Platforms are not available as separate tables as they are implemented as lists [feature.cuda] channels = ["nvidia"] platforms = ["linux-64", "osx-arm64"] ``` ### The `environments` table The `[environments]` table allows you to define environments that are created using the features defined in the `[feature]` tables. The environments table is defined using the following fields: - `features`: The features that are included in the environment. Unless `no-default-feature` is set to `true`, the default feature is implicitly included in the environment. - `solve-group`: The solve group is used to group environments together at the solve stage. This is useful for environments that need to have the same dependencies but might extend them with additional dependencies. For instance when testing a production environment with additional test dependencies. These dependencies will then be the same version in all environments that have the same solve group. But the different environments contain different subsets of the solve-groups dependencies set. - `no-default-feature`: Whether to include the default feature in that environment. The default is `false`, to include the default feature. Full environments table specification ```toml [environments] test = {features = ["test"], solve-group = "test"} prod = {features = ["prod"], solve-group = "test"} lint = {features = ["lint"], no-default-feature = true} ``` As shown in the example above, in the simplest of cases, it is possible to define an environment only by listing its features: Simplest example ```toml [environments] test = ["test"] ``` is equivalent to Simplest example expanded ```toml [environments] test = {features = ["test"]} ``` When an environment comprises several features (including the default feature): - The `activation` and `tasks` of the environment are the union of the `activation` and `tasks` of all its features. - The `dependencies` and `pypi-dependencies` of the environment are the union of the `dependencies` and `pypi-dependencies` of all its features. This means that if several features define a requirement for the same package, both requirements will be combined. Beware of conflicting requirements across features added to the same environment. - The `system-requirements` of the environment is the union of the `system-requirements` of all its features. If multiple features specify a requirement for the same system package, the highest version is chosen. - The `channels` of the environment is the union of the `channels` of all its features. Channel priorities can be specified in each feature, to ensure channels are considered in the right order in the environment. - The `platforms` of the environment is the intersection of the `platforms` of all its features. Be aware that the platforms supported by a feature (including the default feature) will be considered as the `platforms` defined at workspace level (unless overridden in the feature). This means that it is usually a good idea to set the workspace `platforms` to all platforms it can support across its environments. ## Global configuration The global configuration options are documented in the [global configuration](../pixi_configuration/) section. ## Preview features Pixi sometimes introduces new features that are not yet stable, but that we would like for users to test out. These features are called preview features. Preview features are disabled by default and can be enabled by setting the `preview` field in the workspace manifest. The preview field is an array of strings that specify the preview features to enable, or the boolean value `true` to enable all preview features. An example of a preview feature in the manifest: ```toml [workspace] preview = ["pixi-build"] ``` Preview features in the documentation will be marked as such on the relevant pages. ## The `dev` table The `dev` table allows you to depend on the development dependencies of a source package. ```toml [dev] my-package = { path = "src/my-package" } ``` This will install the `build-dependencies`, `host-dependencies` and `run-dependencies` defined in the package located at `src/my-package`. More information can be found in the [Dev packages](../../build/dev/) documentation. ## The `package` section Important note `pixi-build` is a [preview feature](#preview-features), and will change until it is stabilized. Please keep that in mind when you use it for your workspaces. ```toml [workspace] preview = ["pixi-build"] ``` The package section can be added to a workspace manifest to define the package that is built by Pixi. A package section needs to be inside a `workspace`, either in the same manifest file as the `[workspace]` table or in a sub folder `pixi.toml`/`pyproject.toml` file. These packages will be built into a conda package that can be installed into a conda environment. The package section is defined using the following fields: - `name`: The name of the package. - `version`: The version of the package. - `build`: The build system used to build the package. - `build-dependencies`: The build dependencies of the package. - `host-dependencies`: The host dependencies of the package. - `run-dependencies`: The run dependencies of the package. - `target`: The target table to configure target specific dependencies. (Similar to the [target](#the-target-table) table) And to extend the basics, it can also contain the following fields: - `description`: A short description of the package. - `authors`: A list of authors of the package. - `license`: The license of the package. - `license-file`: The license file of the package. - `readme`: The README file of the package. - `homepage`: The homepage link of the package. - `repository`: The repository link of the package. - `documentation`: The documentation link of the package. ```toml [package] name = "package" version = "0.1.0" authors = ["Author Name "] description = "A package description" documentation = "https://docs.example.com" homepage = "https://example.com" license = "MIT" license-file = "LICENSE" readme = "README.md" repository = "https://github.com/user/repo" ``` Workspace inheritance Most extra fields can be inherited from the workspace manifest. This means that you can define the `description`, `authors`, `license` in the workspace manifest, and they will be inherited by the package manifest. ```toml [workspace] name = "my-workspace" [package] name = { workspace = true } # Inherit the name from the workspace ``` ### `build` table The build system specifies how the package can be built. The build system is a table that can contain the following fields: - `source`: specifies the location of the source code for the package. Default: manifest directory. Currently supported options: - `path`: a string representing a relative or absolute path to the source code. - `git`: a string representing URL to the source repository. - `rev`: a string representing SHA revision to checkout. - `subdirectory`: a string representing path to subdirectory to use. - `channels`: specifies the channels to get the build backend from. - `backend`: specifies the build backend to use. This is a table that can contain the following fields: - `name`: the name of the build backend to use. This will also be the executable name. - `version`: the version of the build backend to use. - `config`: a table that contains the configuration options for the build backend. - `target`: a table that can contain target specific build configuration. - Each target can have its own `config` table to override or extend the base configuration for specific platforms. More documentation on the backends can be found in the [build backend documentation](../../build/backends/). #### Basic build configuration example ```toml [package.build] backend = { name = "pixi-build-cmake", version = "0.3.*" } # not required: channels = ["https://prefix.dev/conda-forge"] config = { key = "value" } # Optional configuration, specific to the build backend ``` #### Target-specific build configuration example For platform-specific build configuration, use the `[package.build.target.]` table: ```toml [package.build] backend = { name = "pixi-build-cmake", version = "0.3.*" } [package.build.config] # Base configuration applied to all platforms extra-args = ["-DCMAKE_BUILD_TYPE=Release"] [package.build.target.linux-64.config] # Linux-specific configuration extra-args = ["-DCMAKE_BUILD_TYPE=Debug", "-DLINUX_FLAG=ON"] [package.build.target.win-64.config] # Windows-specific configuration extra-args = ["-DCMAKE_BUILD_TYPE=Debug", "-DWIN_FLAG=ON"] ``` ### The `build` `host` and `run` dependencies tables The dependencies of a package are split into three tables. Each of these tables has a different purpose and is used to define the dependencies of the package. - [`build-dependencies`](#build-dependencies): Dependencies that are required to build the package on the build platform. - [`host-dependencies`](#host-dependencies): Dependencies that are required during the build process, to link against the package on the target platform. - [`run-dependencies`](#run-dependencies): Dependencies that are required to run the package on the target platform. ### `build-dependencies` Build dependencies are required in the build environment and contain all tools that are not needed on the host of the package. Following packages are examples of typical build dependencies: - compilers (`gcc`, `clang`, `gfortran`) - build tools (`cmake`, `ninja`, `meson`) - `make` - `pkg-config` - VSC packages (`git`, `svn`) Using git SSH URLs When using SSH URLs in git dependencies, make sure to have your SSH key added to your SSH agent. You can do this by running `ssh-add` which will prompt you for your SSH key passphrase. Make sure that the `ssh-add` agent or service is running and you have a generated public/private SSH key. For more details on how to do this, check the [Github SSH documentation](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent). ```toml [package.build-dependencies] cmake = "*" git = "*" ``` ### `host-dependencies` Host dependencies are required during build phase, but in contrast to build packages they have to be present on the host. Following packages are typical examples for host dependencies: - shared libraries (c/c++) - python/r libraries that link against c libraries - `python`, `r-base` - `setuptools`, `pip` ```toml [package.host-dependencies] python = "*" ``` ### `run-dependencies` The `run-dependencies` are the packages that will be installed in the environment when the package is run. - Libraries - Extra data file packages - Python/R packages that are not needed during build time ```toml [package.run-dependencies] rich = ">=13.9.4,<14" ``` This directory contains the same structure as the autogenerated cli documentation. In all the autogenerated files, there are `snippets` injected like `description` and `example`. If you put a file with the same file name and path as the autogenerated companion file, the `snippets` will be injected into the file. For example, `docs/autogenerated/pixi.md` is the autogenerated file and `docs/reference/cli/pixi.md` is the injecting file. Snipped documentation can be found here: https://facelessuser.github.io/pymdown-extensions/extensions/snippets/ # pixi The `pixi` command is the main entry point for the Pixi CLI. ## Usage ```text pixi [OPTIONS] [COMMAND] ``` ## Subcommands | Command | Description | | ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | [`add`](add/) | Adds dependencies to the workspace | | [`auth`](auth/) | Login to prefix.dev or anaconda.org servers to access private channels | | [`build`](build/) | Build a conda package from a Pixi package. | | [`clean`](clean/) | Cleanup the environments | | [`completion`](completion/) | Generates a completion script for a shell | | [`config`](config/) | Configuration management | | [`exec`](exec/) | Run a command and install it in a temporary environment | | [`global`](global/) | Subcommand for global package management actions | | [`info`](info/) | Information about the system, workspace and environments for the current machine | | [`init`](init/) | Creates a new workspace | | [`import`](import/) | Imports a file into an environment in an existing workspace. | | [`install`](install/) | Install an environment, both updating the lockfile and installing the environment | | [`list`](list/) | List the packages of the current workspace | | [`lock`](lock/) | Solve environment and update the lock file without installing the environments | | [`reinstall`](reinstall/) | Re-install an environment, both updating the lockfile and re-installing the environment | | [`remove`](remove/) | Removes dependencies from the workspace | | [`run`](run/) | Runs task in the pixi environment | | [`search`](search/) | Search a conda package | | [`self-update`](self-update/) | Update pixi to the latest version or a specific version | | [`shell`](shell/) | Start a shell in a pixi environment, run `exit` to leave the shell | | [`shell-hook`](shell-hook/) | Print the pixi environment activation script | | [`task`](task/) | Interact with tasks in the workspace | | [`tree`](tree/) | Show a tree of workspace dependencies | | [`update`](update/) | The `update` command checks if there are newer versions of the dependencies and updates the `pixi.lock` file and environments accordingly | | [`upgrade`](upgrade/) | Checks if there are newer versions of the dependencies and upgrades them in the lockfile and manifest file | | [`upload`](upload/) | Upload conda packages to various channels | | [`workspace`](workspace/) | Modify the workspace configuration file through the command line | ## Global Options - [`--help (-h)`](#arg---help) : Display help information - [`--verbose (-v)`](#arg---verbose) : Increase logging verbosity (-v for warnings, -vv for info, -vvv for debug, -vvvv for trace) - [`--quiet (-q)`](#arg---quiet) : Decrease logging verbosity (quiet mode) - [`--color `](#arg---color) : Whether the log needs to be colored ``` **env**: `PIXI_COLOR` **default**: `auto` **options**: `always`, `never`, `auto` ``` - [`--no-progress`](#arg---no-progress) : Hide all progress bars, always turned on if stderr is not a terminal ``` **env**: `PIXI_NO_PROGRESS` **default**: `false` ``` - [`--list`](#arg---list) : List all installed commands (built-in and extensions) # [pixi](../) add Adds dependencies to the workspace ## Usage ```text pixi add [OPTIONS] ... ``` ## Arguments - [``](#arg-%3CSPEC%3E) : The dependency as names, conda MatchSpecs or PyPi requirements ``` May be provided more than once. **required**: `true` ``` ## Options - [`--pypi`](#arg---pypi) : The specified dependencies are pypi dependencies. Conflicts with `host` and `build` - [`--platform (-p) `](#arg---platform) : The platform for which the dependency should be modified ``` May be provided more than once. ``` - [`--feature (-f) `](#arg---feature) : The feature for which the dependency should be modified ``` **default**: `default` ``` - [`--editable`](#arg---editable) : Whether the pypi requirement should be editable ## Config Options - [`--auth-file `](#arg---auth-file) : Path to the file containing the authentication token - [`--concurrent-downloads `](#arg---concurrent-downloads) : Max concurrent network requests, default is `50` - [`--concurrent-solves `](#arg---concurrent-solves) : Max concurrent solves, default is the number of CPUs - [`--pinning-strategy `](#arg---pinning-strategy) : Set pinning strategy ``` **options**: `semver`, `minor`, `major`, `latest-up`, `exact-version`, `no-pin` ``` - [`--pypi-keyring-provider `](#arg---pypi-keyring-provider) : Specifies whether to use the keyring to look up credentials for PyPI ``` **options**: `disabled`, `subprocess` ``` - [`--run-post-link-scripts`](#arg---run-post-link-scripts) : Run post-link scripts (insecure) - [`--tls-no-verify`](#arg---tls-no-verify) : Do not verify the TLS certificate of the server - [`--tls-root-certs `](#arg---tls-root-certs) : Which TLS root certificates to use: 'webpki' (bundled Mozilla roots), 'native' (system store), or 'all' (both) ``` **env**: `PIXI_TLS_ROOT_CERTS` ``` - [`--use-environment-activation-cache`](#arg---use-environment-activation-cache) : Use environment activation cache (experimental) ## Git Options - [`--git (-g) `](#arg---git) : The git url to use when adding a git dependency - [`--branch `](#arg---branch) : The git branch - [`--tag `](#arg---tag) : The git tag - [`--rev `](#arg---rev) : The git revision - [`--subdir (-s) `](#arg---subdir) : The subdirectory of the git repository to use ## Update Options - [`--no-install`](#arg---no-install) : Don't modify the environment, only modify the lock-file - [`--frozen`](#arg---frozen) : Install the environment as defined in the lockfile, doesn't update lockfile if it isn't up-to-date with the manifest file ``` **env**: `PIXI_FROZEN` ``` - [`--locked`](#arg---locked) : Check if lockfile is up-to-date before installing the environment, aborts when lockfile isn't up-to-date with the manifest file ``` **env**: `PIXI_LOCKED` ``` ## Global Options - [`--manifest-path (-m) `](#arg---manifest-path) : The path to `pixi.toml`, `pyproject.toml`, or the workspace directory - [`--workspace (-w) `](#arg---workspace) : Name of the workspace ## Description Adds dependencies to the workspace The dependencies should be defined as MatchSpec for conda package, or a PyPI requirement for the `--pypi` dependencies. If no specific version is provided, the latest version compatible with your workspace will be chosen automatically or a * will be used. Example usage: - `pixi add python=3.9`: This will select the latest minor version that complies with 3.9.\*, i.e., python version 3.9.0, 3.9.1, 3.9.2, etc. - `pixi add python`: In absence of a specified version, the latest version will be chosen. For instance, this could resolve to python version 3.11.3.\* at the time of writing. Adding multiple dependencies at once is also supported: - `pixi add python pytest`: This will add both `python` and `pytest` to the workspace's dependencies. The `--platform` and `--build/--host` flags make the dependency target specific. - `pixi add python --platform linux-64 --platform osx-arm64`: Will add the latest version of python for linux-64 and osx-arm64 platforms. - `pixi add python --build`: Will add the latest version of python for as a build dependency. Mixing `--platform` and `--build`/`--host` flags is supported The `--pypi` option will add the package as a pypi dependency. This cannot be mixed with the conda dependencies - `pixi add --pypi boto3` - `pixi add --pypi "boto3==version"` If the workspace manifest is a `pyproject.toml`, adding a pypi dependency will add it to the native pyproject `project.dependencies` array or to the native `dependency-groups` table if a feature is specified: - `pixi add --pypi boto3` will add `boto3` to the `project.dependencies` array - `pixi add --pypi boto3 --feature aws` will add `boto3` to the `dependency-groups.aws` array - `pixi add --pypi --editable 'boto3 @ file://absolute/path/to/boto3'` will add the local editable `boto3` to the `pypi-dependencies` array Note that if `--platform` or `--editable` are specified, the pypi dependency will be added to the `tool.pixi.pypi-dependencies` table instead as native arrays have no support for platform-specific or editable dependencies. These dependencies will then be read by pixi as if they had been added to the pixi `pypi-dependencies` tables of the default or of a named feature. The versions will be automatically added with a pinning strategy based on semver or the pinning strategy set in the config. There is a list of packages that are not following the semver versioning scheme but will use the minor version by default: Python, Rust, Julia, GCC, GXX, GFortran, NodeJS, Deno, R, R-Base, Perl ## Examples ```shell pixi add numpy # (1)! pixi add numpy pandas "pytorch>=1.8" # (2)! pixi add "numpy>=1.22,<1.24" # (3)! pixi add --manifest-path ~/myworkspace/pixi.toml numpy # (4)! pixi add --host "python>=3.9.0" # (5)! pixi add --build cmake # (6)! pixi add --platform osx-64 clang # (7)! pixi add --no-install numpy # (8)! pixi add --no-lockfile-update numpy # (9)! pixi add --feature featurex numpy # (10)! pixi add --git https://github.com/wolfv/pixi-build-examples boost-check # (11)! pixi add --git https://github.com/wolfv/pixi-build-examples --branch main --subdir boost-check boost-check # (12)! pixi add --git https://github.com/wolfv/pixi-build-examples --tag v0.1.0 boost-check # (13)! pixi add --git https://github.com/wolfv/pixi-build-examples --rev e50d4a1 boost-check # (14)! # Add a pypi dependency pixi add --pypi requests[security] # (15)! pixi add --pypi Django==5.1rc1 # (16)! pixi add --pypi "boltons>=24.0.0" --feature lint # (17)! pixi add --pypi "boltons @ https://files.pythonhosted.org/packages/46/35/e50d4a115f93e2a3fbf52438435bb2efcf14c11d4fcd6bdcd77a6fc399c9/boltons-24.0.0-py3-none-any.whl" # (18)! pixi add --pypi "exchangelib @ git+https://github.com/ecederstrand/exchangelib" # (19)! pixi add --pypi "project @ file:///absolute/path/to/project" # (20)! pixi add --pypi "project@file:///absolute/path/to/project" --editable # (21)! pixi add --git https://github.com/mahmoud/boltons.git boltons --pypi # (22)! pixi add --git https://github.com/mahmoud/boltons.git boltons --branch main --pypi # (23)! pixi add --git https://github.com/mahmoud/boltons.git boltons --rev e50d4a1 --pypi # (24)! pixi add --git https://github.com/mahmoud/boltons.git boltons --tag v0.1.0 --pypi # (25)! pixi add --git https://github.com/mahmoud/boltons.git boltons --tag v0.1.0 --pypi --subdir boltons # (26)! ``` 1. This will add the `numpy` package to the project with the latest available for the solved environment. 1. This will add multiple packages to the project solving them all together. 1. This will add the `numpy` package with the version constraint. 1. This will add the `numpy` package to the project of the manifest file at the given path. 1. This will add the `python` package as a host dependency. There is currently no different behavior for host dependencies. 1. This will add the `cmake` package as a build dependency. There is currently no different behavior for build dependencies. 1. This will add the `clang` package only for the `osx-64` platform. 1. This will add the `numpy` package to the manifest and lockfile, without installing it in an environment. 1. This will add the `numpy` package to the manifest without updating the lockfile or installing it in the environment. 1. This will add the `numpy` package in the feature `featurex`. 1. This will add the `boost-check` source package to the dependencies from the git repository. 1. This will add the `boost-check` source package to the dependencies from the git repository using `main` branch and the `boost-check` folder in the repository. 1. This will add the `boost-check` source package to the dependencies from the git repository using `v0.1.0` tag. 1. This will add the `boost-check` source package to the dependencies from the git repository using `e50d4a1` revision. 1. This will add the `requests` package as `pypi` dependency with the `security` extra. 1. This will add the `pre-release` version of `Django` to the project as a `pypi` dependency. 1. This will add the `boltons` package in the feature `lint` as `pypi` dependency. 1. This will add the `boltons` package with the given `url` as `pypi` dependency. 1. This will add the `exchangelib` package with the given `git` url as `pypi` dependency. 1. This will add the `project` package with the given `file` url as `pypi` dependency. 1. This will add the `project` package with the given `file` url as an `editable` package as `pypi` dependency. 1. This will add the `boltons` package with the given `git` url as `pypi` dependency. 1. This will add the `boltons` package with the given `git` url and `main` branch as `pypi` dependency. 1. This will add the `boltons` package with the given `git` url and `e50d4a1` revision as `pypi` dependency. 1. This will add the `boltons` package with the given `git` url and `v0.1.0` tag as `pypi` dependency. 1. This will add the `boltons` package with the given `git` url, `v0.1.0` tag and the `boltons` folder in the repository as `pypi` dependency. Need to specify build strings or hardware-specific packages? For advanced package specifications including build strings, see the [Package Specifications](../../../../concepts/package_specifications/) guide. Examples (both syntaxes work): ```shell # Equals syntax (compact) pixi add "pytorch=*=*cuda*" pixi add "numpy=*=py311*" # Bracket syntax (explicit) pixi add "pytorch [build='*cuda*']" pixi add "numpy [build='py311*']" ``` Tip If you want to use a non default pinning strategy, you can set it using [pixi's configuration](../../../pixi_configuration/#pinning-strategy). ```text pixi config set pinning-strategy no-pin --global ``` The default is `semver` which will pin the dependencies to the latest major version or minor for `v0` versions. Note There is an exception to this rule when you add a package we defined as non `semver`, then we'll use the `minor` strategy. These are the packages we defined as non `semver`: Python, Rust, Julia, GCC, GXX, GFortran, NodeJS, Deno, R, R-Base, Perl # [pixi](../) auth Login to prefix.dev or anaconda.org servers to access private channels ## Usage ```text pixi auth ``` ## Subcommands | Command | Description | | ------------------- | -------------------------------------------------- | | [`login`](login/) | Store authentication information for a given host | | [`logout`](logout/) | Remove authentication information for a given host | # [pixi](../) build Build a conda package from a Pixi package. ## Usage ```text pixi build [OPTIONS] ``` ## Options - [`--target-platform (-t) `](#arg---target-platform) : The target platform to build for (defaults to the current platform) ``` **default**: `current_platform` ``` - [`--build-platform `](#arg---build-platform) : The build platform to use for building (defaults to the current platform) ``` **default**: `current_platform` ``` - [`--output-dir (-o) `](#arg---output-dir) : The output directory to place the built artifacts ``` **default**: `.` ``` - [`--build-dir (-b) `](#arg---build-dir) : The directory to use for incremental builds artifacts - [`--clean (-c)`](#arg---clean) : Whether to clean the build directory before building - [`--path `](#arg---path) : The path to a directory containing a package manifest, or to a specific manifest file ## Config Options - [`--auth-file `](#arg---auth-file) : Path to the file containing the authentication token - [`--concurrent-downloads `](#arg---concurrent-downloads) : Max concurrent network requests, default is `50` - [`--concurrent-solves `](#arg---concurrent-solves) : Max concurrent solves, default is the number of CPUs - [`--pinning-strategy `](#arg---pinning-strategy) : Set pinning strategy ``` **options**: `semver`, `minor`, `major`, `latest-up`, `exact-version`, `no-pin` ``` - [`--pypi-keyring-provider `](#arg---pypi-keyring-provider) : Specifies whether to use the keyring to look up credentials for PyPI ``` **options**: `disabled`, `subprocess` ``` - [`--run-post-link-scripts`](#arg---run-post-link-scripts) : Run post-link scripts (insecure) - [`--tls-no-verify`](#arg---tls-no-verify) : Do not verify the TLS certificate of the server - [`--tls-root-certs `](#arg---tls-root-certs) : Which TLS root certificates to use: 'webpki' (bundled Mozilla roots), 'native' (system store), or 'all' (both) ``` **env**: `PIXI_TLS_ROOT_CERTS` ``` - [`--use-environment-activation-cache`](#arg---use-environment-activation-cache) : Use environment activation cache (experimental) ## Update Options - [`--no-install`](#arg---no-install) : Don't modify the environment, only modify the lock-file - [`--frozen`](#arg---frozen) : Install the environment as defined in the lockfile, doesn't update lockfile if it isn't up-to-date with the manifest file ``` **env**: `PIXI_FROZEN` ``` - [`--locked`](#arg---locked) : Check if lockfile is up-to-date before installing the environment, aborts when lockfile isn't up-to-date with the manifest file ``` **env**: `PIXI_LOCKED` ``` - [`--as-is`](#arg---as-is) : Shorthand for the combination of --no-install and --frozen # [pixi](../) clean Cleanup the environments ## Usage ```text pixi clean [OPTIONS] [COMMAND] ``` ## Subcommands | Command | Description | | ----------------- | -------------------------------------------------------- | | [`cache`](cache/) | Clean the cache of your system which are touched by pixi | ## Options - [`--environment (-e) `](#arg---environment) : The environment directory to remove - [`--activation-cache`](#arg---activation-cache) : Only remove the activation cache - [`--build`](#arg---build) : Only remove the pixi-build cache - [`--workspaces-registry`](#arg---workspaces-registry) : Only remove disassociated workspace registries ## Global Options - [`--manifest-path (-m) `](#arg---manifest-path) : The path to `pixi.toml`, `pyproject.toml`, or the workspace directory - [`--workspace (-w) `](#arg---workspace) : Name of the workspace ## Description Cleanup the environments. This command removes the information in the .pixi folder. You can specify the environment to remove with the `--environment` flag. Use the `cache` subcommand to clean the cache. # [pixi](../) completion Generates a completion script for a shell ## Usage ```text pixi completion --shell ``` ## Options - [`--shell (-s) `](#arg---shell) : The shell to generate a completion script for ``` **required**: `true` **options**: `bash`, `elvish`, `fish`, `nushell`, `powershell`, `zsh` ``` # [pixi](../) config Configuration management ## Usage ```text pixi config ``` ## Subcommands | Command | Description | | --------------------- | ------------------------------------------- | | [`edit`](edit/) | Edit the configuration file | | [`list`](list/) | List configuration values | | [`prepend`](prepend/) | Prepend a value to a list configuration key | | [`append`](append/) | Append a value to a list configuration key | | [`set`](set/) | Set a configuration value | | [`unset`](unset/) | Unset a configuration value | # [pixi](../) exec Run a command and install it in a temporary environment ## Usage ```text pixi exec [OPTIONS] [COMMAND]... ``` ## Arguments - [``](#arg-%3CCOMMAND%3E) : The executable to run, followed by any arguments ``` May be provided more than once. ``` ## Options - [`--spec (-s) `](#arg---spec) : Matchspecs of package to install. If this is not provided, the package is guessed from the command ``` May be provided more than once. ``` - [`--with (-w) `](#arg---with) : Matchspecs of package to install, while also guessing a package from the command ``` May be provided more than once. ``` - [`--channel (-c) `](#arg---channel) : The channels to consider as a name or a url. Multiple channels can be specified by using this field multiple times ``` May be provided more than once. ``` - [`--platform (-p) `](#arg---platform) : The platform to create the environment for ``` **default**: `current_platform` ``` - [`--force-reinstall`](#arg---force-reinstall) : If specified a new environment is always created even if one already exists - [`--list=`](#arg---list) : Before executing the command, list packages in the environment Specify `--list=some_regex` to filter the shown packages - [`--no-modify-ps1`](#arg---no-modify-ps1) : Disable modification of the PS1 prompt to indicate the temporary environment ## Config Options - [`--auth-file `](#arg---auth-file) : Path to the file containing the authentication token - [`--concurrent-downloads `](#arg---concurrent-downloads) : Max concurrent network requests, default is `50` - [`--concurrent-solves `](#arg---concurrent-solves) : Max concurrent solves, default is the number of CPUs - [`--pinning-strategy `](#arg---pinning-strategy) : Set pinning strategy ``` **options**: `semver`, `minor`, `major`, `latest-up`, `exact-version`, `no-pin` ``` - [`--pypi-keyring-provider `](#arg---pypi-keyring-provider) : Specifies whether to use the keyring to look up credentials for PyPI ``` **options**: `disabled`, `subprocess` ``` - [`--run-post-link-scripts`](#arg---run-post-link-scripts) : Run post-link scripts (insecure) - [`--tls-no-verify`](#arg---tls-no-verify) : Do not verify the TLS certificate of the server - [`--tls-root-certs `](#arg---tls-root-certs) : Which TLS root certificates to use: 'webpki' (bundled Mozilla roots), 'native' (system store), or 'all' (both) ``` **env**: `PIXI_TLS_ROOT_CERTS` ``` - [`--use-environment-activation-cache`](#arg---use-environment-activation-cache) : Use environment activation cache (experimental) ## Description Run a command and install it in a temporary environment. Remove the temporary environments with `pixi clean cache --exec`. ## Examples ```shell pixi exec python # Run ipython and include the py-rattler and numpy packages in the environment pixi exec --with py-rattler --with numpy ipython # Specify the specs of the environment pixi exec --spec python=3.9 --spec numpy python # Install a specific conda package to temporary environment pixi exec --spec "$(pwd)/numpy-2.3.4-py314h2b28147_0.conda" -- python pixi exec --spec https://prefix.dev/conda-forge/noarch/polars-1.35.1-pyh6a1acc5_0.conda -- python # Force reinstall to recreate the environment and get the latest package versions pixi exec --force-reinstall --with py-rattler ipython ``` # [pixi](../) global Subcommand for global package management actions All commands in this section are used to manage global installations of packages and environments through the global manifest. More info on the global manifest can be found [here](../../../../global_tools/introduction/). Tip Binaries and environments installed globally are stored in `~/.pixi` by default, this can be changed by setting the `PIXI_HOME` environment variable. ## Usage ```text pixi global ``` ## Subcommands | Command | Description | | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [`add`](add/) | Adds dependencies to an environment | | [`edit`](edit/) | Edit the global manifest file | | [`install`](install/) | Installs the defined packages in a globally accessible location and exposes their command line applications. | | [`uninstall`](uninstall/) | Uninstalls environments from the global environment. | | [`remove`](remove/) | Removes dependencies from an environment | | [`list`](list/) | Lists global environments with their dependencies and exposed commands. Can also display all packages within a specific global environment when using the --environment flag. | | [`sync`](sync/) | Sync global manifest with installed environments | | [`expose`](expose/) | Interact with the exposure of binaries in the global environment | | [`shortcut`](shortcut/) | Interact with the shortcuts on your machine | | [`update`](update/) | Updates environments in the global environment | | [`tree`](tree/) | Show a tree of dependencies for a specific global environment | ## Description Subcommand for global package management actions. Install packages on the user level. Into to the \[`$PIXI_HOME`\] directory, which defaults to `~/.pixi`. # [pixi](../) import Imports a file into an environment in an existing workspace. ## Usage ```text pixi import [OPTIONS] ``` ## Arguments - [``](#arg-%3CFILE%3E) : File to import into the workspace ``` **required**: `true` ``` ## Options - [`--format `](#arg---format) : Which format to interpret the file as ``` **options**: `conda-env`, `pypi-txt` ``` - [`--platform (-p) `](#arg---platform) : The platforms for the imported environment ``` May be provided more than once. ``` - [`--environment (-e) `](#arg---environment) : A name for the created environment - [`--feature (-f) `](#arg---feature) : A name for the created feature ## Config Options - [`--auth-file `](#arg---auth-file) : Path to the file containing the authentication token - [`--concurrent-downloads `](#arg---concurrent-downloads) : Max concurrent network requests, default is `50` - [`--concurrent-solves `](#arg---concurrent-solves) : Max concurrent solves, default is the number of CPUs - [`--pinning-strategy `](#arg---pinning-strategy) : Set pinning strategy ``` **options**: `semver`, `minor`, `major`, `latest-up`, `exact-version`, `no-pin` ``` - [`--pypi-keyring-provider `](#arg---pypi-keyring-provider) : Specifies whether to use the keyring to look up credentials for PyPI ``` **options**: `disabled`, `subprocess` ``` - [`--run-post-link-scripts`](#arg---run-post-link-scripts) : Run post-link scripts (insecure) - [`--tls-no-verify`](#arg---tls-no-verify) : Do not verify the TLS certificate of the server - [`--tls-root-certs `](#arg---tls-root-certs) : Which TLS root certificates to use: 'webpki' (bundled Mozilla roots), 'native' (system store), or 'all' (both) ``` **env**: `PIXI_TLS_ROOT_CERTS` ``` - [`--use-environment-activation-cache`](#arg---use-environment-activation-cache) : Use environment activation cache (experimental) ## Global Options - [`--manifest-path (-m) `](#arg---manifest-path) : The path to `pixi.toml`, `pyproject.toml`, or the workspace directory - [`--workspace (-w) `](#arg---workspace) : Name of the workspace ## Description Imports a file into an environment in an existing workspace. If `--format` isn't provided, `import` will try each format in turn # [pixi](../) info Information about the system, workspace and environments for the current machine More information [here](../../../../advanced/explain_info_command/). ## Usage ```text pixi info [OPTIONS] ``` ## Options - [`--extended`](#arg---extended) : Show cache and environment size - [`--json`](#arg---json) : Whether to show the output as JSON or not ## Global Options - [`--manifest-path (-m) `](#arg---manifest-path) : The path to `pixi.toml`, `pyproject.toml`, or the workspace directory - [`--workspace (-w) `](#arg---workspace) : Name of the workspace ## Examples ```shell pixi info pixi info --json pixi info --extended ``` # [pixi](../) init Creates a new workspace Importing an environment.yml When importing an environment, the `pixi.toml` will be created with the dependencies from the environment file. The `pixi.lock` will be created when you install the environment. We don't support `git+` urls as dependencies for pip packages and for the `defaults` channel we use `main`, `r` and `msys2` as the default channels. ## Usage ```text pixi init [OPTIONS] [PATH] ``` ## Arguments - [``](#arg-%3CPATH%3E) : Where to place the workspace (defaults to current path) ``` **default**: `.` ``` ## Options - [`--channel (-c) `](#arg---channel) : Channel to use in the workspace ``` May be provided more than once. ``` - [`--platform (-p) `](#arg---platform) : Platforms that the workspace supports ``` May be provided more than once. ``` - [`--import (-i) `](#arg---import) : Environment.yml file to bootstrap the workspace - [`--format `](#arg---format) : The manifest format to create ``` **options**: `pixi`, `pyproject`, `mojoproject` ``` - [`--scm (-s) `](#arg---scm) : Source Control Management used for this workspace ``` **options**: `github`, `gitlab`, `codeberg` ``` - [`--conda-pypi-map `](#arg---conda-pypi-map) : Set a mapping between conda channels and pypi channels ``` May be provided more than once. ``` ## Description Creates a new workspace This command is used to create a new workspace. It prepares a manifest and some helpers for the user to start working. As pixi can both work with `pixi.toml` and `pyproject.toml` files, the user can choose which one to use with `--format`. You can import an existing conda environment file with the `--import` flag. ## Examples ```shell pixi init myproject # (1)! pixi init ~/myproject # (2)! pixi init # (3)! pixi init --channel conda-forge --channel bioconda myproject # (4)! pixi init --platform osx-64 --platform linux-64 myproject # (5)! pixi init --import environment.yml # (6)! pixi init --format pyproject # (7)! pixi init --format pixi --scm gitlab # (8)! ``` 1. Initializes a new project in the `myproject` directory, relative to the current directory. 1. Initializes a new project in the `~/myproject` directory, absolute path. 1. Initializes a new project in the current directory. 1. Initializes a new project with the specified channels. 1. Initializes a new project with the specified platforms. 1. Initializes a new project with the `dependencies` and `channels` from the `environment.yml` file. 1. Initializes a new project with the `pyproject.toml` format. 1. Initializes a new project with the `pixi.toml` format and the `gitlab` SCM. # [pixi](../) install Install an environment, both updating the lockfile and installing the environment ## Usage ```text pixi install [OPTIONS] ``` ## Options - [`--environment (-e) `](#arg---environment) : The environment to install ``` May be provided more than once. ``` - [`--all (-a)`](#arg---all) : Install all environments - [`--skip `](#arg---skip) : Skip installation of specific packages present in the lockfile. This uses a soft exclusion: the package will be skipped but its dependencies are installed ``` May be provided more than once. ``` - [`--skip-with-deps `](#arg---skip-with-deps) : Skip a package and its entire dependency subtree. This performs a hard exclusion: the package and its dependencies are not installed unless reachable from another non-skipped root ``` May be provided more than once. ``` - [`--only `](#arg---only) : Install and build only these package(s) and their dependencies. Can be passed multiple times ``` May be provided more than once. ``` ## Config Options - [`--auth-file `](#arg---auth-file) : Path to the file containing the authentication token - [`--concurrent-downloads `](#arg---concurrent-downloads) : Max concurrent network requests, default is `50` - [`--concurrent-solves `](#arg---concurrent-solves) : Max concurrent solves, default is the number of CPUs - [`--pinning-strategy `](#arg---pinning-strategy) : Set pinning strategy ``` **options**: `semver`, `minor`, `major`, `latest-up`, `exact-version`, `no-pin` ``` - [`--pypi-keyring-provider `](#arg---pypi-keyring-provider) : Specifies whether to use the keyring to look up credentials for PyPI ``` **options**: `disabled`, `subprocess` ``` - [`--run-post-link-scripts`](#arg---run-post-link-scripts) : Run post-link scripts (insecure) - [`--tls-no-verify`](#arg---tls-no-verify) : Do not verify the TLS certificate of the server - [`--tls-root-certs `](#arg---tls-root-certs) : Which TLS root certificates to use: 'webpki' (bundled Mozilla roots), 'native' (system store), or 'all' (both) ``` **env**: `PIXI_TLS_ROOT_CERTS` ``` - [`--use-environment-activation-cache`](#arg---use-environment-activation-cache) : Use environment activation cache (experimental) ## Update Options - [`--frozen`](#arg---frozen) : Install the environment as defined in the lockfile, doesn't update lockfile if it isn't up-to-date with the manifest file ``` **env**: `PIXI_FROZEN` ``` - [`--locked`](#arg---locked) : Check if lockfile is up-to-date before installing the environment, aborts when lockfile isn't up-to-date with the manifest file ``` **env**: `PIXI_LOCKED` ``` ## Global Options - [`--manifest-path (-m) `](#arg---manifest-path) : The path to `pixi.toml`, `pyproject.toml`, or the workspace directory - [`--workspace (-w) `](#arg---workspace) : Name of the workspace ## Description Install an environment, both updating the lockfile and installing the environment. This command installs an environment, if the lockfile is not up-to-date it will be updated. `pixi install` only installs one environment at a time, if you have multiple environments you can select the right one with the `--environment` flag. If you don't provide an environment, the `default` environment will be installed. If you want to install all environments, you can use the `--all` flag. Running `pixi install` is not required before running other commands like `pixi run` or `pixi shell`. These commands will automatically install the environment if it is not already installed. You can use `pixi reinstall` to reinstall all environments, one environment or just some packages of an environment. ## Examples ```shell pixi install # (1)! pixi install --manifest-path ~/myworkspace/pixi.toml # (2)! pixi install --frozen # (3)! pixi install --locked # (4)! pixi install --environment lint # (5)! pixi install -e lint # (5)! ``` 1. This will install the default environment. 1. This will install the default environment from the manifest file at the given path. 1. This will install the environment from the lockfile without updating the lockfile. 1. This will install the environment from the lockfile without updating the lockfile and ensuring the environment is locked correctly. 1. This will install the `lint` environment. # [pixi](../) list List the packages of the current workspace ## Usage ```text pixi list [OPTIONS] [REGEX] ``` ## Arguments - [``](#arg-%3CREGEX%3E) : List only packages matching a regular expression ## Options - [`--platform `](#arg---platform) : The platform to list packages for. Defaults to the current platform - [`--json`](#arg---json) : Whether to output in json format - [`--sort-by `](#arg---sort-by) : Sorting strategy ``` **default**: `name` **options**: `size`, `name`, `kind` ``` - [`--fields `](#arg---fields) : Select which fields to display and in what order (comma-separated) ``` May be provided more than once. **default**: `name, version, build, size, kind, source` **options**: `arch`, `build`, `build-number`, `constrains`, `depends`, `file-name`, `is-editable`, `kind`, `license`, `license-family`, `md5`, `name`, `noarch`, `platform`, `requested-spec`, `sha256`, `size`, `source`, `subdir`, `timestamp`, `track-features`, `url`, `version` ``` - [`--environment (-e) `](#arg---environment) : The environment to list packages for. Defaults to the default environment - [`--explicit (-x)`](#arg---explicit) : Only list packages that are explicitly defined in the workspace ## Update Options - [`--frozen`](#arg---frozen) : Install the environment as defined in the lockfile, doesn't update lockfile if it isn't up-to-date with the manifest file ``` **env**: `PIXI_FROZEN` ``` - [`--locked`](#arg---locked) : Check if lockfile is up-to-date before installing the environment, aborts when lockfile isn't up-to-date with the manifest file ``` **env**: `PIXI_LOCKED` ``` - [`--no-install`](#arg---no-install) : Don't modify the environment, only modify the lock-file ## Global Options - [`--manifest-path (-m) `](#arg---manifest-path) : The path to `pixi.toml`, `pyproject.toml`, or the workspace directory - [`--workspace (-w) `](#arg---workspace) : Name of the workspace ## Description List the packages of the current workspace Highlighted packages are explicit dependencies. ## Examples ```shell pixi list pixi list py pixi list --json-pretty pixi list --explicit pixi list --sort-by size pixi list --platform win-64 pixi list --environment cuda pixi list --frozen pixi list --locked pixi list --no-install ``` Output will look like this, where `python` will be green as it is the package that was explicitly added to the [manifest file](../../../pixi_manifest/): ```shell ➜ pixi list Package Version Build Size Kind Source _libgcc_mutex 0.1 conda_forge 2.5 KiB conda _libgcc_mutex-0.1-conda_forge.tar.bz2 _openmp_mutex 4.5 2_gnu 23.1 KiB conda _openmp_mutex-4.5-2_gnu.tar.bz2 bzip2 1.0.8 hd590300_5 248.3 KiB conda bzip2-1.0.8-hd590300_5.conda ca-certificates 2023.11.17 hbcca054_0 150.5 KiB conda ca-certificates-2023.11.17-hbcca054_0.conda ld_impl_linux-64 2.40 h41732ed_0 688.2 KiB conda ld_impl_linux-64-2.40-h41732ed_0.conda libexpat 2.5.0 hcb278e6_1 76.2 KiB conda libexpat-2.5.0-hcb278e6_1.conda libffi 3.4.2 h7f98852_5 56.9 KiB conda libffi-3.4.2-h7f98852_5.tar.bz2 libgcc-ng 13.2.0 h807b86a_4 755.7 KiB conda libgcc-ng-13.2.0-h807b86a_4.conda libgomp 13.2.0 h807b86a_4 412.2 KiB conda libgomp-13.2.0-h807b86a_4.conda libnsl 2.0.1 hd590300_0 32.6 KiB conda libnsl-2.0.1-hd590300_0.conda libsqlite 3.44.2 h2797004_0 826 KiB conda libsqlite-3.44.2-h2797004_0.conda libuuid 2.38.1 h0b41bf4_0 32.8 KiB conda libuuid-2.38.1-h0b41bf4_0.conda libxcrypt 4.4.36 hd590300_1 98 KiB conda libxcrypt-4.4.36-hd590300_1.conda libzlib 1.2.13 hd590300_5 60.1 KiB conda libzlib-1.2.13-hd590300_5.conda ncurses 6.4 h59595ed_2 863.7 KiB conda ncurses-6.4-h59595ed_2.conda openssl 3.2.0 hd590300_1 2.7 MiB conda openssl-3.2.0-hd590300_1.conda python 3.12.1 hab00c5b_1_cpython 30.8 MiB conda python-3.12.1-hab00c5b_1_cpython.conda readline 8.2 h8228510_1 274.9 KiB conda readline-8.2-h8228510_1.conda tk 8.6.13 noxft_h4845f30_101 3.2 MiB conda tk-8.6.13-noxft_h4845f30_101.conda tzdata 2023d h0c530f3_0 116.8 KiB conda tzdata-2023d-h0c530f3_0.conda xz 5.2.6 h166bdaf_0 408.6 KiB conda xz-5.2.6-h166bdaf_0.tar.bz2 ``` # [pixi](../) lock Solve environment and update the lock file without installing the environments ## Usage ```text pixi lock [OPTIONS] ``` ## Options - [`--json`](#arg---json) : Output the changes in JSON format - [`--check`](#arg---check) : Check if any changes have been made to the lock file. If yes, exit with a non-zero code - [`--dry-run`](#arg---dry-run) : Compute the lock file without writing to disk. Implies --no-install ## Update Options - [`--no-install`](#arg---no-install) : Don't modify the environment, only modify the lock-file ## Global Options - [`--manifest-path (-m) `](#arg---manifest-path) : The path to `pixi.toml`, `pyproject.toml`, or the workspace directory - [`--workspace (-w) `](#arg---workspace) : Name of the workspace ## Examples ```shell pixi lock pixi lock --manifest-path ~/myworkspace/pixi.toml pixi lock --json pixi lock --check ``` # [pixi](../) reinstall Re-install an environment, both updating the lockfile and re-installing the environment ## Usage ```text pixi reinstall [OPTIONS] [PACKAGE]... ``` ## Arguments - [``](#arg-%3CPACKAGE%3E) : Specifies the package that should be reinstalled. If no package is given, the whole environment will be reinstalled ``` May be provided more than once. ``` ## Options - [`--environment (-e) `](#arg---environment) : The environment to install ``` May be provided more than once. ``` - [`--all (-a)`](#arg---all) : Install all environments ## Config Options - [`--auth-file `](#arg---auth-file) : Path to the file containing the authentication token - [`--concurrent-downloads `](#arg---concurrent-downloads) : Max concurrent network requests, default is `50` - [`--concurrent-solves `](#arg---concurrent-solves) : Max concurrent solves, default is the number of CPUs - [`--pinning-strategy `](#arg---pinning-strategy) : Set pinning strategy ``` **options**: `semver`, `minor`, `major`, `latest-up`, `exact-version`, `no-pin` ``` - [`--pypi-keyring-provider `](#arg---pypi-keyring-provider) : Specifies whether to use the keyring to look up credentials for PyPI ``` **options**: `disabled`, `subprocess` ``` - [`--run-post-link-scripts`](#arg---run-post-link-scripts) : Run post-link scripts (insecure) - [`--tls-no-verify`](#arg---tls-no-verify) : Do not verify the TLS certificate of the server - [`--tls-root-certs `](#arg---tls-root-certs) : Which TLS root certificates to use: 'webpki' (bundled Mozilla roots), 'native' (system store), or 'all' (both) ``` **env**: `PIXI_TLS_ROOT_CERTS` ``` - [`--use-environment-activation-cache`](#arg---use-environment-activation-cache) : Use environment activation cache (experimental) ## Update Options - [`--frozen`](#arg---frozen) : Install the environment as defined in the lockfile, doesn't update lockfile if it isn't up-to-date with the manifest file ``` **env**: `PIXI_FROZEN` ``` - [`--locked`](#arg---locked) : Check if lockfile is up-to-date before installing the environment, aborts when lockfile isn't up-to-date with the manifest file ``` **env**: `PIXI_LOCKED` ``` ## Global Options - [`--manifest-path (-m) `](#arg---manifest-path) : The path to `pixi.toml`, `pyproject.toml`, or the workspace directory - [`--workspace (-w) `](#arg---workspace) : Name of the workspace ## Description Re-install an environment, both updating the lockfile and re-installing the environment. This command reinstalls an environment, if the lockfile is not up-to-date it will be updated. If packages are specified, only those packages will be reinstalled. Otherwise the whole environment will be reinstalled. `pixi reinstall` only re-installs one environment at a time, if you have multiple environments you can select the right one with the `--environment` flag. If you don't provide an environment, the `default` environment will be re-installed. If you want to re-install all environments, you can use the `--all` flag. # [pixi](../) remove Removes dependencies from the workspace If the project manifest is a `pyproject.toml`, removing a pypi dependency with the `--pypi` flag will remove it from either - the native pyproject `project.dependencies` array or the native `project.optional-dependencies` table (if a feature is specified) - pixi `pypi-dependencies` tables of the default or a named feature (if a feature is specified) ## Usage ```text pixi remove [OPTIONS] ... ``` ## Arguments - [``](#arg-%3CSPEC%3E) : The dependency as names, conda MatchSpecs or PyPi requirements ``` May be provided more than once. **required**: `true` ``` ## Options - [`--pypi`](#arg---pypi) : The specified dependencies are pypi dependencies. Conflicts with `host` and `build` - [`--platform (-p) `](#arg---platform) : The platform for which the dependency should be modified ``` May be provided more than once. ``` - [`--feature (-f) `](#arg---feature) : The feature for which the dependency should be modified ``` **default**: `default` ``` ## Config Options - [`--auth-file `](#arg---auth-file) : Path to the file containing the authentication token - [`--concurrent-downloads `](#arg---concurrent-downloads) : Max concurrent network requests, default is `50` - [`--concurrent-solves `](#arg---concurrent-solves) : Max concurrent solves, default is the number of CPUs - [`--pinning-strategy `](#arg---pinning-strategy) : Set pinning strategy ``` **options**: `semver`, `minor`, `major`, `latest-up`, `exact-version`, `no-pin` ``` - [`--pypi-keyring-provider `](#arg---pypi-keyring-provider) : Specifies whether to use the keyring to look up credentials for PyPI ``` **options**: `disabled`, `subprocess` ``` - [`--run-post-link-scripts`](#arg---run-post-link-scripts) : Run post-link scripts (insecure) - [`--tls-no-verify`](#arg---tls-no-verify) : Do not verify the TLS certificate of the server - [`--tls-root-certs `](#arg---tls-root-certs) : Which TLS root certificates to use: 'webpki' (bundled Mozilla roots), 'native' (system store), or 'all' (both) ``` **env**: `PIXI_TLS_ROOT_CERTS` ``` - [`--use-environment-activation-cache`](#arg---use-environment-activation-cache) : Use environment activation cache (experimental) ## Git Options - [`--git (-g) `](#arg---git) : The git url to use when adding a git dependency - [`--branch `](#arg---branch) : The git branch - [`--tag `](#arg---tag) : The git tag - [`--rev `](#arg---rev) : The git revision - [`--subdir (-s) `](#arg---subdir) : The subdirectory of the git repository to use ## Update Options - [`--no-install`](#arg---no-install) : Don't modify the environment, only modify the lock-file - [`--frozen`](#arg---frozen) : Install the environment as defined in the lockfile, doesn't update lockfile if it isn't up-to-date with the manifest file ``` **env**: `PIXI_FROZEN` ``` - [`--locked`](#arg---locked) : Check if lockfile is up-to-date before installing the environment, aborts when lockfile isn't up-to-date with the manifest file ``` **env**: `PIXI_LOCKED` ``` ## Global Options - [`--manifest-path (-m) `](#arg---manifest-path) : The path to `pixi.toml`, `pyproject.toml`, or the workspace directory - [`--workspace (-w) `](#arg---workspace) : Name of the workspace ## Description Removes dependencies from the workspace. If the workspace manifest is a `pyproject.toml`, removing a pypi dependency with the `--pypi` flag will remove it from either - the native pyproject `project.dependencies` array or, if a feature is specified, the native `project.optional-dependencies` table - pixi `pypi-dependencies` tables of the default feature or, if a feature is specified, a named feature ## Examples ```shell pixi remove numpy pixi remove numpy pandas pytorch pixi remove --manifest-path ~/myworkspace/pixi.toml numpy pixi remove --host python pixi remove --build cmake pixi remove --pypi requests pixi remove --platform osx-64 --build clang pixi remove --feature featurex clang pixi remove --feature featurex --platform osx-64 clang pixi remove --feature featurex --platform osx-64 --build clang pixi remove --no-install numpy ``` # [pixi](../) run Runs task in the pixi environment ## Usage ```text pixi run [OPTIONS] [TASK]... ``` ## Arguments - [``](#arg-%3CTASK%3E) : The pixi task or a task shell command you want to run in the workspace's environment, which can be an executable in the environment's PATH ``` May be provided more than once. ``` ## Options - [`--executable (-x)`](#arg---executable) : Execute the command as an executable without resolving Pixi tasks - [`--environment (-e) `](#arg---environment) : The environment to run the task in - [`--clean-env`](#arg---clean-env) : Use a clean environment to run the task - [`--skip-deps`](#arg---skip-deps) : Don't run the dependencies of the task ('depends-on' field in the task definition) - [`--templated`](#arg---templated) : Enable template rendering for the command arguments - [`--dry-run (-n)`](#arg---dry-run) : Run the task in dry-run mode (only print the command that would run) - [`--help`](#arg---help) : ## Config Options - [`--auth-file `](#arg---auth-file) : Path to the file containing the authentication token - [`--concurrent-downloads `](#arg---concurrent-downloads) : Max concurrent network requests, default is `50` - [`--concurrent-solves `](#arg---concurrent-solves) : Max concurrent solves, default is the number of CPUs - [`--pinning-strategy `](#arg---pinning-strategy) : Set pinning strategy ``` **options**: `semver`, `minor`, `major`, `latest-up`, `exact-version`, `no-pin` ``` - [`--pypi-keyring-provider `](#arg---pypi-keyring-provider) : Specifies whether to use the keyring to look up credentials for PyPI ``` **options**: `disabled`, `subprocess` ``` - [`--run-post-link-scripts`](#arg---run-post-link-scripts) : Run post-link scripts (insecure) - [`--tls-no-verify`](#arg---tls-no-verify) : Do not verify the TLS certificate of the server - [`--tls-root-certs `](#arg---tls-root-certs) : Which TLS root certificates to use: 'webpki' (bundled Mozilla roots), 'native' (system store), or 'all' (both) ``` **env**: `PIXI_TLS_ROOT_CERTS` ``` - [`--use-environment-activation-cache`](#arg---use-environment-activation-cache) : Use environment activation cache (experimental) - [`--force-activate`](#arg---force-activate) : Do not use the environment activation cache. (default: true except in experimental mode) - [`--no-completions`](#arg---no-completions) : Do not source the autocompletion scripts from the environment ## Update Options - [`--no-install`](#arg---no-install) : Don't modify the environment, only modify the lock-file - [`--frozen`](#arg---frozen) : Install the environment as defined in the lockfile, doesn't update lockfile if it isn't up-to-date with the manifest file ``` **env**: `PIXI_FROZEN` ``` - [`--locked`](#arg---locked) : Check if lockfile is up-to-date before installing the environment, aborts when lockfile isn't up-to-date with the manifest file ``` **env**: `PIXI_LOCKED` ``` - [`--as-is`](#arg---as-is) : Shorthand for the combination of --no-install and --frozen ## Global Options - [`--manifest-path (-m) `](#arg---manifest-path) : The path to `pixi.toml`, `pyproject.toml`, or the workspace directory - [`--workspace (-w) `](#arg---workspace) : Name of the workspace ## Description Runs task in the pixi environment. This command is used to run tasks in the pixi environment. It will activate the environment and run the task in the environment. It is using the deno_task_shell to run the task. `pixi run` will also update the lockfile and install the environment if it is required. ## Examples ```shell pixi run python pixi run cowpy "Hey pixi user" pixi run --manifest-path ~/myworkspace/pixi.toml python pixi run --frozen python pixi run --locked python # If you have specified a custom task in the pixi.toml you can run it with run as well pixi run build # Extra arguments will be passed to the tasks command. pixi run task argument1 argument2 # Use `--` to pass extra arguments directly to the underlying command, # even when the task defines typed `args`. pixi run task typed-arg-value -- --extra-flag --other=value # Skip dependencies of the task pixi run --skip-deps task # Run in dry-run mode to see the commands that would be run pixi run --dry-run task # If you have multiple environments you can select the right one with the --environment flag. pixi run --environment cuda python # THIS DOESN'T WORK ON WINDOWS # If you want to run a command in a clean environment you can use the --clean-env flag. # The PATH should only contain the pixi environment here. pixi run --clean-env "echo \$PATH" # By default, CLI commands are not processed by the template engine. # Use --templated to enable template rendering for ad-hoc commands. pixi run --templated echo '{{ pixi.platform }}' ``` ## Notes Info In `pixi` the [`deno_task_shell`](https://deno.land/manual@v1.35.0/tools/task_runner#task-runner) is the underlying runner of the run command. Checkout their [documentation](https://deno.land/manual@v1.35.0/tools/task_runner#task-runner) for the syntax and available commands. This is done so that the run commands can be run across all platforms. Cross environment tasks If you're using the `depends-on` feature of the `tasks`, the tasks will be run in the order you specified them. The `depends-on` can be used cross environment, e.g. you have this `pixi.toml`: pixi.toml ```toml [tasks] start = { cmd = "python start.py", depends-on = ["build"] } [feature.build.tasks] build = "cargo build" [feature.build.dependencies] rust = ">=1.74" [environments] build = ["build"] ``` Then you're able to run the `build` from the `build` environment and `start` from the default environment. By only calling: ```shell pixi run start ``` # [pixi](../) search Search a conda package ## Usage ```text pixi search [OPTIONS] ``` ## Arguments - [``](#arg-%3CPACKAGE%3E) : MatchSpec of a package to search ``` **required**: `true` ``` ## Options - [`--channel (-c) `](#arg---channel) : The channels to consider as a name or a url. Multiple channels can be specified by using this field multiple times ``` May be provided more than once. ``` - [`--platform (-p) `](#arg---platform) : The platform(s) to search for. By default, searches all platforms from the manifest (or all known platforms if no manifest is found) - [`--limit (-l) `](#arg---limit) : Limit the number of versions shown per package, -1 for no limit ``` **default**: `5` ``` - [`--limit-packages (-n) `](#arg---limit-packages) : Limit the number of packages shown, -1 for no limit ``` **default**: `5` ``` - [`--json`](#arg---json) : Output in JSON format ## Global Options - [`--manifest-path (-m) `](#arg---manifest-path) : The path to `pixi.toml`, `pyproject.toml`, or the workspace directory - [`--workspace (-w) `](#arg---workspace) : Name of the workspace ## Description Search a conda package Its output will list the latest version of package. ## Examples ```shell pixi search pixi pixi search --limit 30 "py*" # search in a different channel and for a specific platform pixi search -c robostack --platform linux-64 "*plotjuggler*" # search for a specific version of a package pixi search "rattler-build<=0.35.4" pixi search "rattler-build[build_number=h2d22210_0]" --platform linux-64 ``` # [pixi](../) self-update Update pixi to the latest version or a specific version ## Usage ```text pixi self-update [OPTIONS] ``` ## Options - [`--version `](#arg---version) : The desired version (to downgrade or upgrade to) - [`--dry-run`](#arg---dry-run) : Only show release notes, do not modify the binary - [`--force`](#arg---force) : Force download the desired version when not exactly same with the current. If no desired version, always replace with the latest version ``` **default**: `false` ``` - [`--no-release-note`](#arg---no-release-note) : Skip printing the release notes ``` **default**: `false` ``` ## Examples ```shell pixi self-update pixi self-update --version 0.46.0 ``` # [pixi](../) shell-hook Print the pixi environment activation script ## Usage ```text pixi shell-hook [OPTIONS] ``` ## Options - [`--shell (-s) `](#arg---shell) : Sets the shell, options: \[`bash`, `zsh`, `xonsh`, `cmd`, `powershell`, `fish`, `nushell`\] - [`--environment (-e) `](#arg---environment) : The environment to activate in the script - [`--json`](#arg---json) : Emit the environment variables set by running the activation as JSON ``` **default**: `false` ``` ## Config Options - [`--auth-file `](#arg---auth-file) : Path to the file containing the authentication token - [`--concurrent-downloads `](#arg---concurrent-downloads) : Max concurrent network requests, default is `50` - [`--concurrent-solves `](#arg---concurrent-solves) : Max concurrent solves, default is the number of CPUs - [`--pinning-strategy `](#arg---pinning-strategy) : Set pinning strategy ``` **options**: `semver`, `minor`, `major`, `latest-up`, `exact-version`, `no-pin` ``` - [`--pypi-keyring-provider `](#arg---pypi-keyring-provider) : Specifies whether to use the keyring to look up credentials for PyPI ``` **options**: `disabled`, `subprocess` ``` - [`--run-post-link-scripts`](#arg---run-post-link-scripts) : Run post-link scripts (insecure) - [`--tls-no-verify`](#arg---tls-no-verify) : Do not verify the TLS certificate of the server - [`--tls-root-certs `](#arg---tls-root-certs) : Which TLS root certificates to use: 'webpki' (bundled Mozilla roots), 'native' (system store), or 'all' (both) ``` **env**: `PIXI_TLS_ROOT_CERTS` ``` - [`--use-environment-activation-cache`](#arg---use-environment-activation-cache) : Use environment activation cache (experimental) - [`--force-activate`](#arg---force-activate) : Do not use the environment activation cache. (default: true except in experimental mode) - [`--no-completions`](#arg---no-completions) : Do not source the autocompletion scripts from the environment - [`--change-ps1 `](#arg---change-ps1) : Do not change the PS1 variable when starting a prompt ``` **options**: `true`, `false` ``` ## Update Options - [`--no-install`](#arg---no-install) : Don't modify the environment, only modify the lock-file - [`--frozen`](#arg---frozen) : Install the environment as defined in the lockfile, doesn't update lockfile if it isn't up-to-date with the manifest file ``` **env**: `PIXI_FROZEN` ``` - [`--locked`](#arg---locked) : Check if lockfile is up-to-date before installing the environment, aborts when lockfile isn't up-to-date with the manifest file ``` **env**: `PIXI_LOCKED` ``` - [`--as-is`](#arg---as-is) : Shorthand for the combination of --no-install and --frozen ## Global Options - [`--manifest-path (-m) `](#arg---manifest-path) : The path to `pixi.toml`, `pyproject.toml`, or the workspace directory - [`--workspace (-w) `](#arg---workspace) : Name of the workspace ## Description Print the pixi environment activation script. You can source the script to activate the environment without needing pixi itself. ## Examples ```shell pixi shell-hook pixi shell-hook --shell bash pixi shell-hook --shell zsh pixi shell-hook -s powershell pixi shell-hook --manifest-path ~/myworkspace/pixi.toml pixi shell-hook --frozen pixi shell-hook --locked pixi shell-hook --environment cuda pixi shell-hook --json ``` Example use-case, when you want to get rid of the `pixi` executable in a Docker container. ```shell pixi shell-hook --shell bash > /etc/profile.d/pixi.sh rm ~/.pixi/bin/pixi # Now the environment will be activated without the need for the pixi executable. ``` # [pixi](../) shell Start a shell in a pixi environment, run `exit` to leave the shell ## Usage ```text pixi shell [OPTIONS] ``` ## Options - [`--environment (-e) `](#arg---environment) : The environment to activate in the shell ## Config Options - [`--auth-file `](#arg---auth-file) : Path to the file containing the authentication token - [`--concurrent-downloads `](#arg---concurrent-downloads) : Max concurrent network requests, default is `50` - [`--concurrent-solves `](#arg---concurrent-solves) : Max concurrent solves, default is the number of CPUs - [`--pinning-strategy `](#arg---pinning-strategy) : Set pinning strategy ``` **options**: `semver`, `minor`, `major`, `latest-up`, `exact-version`, `no-pin` ``` - [`--pypi-keyring-provider `](#arg---pypi-keyring-provider) : Specifies whether to use the keyring to look up credentials for PyPI ``` **options**: `disabled`, `subprocess` ``` - [`--run-post-link-scripts`](#arg---run-post-link-scripts) : Run post-link scripts (insecure) - [`--tls-no-verify`](#arg---tls-no-verify) : Do not verify the TLS certificate of the server - [`--tls-root-certs `](#arg---tls-root-certs) : Which TLS root certificates to use: 'webpki' (bundled Mozilla roots), 'native' (system store), or 'all' (both) ``` **env**: `PIXI_TLS_ROOT_CERTS` ``` - [`--use-environment-activation-cache`](#arg---use-environment-activation-cache) : Use environment activation cache (experimental) - [`--change-ps1 `](#arg---change-ps1) : Do not change the PS1 variable when starting a prompt ``` **options**: `true`, `false` ``` - [`--force-activate`](#arg---force-activate) : Do not use the environment activation cache. (default: true except in experimental mode) - [`--no-completions`](#arg---no-completions) : Do not source the autocompletion scripts from the environment ## Update Options - [`--no-install`](#arg---no-install) : Don't modify the environment, only modify the lock-file - [`--frozen`](#arg---frozen) : Install the environment as defined in the lockfile, doesn't update lockfile if it isn't up-to-date with the manifest file ``` **env**: `PIXI_FROZEN` ``` - [`--locked`](#arg---locked) : Check if lockfile is up-to-date before installing the environment, aborts when lockfile isn't up-to-date with the manifest file ``` **env**: `PIXI_LOCKED` ``` - [`--as-is`](#arg---as-is) : Shorthand for the combination of --no-install and --frozen ## Global Options - [`--manifest-path (-m) `](#arg---manifest-path) : The path to `pixi.toml`, `pyproject.toml`, or the workspace directory - [`--workspace (-w) `](#arg---workspace) : Name of the workspace ## Examples ```shell pixi shell pixi shell --manifest-path ~/myworkspace/pixi.toml pixi shell --frozen pixi shell --locked pixi shell --environment cuda exit ``` # [pixi](../) task Interact with tasks in the workspace ## Usage ```text pixi task [OPTIONS] ``` ## Subcommands | Command | Description | | ------------------- | ----------------------------------- | | [`add`](add/) | Add a command to the workspace | | [`remove`](remove/) | Remove a command from the workspace | | [`alias`](alias/) | Alias another specific command | | [`list`](list/) | List all tasks in the workspace | ## Global Options - [`--manifest-path (-m) `](#arg---manifest-path) : The path to `pixi.toml`, `pyproject.toml`, or the workspace directory - [`--workspace (-w) `](#arg---workspace) : Name of the workspace # [pixi](../) tree Show a tree of workspace dependencies ## Usage ```text pixi tree [OPTIONS] [REGEX] ``` ## Arguments - [``](#arg-%3CREGEX%3E) : List only packages matching a regular expression ## Options - [`--platform (-p) `](#arg---platform) : The platform to list packages for. Defaults to the current platform - [`--environment (-e) `](#arg---environment) : The environment to list packages for. Defaults to the default environment - [`--invert (-i)`](#arg---invert) : Invert tree and show what depends on given package in the regex argument ## Update Options - [`--frozen`](#arg---frozen) : Install the environment as defined in the lockfile, doesn't update lockfile if it isn't up-to-date with the manifest file ``` **env**: `PIXI_FROZEN` ``` - [`--locked`](#arg---locked) : Check if lockfile is up-to-date before installing the environment, aborts when lockfile isn't up-to-date with the manifest file ``` **env**: `PIXI_LOCKED` ``` - [`--no-install`](#arg---no-install) : Don't modify the environment, only modify the lock-file ## Global Options - [`--manifest-path (-m) `](#arg---manifest-path) : The path to `pixi.toml`, `pyproject.toml`, or the workspace directory - [`--workspace (-w) `](#arg---workspace) : Name of the workspace ## Description Show a tree of workspace dependencies Dependency names highlighted in green are directly specified in the manifest. Yellow version numbers are conda packages, PyPI version numbers are blue. ## Examples ```shell pixi tree pixi tree pre-commit pixi tree -i yaml pixi tree --environment docs pixi tree --platform win-64 ``` Output will look like this, where direct packages in the [manifest file](../../../pixi_manifest/) will be green. Once a package has been displayed once, the tree won't continue to recurse through its dependencies (compare the first time `python` appears, vs the rest), and it will instead be marked with a star `(*)`. Version numbers are colored by the package type, yellow for Conda packages and blue for PyPI. ```shell ➜ pixi tree β”œβ”€β”€ pre-commit v3.3.3 β”‚ β”œβ”€β”€ cfgv v3.3.1 β”‚ β”‚ └── python v3.12.2 β”‚ β”‚ β”œβ”€β”€ bzip2 v1.0.8 β”‚ β”‚ β”œβ”€β”€ libexpat v2.6.2 β”‚ β”‚ β”œβ”€β”€ libffi v3.4.2 β”‚ β”‚ β”œβ”€β”€ libsqlite v3.45.2 β”‚ β”‚ β”‚ └── libzlib v1.2.13 β”‚ β”‚ β”œβ”€β”€ libzlib v1.2.13 (*) β”‚ β”‚ β”œβ”€β”€ ncurses v6.4.20240210 β”‚ β”‚ β”œβ”€β”€ openssl v3.2.1 β”‚ β”‚ β”œβ”€β”€ readline v8.2 β”‚ β”‚ β”‚ └── ncurses v6.4.20240210 (*) β”‚ β”‚ β”œβ”€β”€ tk v8.6.13 β”‚ β”‚ β”‚ └── libzlib v1.2.13 (*) β”‚ β”‚ └── xz v5.2.6 β”‚ β”œβ”€β”€ identify v2.5.35 β”‚ β”‚ └── python v3.12.2 (*) ... └── tbump v6.9.0 ... └── tomlkit v0.12.4 └── python v3.12.2 (*) ``` A regex pattern can be specified to filter the tree to just those that show a specific direct, or transitive dependency: ```shell ➜ pixi tree pre-commit └── pre-commit v3.3.3 β”œβ”€β”€ virtualenv v20.25.1 β”‚ β”œβ”€β”€ filelock v3.13.1 β”‚ β”‚ └── python v3.12.2 β”‚ β”‚ β”œβ”€β”€ libexpat v2.6.2 β”‚ β”‚ β”œβ”€β”€ readline v8.2 β”‚ β”‚ β”‚ └── ncurses v6.4.20240210 β”‚ β”‚ β”œβ”€β”€ libsqlite v3.45.2 β”‚ β”‚ β”‚ └── libzlib v1.2.13 β”‚ β”‚ β”œβ”€β”€ bzip2 v1.0.8 β”‚ β”‚ β”œβ”€β”€ libzlib v1.2.13 (*) β”‚ β”‚ β”œβ”€β”€ libffi v3.4.2 β”‚ β”‚ β”œβ”€β”€ tk v8.6.13 β”‚ β”‚ β”‚ └── libzlib v1.2.13 (*) β”‚ β”‚ β”œβ”€β”€ xz v5.2.6 β”‚ β”‚ β”œβ”€β”€ ncurses v6.4.20240210 (*) β”‚ β”‚ └── openssl v3.2.1 β”‚ β”œβ”€β”€ platformdirs v4.2.0 β”‚ β”‚ └── python v3.12.2 (*) β”‚ β”œβ”€β”€ distlib v0.3.8 β”‚ β”‚ └── python v3.12.2 (*) β”‚ └── python v3.12.2 (*) β”œβ”€β”€ pyyaml v6.0.1 ... ``` Additionally, the tree can be inverted, and it can show which packages depend on a regex pattern. The packages specified in the manifest will also be highlighted (in this case `cffconvert` and `pre-commit` would be). ```shell ➜ pixi tree -i yaml ruamel.yaml v0.18.6 β”œβ”€β”€ pykwalify v1.8.0 β”‚ └── cffconvert v2.0.0 └── cffconvert v2.0.0 pyyaml v6.0.1 └── pre-commit v3.3.3 ruamel.yaml.clib v0.2.8 └── ruamel.yaml v0.18.6 β”œβ”€β”€ pykwalify v1.8.0 β”‚ └── cffconvert v2.0.0 └── cffconvert v2.0.0 yaml v0.2.5 └── pyyaml v6.0.1 └── pre-commit v3.3.3 ``` Warning Use `-v` to show which `pypi` packages are not yet parsed correctly. The `extras` and `markers` parsing is still under development. # [pixi](../) update The `update` command checks if there are newer versions of the dependencies and updates the `pixi.lock` file and environments accordingly ## Usage ```text pixi update [OPTIONS] [PACKAGES]... ``` ## Arguments - [``](#arg-%3CPACKAGES%3E) : The packages to update, space separated. If no packages are provided, all packages will be updated ``` May be provided more than once. ``` ## Options - [`--no-install`](#arg---no-install) : Don't install the (solve) environments needed for pypi-dependencies solving - [`--dry-run (-n)`](#arg---dry-run) : Don't actually write the lockfile or update any environment - [`--environment (-e) `](#arg---environment) : The environments to update. If none is specified, all environments are updated ``` May be provided more than once. ``` - [`--platform (-p) `](#arg---platform) : The platforms to update. If none is specified, all platforms are updated ``` May be provided more than once. ``` - [`--json`](#arg---json) : Output the changes in JSON format ## Config Options - [`--auth-file `](#arg---auth-file) : Path to the file containing the authentication token - [`--concurrent-downloads `](#arg---concurrent-downloads) : Max concurrent network requests, default is `50` - [`--concurrent-solves `](#arg---concurrent-solves) : Max concurrent solves, default is the number of CPUs - [`--pinning-strategy `](#arg---pinning-strategy) : Set pinning strategy ``` **options**: `semver`, `minor`, `major`, `latest-up`, `exact-version`, `no-pin` ``` - [`--pypi-keyring-provider `](#arg---pypi-keyring-provider) : Specifies whether to use the keyring to look up credentials for PyPI ``` **options**: `disabled`, `subprocess` ``` - [`--run-post-link-scripts`](#arg---run-post-link-scripts) : Run post-link scripts (insecure) - [`--tls-no-verify`](#arg---tls-no-verify) : Do not verify the TLS certificate of the server - [`--tls-root-certs `](#arg---tls-root-certs) : Which TLS root certificates to use: 'webpki' (bundled Mozilla roots), 'native' (system store), or 'all' (both) ``` **env**: `PIXI_TLS_ROOT_CERTS` ``` - [`--use-environment-activation-cache`](#arg---use-environment-activation-cache) : Use environment activation cache (experimental) ## Global Options - [`--manifest-path (-m) `](#arg---manifest-path) : The path to `pixi.toml`, `pyproject.toml`, or the workspace directory - [`--workspace (-w) `](#arg---workspace) : Name of the workspace ## Description The `update` command checks if there are newer versions of the dependencies and updates the `pixi.lock` file and environments accordingly. It will only update the lock file if the dependencies in the manifest file are still compatible with the new versions. ## Examples ```shell pixi update numpy # (1)! pixi update numpy pandas # (2)! pixi update --manifest-path ~/myworkspace/pixi.toml numpy # (3)! pixi update --environment lint python # (4)! pixi update -e lint -e schema -e docs pre-commit # (5)! pixi update --platform osx-arm64 mlx # (6)! pixi update -p linux-64 -p osx-64 numpy # (7)! pixi update --dry-run numpy # (8)! pixi update --no-install boto3 # (9)! ``` 1. This will update the `numpy` package to the latest version that fits the requirement. 1. This will update the `numpy` and `pandas` packages to the latest version that fits the requirement. 1. This will update the `numpy` package to the latest version in the manifest file at the given path. 1. This will update the `python` package in the `lint` environment. 1. This will update the `pre-commit` package in the `lint`, `schema`, and `docs` environments. 1. This will update the `mlx` package in the `osx-arm64` platform. 1. This will update the `numpy` package in the `linux-64` and `osx-64` platforms. 1. This will show the packages that would be updated without actually updating them in the lockfile 1. This will update the `boto3` package in the manifest and lockfile, without installing it in an environment. # [pixi](../) upgrade Checks if there are newer versions of the dependencies and upgrades them in the lockfile and manifest file Note The `pixi upgrade` command will update only `version`s, except when you specify the exact package name (`pixi upgrade numpy`). Then it will remove all fields, apart from: - `build` field containing a wildcard `*` - `channel` - `file_name` - `url` - `subdir`. Note In v0.55.0 and earlier releases, by default only the `default` feature was upgraded. Pass `--feature=default` if you want to emulate this behaviour on newer releases. ## Usage ```text pixi upgrade [OPTIONS] [PACKAGES]... ``` ## Arguments - [``](#arg-%3CPACKAGES%3E) : The packages to upgrade ``` May be provided more than once. ``` ## Options - [`--feature (-f) `](#arg---feature) : The feature to update - [`--exclude `](#arg---exclude) : The packages which should be excluded ``` May be provided more than once. ``` - [`--json`](#arg---json) : Output the changes in JSON format - [`--dry-run (-n)`](#arg---dry-run) : Only show the changes that would be made, without actually updating the manifest, lock file, or environment ## Config Options - [`--auth-file `](#arg---auth-file) : Path to the file containing the authentication token - [`--concurrent-downloads `](#arg---concurrent-downloads) : Max concurrent network requests, default is `50` - [`--concurrent-solves `](#arg---concurrent-solves) : Max concurrent solves, default is the number of CPUs - [`--pinning-strategy `](#arg---pinning-strategy) : Set pinning strategy ``` **options**: `semver`, `minor`, `major`, `latest-up`, `exact-version`, `no-pin` ``` - [`--pypi-keyring-provider `](#arg---pypi-keyring-provider) : Specifies whether to use the keyring to look up credentials for PyPI ``` **options**: `disabled`, `subprocess` ``` - [`--run-post-link-scripts`](#arg---run-post-link-scripts) : Run post-link scripts (insecure) - [`--tls-no-verify`](#arg---tls-no-verify) : Do not verify the TLS certificate of the server - [`--tls-root-certs `](#arg---tls-root-certs) : Which TLS root certificates to use: 'webpki' (bundled Mozilla roots), 'native' (system store), or 'all' (both) ``` **env**: `PIXI_TLS_ROOT_CERTS` ``` - [`--use-environment-activation-cache`](#arg---use-environment-activation-cache) : Use environment activation cache (experimental) ## Update Options - [`--no-install`](#arg---no-install) : Don't modify the environment, only modify the lock-file - [`--frozen`](#arg---frozen) : Install the environment as defined in the lockfile, doesn't update lockfile if it isn't up-to-date with the manifest file ``` **env**: `PIXI_FROZEN` ``` - [`--locked`](#arg---locked) : Check if lockfile is up-to-date before installing the environment, aborts when lockfile isn't up-to-date with the manifest file ``` **env**: `PIXI_LOCKED` ``` ## Global Options - [`--manifest-path (-m) `](#arg---manifest-path) : The path to `pixi.toml`, `pyproject.toml`, or the workspace directory - [`--workspace (-w) `](#arg---workspace) : Name of the workspace ## Description Checks if there are newer versions of the dependencies and upgrades them in the lockfile and manifest file. `pixi upgrade` loosens the requirements for the given packages, updates the lock file and the adapts the manifest accordingly. By default, all features are upgraded. ## Examples ```shell pixi upgrade # (1)! pixi upgrade numpy # (2)! pixi upgrade numpy pandas # (3)! pixi upgrade --manifest-path ~/myworkspace/pixi.toml numpy # (4)! pixi upgrade --feature lint python # (5)! pixi upgrade --json # (6)! pixi upgrade --dry-run # (7)! ``` 1. This will upgrade all packages to the latest version. 1. This will upgrade the `numpy` package to the latest version. 1. This will upgrade the `numpy` and `pandas` packages to the latest version. 1. This will upgrade the `numpy` package to the latest version in the manifest file at the given path. 1. This will upgrade the `python` package in the `lint` feature. 1. This will upgrade all packages and output the result in JSON format. 1. This will show the packages that would be upgraded without actually upgrading them in the lockfile or manifest. # [pixi](../) upload Upload conda packages to various channels The `pixi upload` command supports uploading conda packages to various server types: | Server Type | Description | | ------------- | ------------------------------------------------------------------- | | `prefix` | Upload to [prefix.dev](https://prefix.dev) or self-hosted instances | | `anaconda` | Upload to [Anaconda.org](https://anaconda.org) | | `quetz` | Upload to a [Quetz](https://github.com/mamba-org/quetz) server | | `artifactory` | Upload to [JFrog Artifactory](https://jfrog.com/artifactory/) | | `s3` | Upload to S3-compatible object storage | ## Usage ```text pixi upload [OPTIONS] [PACKAGE_FILES]... ``` ## Subcommands | Command | Description | | ----------------------------- | ---------------------------------------------------------------------------------------------------- | | [`quetz`](quetz/) | Upload to a Quetz server. Authentication is used from the keychain / auth-file | | [`artifactory`](artifactory/) | Options for uploading to a Artifactory channel. Authentication is used from the keychain / auth-file | | [`prefix`](prefix/) | Options for uploading to a prefix.dev server. Authentication is used from the keychain / auth-file | | [`anaconda`](anaconda/) | Options for uploading to a Anaconda.org server | | [`s3`](s3/) | Options for uploading to S3 | ## Arguments - [``](#arg-%3CPACKAGE_FILES%3E) : The package file to upload ``` May be provided more than once. ``` ## Options - [`--allow-insecure-host `](#arg---allow-insecure-host) : List of hosts for which SSL certificate verification should be skipped ``` May be provided more than once. ``` ## Description Upload conda packages to various channels Supported server types: prefix, anaconda, quetz, artifactory, s3, conda-forge Use `pixi auth login` to authenticate with the server. ## Examples ### Uploading to prefix.dev ```shell # Upload a package to a channel on prefix.dev pixi upload prefix --channel my-channel my_package-1.0.0-h123abc_0.conda # Upload with an explicit API key pixi upload prefix --channel my-channel --api-key $PREFIX_API_KEY my_package.conda # Skip upload if package already exists pixi upload prefix --channel my-channel --skip-existing my_package.conda ``` ### Uploading to Anaconda.org ```shell # Upload to your personal channel pixi upload anaconda --owner my-username my_package.conda # Upload to a specific label/channel pixi upload anaconda --owner my-username --channel dev my_package.conda # Force replace existing package pixi upload anaconda --owner my-username --force my_package.conda ``` ### Uploading to S3 ```shell # Upload to an S3 bucket (using AWS credentials from environment) pixi upload s3 --channel s3://my-bucket/my-channel my_package.conda # Upload with explicit credentials pixi upload s3 \ --channel s3://my-bucket/my-channel \ --region us-east-1 \ --access-key-id $AWS_ACCESS_KEY_ID \ --secret-access-key $AWS_SECRET_ACCESS_KEY \ my_package.conda # Upload to S3-compatible storage (MinIO, Cloudflare R2, etc.) pixi upload s3 \ --channel s3://my-bucket/my-channel \ --endpoint-url https://minio.example.com \ --region us-east-1 \ --addressing-style path \ my_package.conda # Force replace existing package pixi upload s3 --channel s3://my-bucket/my-channel --force my_package.conda ``` ### Uploading to Quetz ```shell # Upload to a Quetz server pixi upload quetz \ --url https://my-quetz-server.com \ --channel my-channel \ my_package.conda # Upload with explicit API key pixi upload quetz \ --url https://my-quetz-server.com \ --channel my-channel \ --api-key $QUETZ_API_KEY \ my_package.conda ``` ### Uploading to Artifactory ```shell # Upload to Artifactory pixi upload artifactory \ --url https://my-artifactory.com \ --channel conda-local \ my_package.conda # Upload with explicit token pixi upload artifactory \ --url https://my-artifactory.com \ --channel conda-local \ --token $ARTIFACTORY_TOKEN \ my_package.conda ``` ### Uploading Multiple Packages All server types support uploading multiple packages at once: ```shell pixi upload prefix --channel my-channel package1.conda package2.conda package3.conda ``` ## Authentication For most server types, authentication can be provided in multiple ways: 1. **Keychain / auth-file**: Use `pixi auth login` to store credentials ```shell pixi auth login https://prefix.dev --token $MY_TOKEN pixi upload prefix --channel my-channel my_package.conda ``` 1. **Environment variables**: Each server type supports specific environment variables - `PREFIX_API_KEY` for prefix.dev - `ANACONDA_API_KEY` for Anaconda.org - `QUETZ_API_KEY` for Quetz - `ARTIFACTORY_TOKEN` for Artifactory - `S3_ACCESS_KEY_ID`, `S3_SECRET_ACCESS_KEY` for S3 1. **Command-line arguments**: Pass credentials directly via `--api-key`, `--token`, etc. ## S3 Re-indexing When uploading packages to S3, the `repodata.json` file needs to be updated manually since S3 is just storage, not a package server. Use `rattler-index` to re-index your S3 bucket after uploading: ```shell pixi exec rattler-index s3 s3://my-bucket/my-channel \ --endpoint-url https://my-s3-host \ --region us-east-1 ``` See the [S3 deployment documentation](../../../../deployment/s3/) for more details. # [pixi](../) workspace Modify the workspace configuration file through the command line ## Usage ```text pixi workspace [OPTIONS] ``` ## Subcommands | Command | Description | | --------------------------------------------- | --------------------------------------------------------------------------------------- | | [`channel`](channel/) | Commands to manage workspace channels | | [`description`](description/) | Commands to manage workspace description | | [`platform`](platform/) | Commands to manage workspace platforms | | [`version`](version/) | Commands to manage workspace version | | [`environment`](environment/) | Commands to manage workspace environments | | [`feature`](feature/) | Commands to manage workspace features | | [`export`](export/) | Commands to export workspaces to other formats | | [`name`](name/) | Commands to manage workspace name | | [`system-requirements`](system-requirements/) | Commands to manage workspace system requirements | | [`register`](register/) | Commands to manage the registry of workspaces. Default command will add a new workspace | | [`requires-pixi`](requires-pixi/) | Commands to manage the pixi minimum version requirement | ## Global Options - [`--manifest-path (-m) `](#arg---manifest-path) : The path to `pixi.toml`, `pyproject.toml`, or the workspace directory - [`--workspace (-w) `](#arg---workspace) : Name of the workspace # [pixi](../../) [auth](../) login Store authentication information for a given host ## Usage ```text pixi auth login [OPTIONS] ``` ## Arguments - [``](#arg-%3CHOST%3E) : The host to authenticate with (e.g. prefix.dev) ``` **required**: `true` ``` ## OAuth/OIDC Authentication - [`--oauth`](#arg---oauth) : Use OAuth/OIDC authentication - [`--oauth-issuer-url `](#arg---oauth-issuer-url) : OIDC issuer URL (defaults to }) - [`--oauth-client-id `](#arg---oauth-client-id) : OAuth client ID (defaults to "rattler") - [`--oauth-client-secret `](#arg---oauth-client-secret) : OAuth client secret (for confidential clients) - [`--oauth-flow `](#arg---oauth-flow) : OAuth flow: auto (default), auth-code, device-code ``` **options**: `auto`, `auth-code`, `device-code` ``` - [`--oauth-scope `](#arg---oauth-scope) : Additional OAuth scopes to request (repeatable) ``` May be provided more than once. ``` ## S3 Authentication - [`--s3-access-key-id `](#arg---s3-access-key-id) : The S3 access key ID - [`--s3-secret-access-key `](#arg---s3-secret-access-key) : The S3 secret access key - [`--s3-session-token `](#arg---s3-session-token) : The S3 session token ## Token / Basic Authentication - [`--token `](#arg---token) : The token to use (for authentication with prefix.dev) - [`--username `](#arg---username) : The username to use (for basic HTTP authentication) - [`--password `](#arg---password) : The password to use (for basic HTTP authentication) - [`--conda-token `](#arg---conda-token) : The token to use on anaconda.org / quetz authentication ## Examples ```shell pixi auth login repo.prefix.dev --token pfx_JQEV-m_2bdz-D8NSyRSaAndHANx0qHjq7f2iD pixi auth login anaconda.org --conda-token ABCDEFGHIJKLMNOP pixi auth login https://myquetz.server --username john --password xxxxxx pixi auth login s3://my-bucket --s3-access-key-id $AWS_ACCESS_KEY_ID --s3-secret-access-key $AWS_SECRET_ACCESS_KEY ``` # [pixi](../../) [auth](../) logout Remove authentication information for a given host ## Usage ```text pixi auth logout ``` ## Arguments - [``](#arg-%3CHOST%3E) : The host to remove authentication for ``` **required**: `true` ``` ## Examples ```shell pixi auth logout pixi auth logout repo.prefix.dev pixi auth logout anaconda.org pixi auth logout s3://my-bucket ``` # [pixi](../../) [clean](../) cache Clean the cache of your system which are touched by pixi ## Usage ```text pixi clean cache [OPTIONS] ``` ## Options - [`--pypi`](#arg---pypi) : Clean only the pypi related cache - [`--conda`](#arg---conda) : Clean only the conda related cache - [`--mapping`](#arg---mapping) : Clean only the mapping cache - [`--exec`](#arg---exec) : Clean only `exec` cache - [`--repodata`](#arg---repodata) : Clean only the repodata cache - [`--build-backends`](#arg---build-backends) : Clean only the build backends environments cache - [`--build`](#arg---build) : Clean only the build related cache - [`--yes (-y)`](#arg---yes) : Answer yes to all questions ## Description Clean the cache of your system which are touched by pixi. Specify the cache type to clean with the flags. ## Examples ```shell pixi clean cache # clean all pixi caches pixi clean cache --pypi # clean only the pypi cache pixi clean cache --conda # clean only the conda cache pixi clean cache --mapping # clean only the mapping cache pixi clean cache --exec # clean only the `exec` cache pixi clean cache --repodata # clean only the `repodata` cache pixi clean cache --yes # skip the confirmation prompt ``` # [pixi](../../) [config](../) append Append a value to a list configuration key ## Usage ```text pixi config append [OPTIONS] ``` ## Arguments - [``](#arg-%3CKEY%3E) : Configuration key to set ``` **required**: `true` ``` - [``](#arg-%3CVALUE%3E) : Configuration value to (pre|ap)pend ``` **required**: `true` ``` ## Config Options - [`--local (-l)`](#arg---local) : Operation on project-local configuration - [`--global (-g)`](#arg---global) : Operation on global configuration - [`--system (-s)`](#arg---system) : Operation on system configuration ## Global Options - [`--manifest-path (-m) `](#arg---manifest-path) : The path to `pixi.toml`, `pyproject.toml`, or the workspace directory - [`--workspace (-w) `](#arg---workspace) : Name of the workspace ## Description Append a value to a list configuration key Example: `pixi config append default-channels bioconda` ## Examples ```shell pixi config append default-channels robostack pixi config append default-channels bioconda --global ``` # [pixi](../../) [config](../) edit Edit the configuration file ## Usage ```text pixi config edit [OPTIONS] [EDITOR] ``` ## Arguments - [``](#arg-%3CEDITOR%3E) : The editor to use, defaults to `EDITOR` environment variable or `nano` on Unix and `notepad` on Windows ``` **env**: `EDITOR` ``` ## Config Options - [`--local (-l)`](#arg---local) : Operation on project-local configuration - [`--global (-g)`](#arg---global) : Operation on global configuration - [`--system (-s)`](#arg---system) : Operation on system configuration ## Global Options - [`--manifest-path (-m) `](#arg---manifest-path) : The path to `pixi.toml`, `pyproject.toml`, or the workspace directory - [`--workspace (-w) `](#arg---workspace) : Name of the workspace ## Examples ```shell pixi config edit --system pixi config edit --local pixi config edit -g pixi config edit --global code pixi config edit --system vim ``` # [pixi](../../) [config](../) list List configuration values ## Usage ```text pixi config list [OPTIONS] [KEY] ``` ## Arguments - [``](#arg-%3CKEY%3E) : Configuration key to show (all if not provided) ## Options - [`--json`](#arg---json) : Output in JSON format ## Config Options - [`--local (-l)`](#arg---local) : Operation on project-local configuration - [`--global (-g)`](#arg---global) : Operation on global configuration - [`--system (-s)`](#arg---system) : Operation on system configuration ## Global Options - [`--manifest-path (-m) `](#arg---manifest-path) : The path to `pixi.toml`, `pyproject.toml`, or the workspace directory - [`--workspace (-w) `](#arg---workspace) : Name of the workspace ## Description List configuration values Example: `pixi config list default-channels` ## Examples ```shell pixi config list default-channels pixi config list --json pixi config list --system pixi config list -g ``` # [pixi](../../) [config](../) prepend Prepend a value to a list configuration key ## Usage ```text pixi config prepend [OPTIONS] ``` ## Arguments - [``](#arg-%3CKEY%3E) : Configuration key to set ``` **required**: `true` ``` - [``](#arg-%3CVALUE%3E) : Configuration value to (pre|ap)pend ``` **required**: `true` ``` ## Config Options - [`--local (-l)`](#arg---local) : Operation on project-local configuration - [`--global (-g)`](#arg---global) : Operation on global configuration - [`--system (-s)`](#arg---system) : Operation on system configuration ## Global Options - [`--manifest-path (-m) `](#arg---manifest-path) : The path to `pixi.toml`, `pyproject.toml`, or the workspace directory - [`--workspace (-w) `](#arg---workspace) : Name of the workspace ## Description Prepend a value to a list configuration key Example: `pixi config prepend default-channels bioconda` ## Examples ```shell pixi config prepend default-channels conda-forge ``` # [pixi](../../) [config](../) set Set a configuration value ## Usage ```text pixi config set [OPTIONS] [VALUE] ``` ## Arguments - [``](#arg-%3CKEY%3E) : Configuration key to set ``` **required**: `true` ``` - [``](#arg-%3CVALUE%3E) : Configuration value to set (key will be unset if value not provided) ## Config Options - [`--local (-l)`](#arg---local) : Operation on project-local configuration - [`--global (-g)`](#arg---global) : Operation on global configuration - [`--system (-s)`](#arg---system) : Operation on system configuration ## Global Options - [`--manifest-path (-m) `](#arg---manifest-path) : The path to `pixi.toml`, `pyproject.toml`, or the workspace directory - [`--workspace (-w) `](#arg---workspace) : Name of the workspace ## Description Set a configuration value Example: `pixi config set default-channels '["conda-forge", "bioconda"]'` ## Examples ```shell pixi config set default-channels '["conda-forge", "bioconda"]' pixi config set --global mirrors '{"https://conda.anaconda.org/conda-forge": ["https://prefix.dev/conda-forge"]}' pixi config set repodata-config.disable-zstd true --system pixi config set --global detached-environments "/opt/pixi/envs" pixi config set detached-environments false pixi config set s3-options.my-bucket '{"endpoint-url": "http://localhost:9000", "force-path-style": true, "region": "auto"}' ``` # [pixi](../../) [config](../) unset Unset a configuration value ## Usage ```text pixi config unset [OPTIONS] ``` ## Arguments - [``](#arg-%3CKEY%3E) : Configuration key to unset ``` **required**: `true` ``` ## Config Options - [`--local (-l)`](#arg---local) : Operation on project-local configuration - [`--global (-g)`](#arg---global) : Operation on global configuration - [`--system (-s)`](#arg---system) : Operation on system configuration ## Global Options - [`--manifest-path (-m) `](#arg---manifest-path) : The path to `pixi.toml`, `pyproject.toml`, or the workspace directory - [`--workspace (-w) `](#arg---workspace) : Name of the workspace ## Description Unset a configuration value Example: `pixi config unset default-channels` ## Examples ```shell pixi config unset default-channels pixi config unset --global mirrors pixi config unset repodata-config.disable-zstd --system ``` # [pixi](../../) [global](../) add Adds dependencies to an environment ## Usage ```text pixi global add [OPTIONS] --environment [PACKAGE]... ``` ## Arguments - [``](#arg-%3CPACKAGE%3E) : The dependency as names, conda MatchSpecs ``` May be provided more than once. ``` ## Options - [`--path `](#arg---path) : The path to the local package - [`--environment (-e) `](#arg---environment) : Specifies the environment that the dependencies need to be added to ``` **required**: `true` ``` - [`--expose `](#arg---expose) : Add one or more mapping which describe which executables are exposed. The syntax is `exposed_name=executable_name`, so for example `python3.10=python`. Alternatively, you can input only an executable_name and `executable_name=executable_name` is assumed ``` May be provided more than once. ``` ## Config Options - [`--auth-file `](#arg---auth-file) : Path to the file containing the authentication token - [`--concurrent-downloads `](#arg---concurrent-downloads) : Max concurrent network requests, default is `50` - [`--concurrent-solves `](#arg---concurrent-solves) : Max concurrent solves, default is the number of CPUs - [`--pinning-strategy `](#arg---pinning-strategy) : Set pinning strategy ``` **options**: `semver`, `minor`, `major`, `latest-up`, `exact-version`, `no-pin` ``` - [`--pypi-keyring-provider `](#arg---pypi-keyring-provider) : Specifies whether to use the keyring to look up credentials for PyPI ``` **options**: `disabled`, `subprocess` ``` - [`--run-post-link-scripts`](#arg---run-post-link-scripts) : Run post-link scripts (insecure) - [`--tls-no-verify`](#arg---tls-no-verify) : Do not verify the TLS certificate of the server - [`--tls-root-certs `](#arg---tls-root-certs) : Which TLS root certificates to use: 'webpki' (bundled Mozilla roots), 'native' (system store), or 'all' (both) ``` **env**: `PIXI_TLS_ROOT_CERTS` ``` - [`--use-environment-activation-cache`](#arg---use-environment-activation-cache) : Use environment activation cache (experimental) ## Git Options - [`--git `](#arg---git) : The git url, e.g. `https://github.com/user/repo.git` - [`--branch `](#arg---branch) : The git branch - [`--tag `](#arg---tag) : The git tag - [`--rev `](#arg---rev) : The git revision - [`--subdir `](#arg---subdir) : The subdirectory within the git repository ## Description Adds dependencies to an environment Example: - `pixi global add --environment python numpy` - `pixi global add --environment my_env pytest pytest-cov --expose pytest=pytest` ## Examples ```shell pixi global add python=3.9.* --environment my-env pixi global add python=3.9.* --expose py39=python3.9 --environment my-env pixi global add numpy matplotlib --environment my-env pixi global add numpy matplotlib --expose np=python3.9 --environment my-env ``` # [pixi](../../) [global](../) edit Edit the global manifest file ## Usage ```text pixi global edit [EDITOR] ``` ## Arguments - [``](#arg-%3CEDITOR%3E) : The editor to use, defaults to `EDITOR` environment variable or `nano` on Unix and `notepad` on Windows ``` **env**: `EDITOR` ``` ## Description Edit the global manifest file Opens your editor to edit the global manifest file. ## Examples ```shell pixi global edit pixi global edit code pixi global edit vim ``` # [pixi](../../) [global](../) expose Interact with the exposure of binaries in the global environment ## Usage ```text pixi global expose ``` ## Subcommands | Command | Description | | ------------------- | ------------------------------------------------------------------- | | [`add`](add/) | Add exposed binaries from an environment to your global environment | | [`remove`](remove/) | Remove exposed binaries from the global environment | ## Description Interact with the exposure of binaries in the global environment `pixi global expose add python310=python3.10 --environment myenv` will expose the `python3.10` executable as `python310` from the environment `myenv` `pixi global expose remove python310 --environment myenv` will remove the exposed name `python310` from the environment `myenv` # [pixi](../../) [global](../) install Installs the defined packages in a globally accessible location and exposes their command line applications. Need to specify build strings or hardware-specific packages? For advanced package specifications including build strings, see the [Package Specifications](../../../../../concepts/package_specifications/) guide. Examples (both syntaxes work): ```shell # Equals syntax (compact) pixi global install "pytorch=*=*cuda*" --channel pytorch pixi global install "jax=*=*cuda*" # Bracket syntax (explicit) pixi global install "pytorch [build='*cuda*']" --channel pytorch pixi global install "jax [build='*cuda*']" ``` Tip Running `osx-64` on Apple Silicon will install the Intel binary but run it using [Rosetta](https://developer.apple.com/documentation/apple-silicon/about-the-rosetta-translation-environment) ```text pixi global install --platform osx-64 ruff ``` Note When you pass `--path` with a local `.conda` archive, Pixi copies the file into `PIXI_HOME/conda-files` and installs from that managed copy. Supplying any other kind of path keeps the original location unchanged. After using global install, you can use the package you installed anywhere on your system. ## Usage ```text pixi global install [OPTIONS] [PACKAGE]... ``` ## Arguments - [``](#arg-%3CPACKAGE%3E) : The dependency as names, conda MatchSpecs ``` May be provided more than once. ``` ## Options - [`--path `](#arg---path) : The path to the local package - [`--channel (-c) `](#arg---channel) : The channels to consider as a name or a url. Multiple channels can be specified by using this field multiple times ``` May be provided more than once. ``` - [`--platform (-p) `](#arg---platform) : The platform to install the packages for - [`--environment (-e) `](#arg---environment) : Ensures that all packages will be installed in the same environment - [`--expose `](#arg---expose) : Add one or more mapping which describe which executables are exposed. The syntax is `exposed_name=executable_name`, so for example `python3.10=python`. Alternatively, you can input only an executable_name and `executable_name=executable_name` is assumed ``` May be provided more than once. ``` - [`--with `](#arg---with) : Add additional dependencies to the environment. Their executables will not be exposed ``` May be provided more than once. ``` - [`--force-reinstall`](#arg---force-reinstall) : Specifies that the environment should be reinstalled - [`--no-shortcuts`](#arg---no-shortcuts) : Specifies that no shortcuts should be created for the installed packages ## Config Options - [`--auth-file `](#arg---auth-file) : Path to the file containing the authentication token - [`--concurrent-downloads `](#arg---concurrent-downloads) : Max concurrent network requests, default is `50` - [`--concurrent-solves `](#arg---concurrent-solves) : Max concurrent solves, default is the number of CPUs - [`--pinning-strategy `](#arg---pinning-strategy) : Set pinning strategy ``` **options**: `semver`, `minor`, `major`, `latest-up`, `exact-version`, `no-pin` ``` - [`--pypi-keyring-provider `](#arg---pypi-keyring-provider) : Specifies whether to use the keyring to look up credentials for PyPI ``` **options**: `disabled`, `subprocess` ``` - [`--run-post-link-scripts`](#arg---run-post-link-scripts) : Run post-link scripts (insecure) - [`--tls-no-verify`](#arg---tls-no-verify) : Do not verify the TLS certificate of the server - [`--tls-root-certs `](#arg---tls-root-certs) : Which TLS root certificates to use: 'webpki' (bundled Mozilla roots), 'native' (system store), or 'all' (both) ``` **env**: `PIXI_TLS_ROOT_CERTS` ``` - [`--use-environment-activation-cache`](#arg---use-environment-activation-cache) : Use environment activation cache (experimental) ## Git Options - [`--git `](#arg---git) : The git url, e.g. `https://github.com/user/repo.git` - [`--branch `](#arg---branch) : The git branch - [`--tag `](#arg---tag) : The git tag - [`--rev `](#arg---rev) : The git revision - [`--subdir `](#arg---subdir) : The subdirectory within the git repository ## Description Installs the defined packages in a globally accessible location and exposes their command line applications. Example: - `pixi global install starship nushell ripgrep bat` - `pixi global install jupyter --with polars` - `pixi global install --expose python3.8=python python=3.8` - `pixi global install --environment science --expose jupyter --expose ipython jupyter ipython polars` ## Examples ```shell pixi global install ruff # Multiple packages can be installed at once pixi global install starship rattler-build # Specify the channel(s) pixi global install --channel conda-forge --channel bioconda trackplot # Support full conda matchspec pixi global install python=3.9.* pixi global install "python [version='3.11.0', build_number=1]" pixi global install "python [version='3.11.0', build=he550d4f_1_cpython]" pixi global install python=3.11.0=h10a6764_1_cpython # Install for a specific platform, only useful on osx-arm64 pixi global install --platform osx-64 ruff # Install a package with all its executables exposed, together with additional packages that don't expose anything pixi global install ipython --with numpy --with scipy # Install into a specific environment name and expose all executables pixi global install --environment data-science ipython jupyterlab numpy matplotlib # Expose the binary under a different name pixi global install --expose "py39=python3.9" "python=3.9.*" ``` # [pixi](../../) [global](../) list Lists global environments with their dependencies and exposed commands. Can also display all packages within a specific global environment when using the --environment flag. ## Usage ```text pixi global list [OPTIONS] [REGEX] ``` ## Arguments - [``](#arg-%3CREGEX%3E) : List only packages matching a regular expression. Without regex syntax it acts like a `contains` filter ## Options - [`--environment (-e) `](#arg---environment) : Allows listing all the packages installed in a specific environment, with an output similar to `pixi list` - [`--sort-by `](#arg---sort-by) : Sorting strategy for the package table of an environment ``` **default**: `name` **options**: `size`, `name` ``` - [`--json`](#arg---json) : Whether to output in JSON format ## Config Options - [`--auth-file `](#arg---auth-file) : Path to the file containing the authentication token - [`--concurrent-downloads `](#arg---concurrent-downloads) : Max concurrent network requests, default is `50` - [`--concurrent-solves `](#arg---concurrent-solves) : Max concurrent solves, default is the number of CPUs - [`--pinning-strategy `](#arg---pinning-strategy) : Set pinning strategy ``` **options**: `semver`, `minor`, `major`, `latest-up`, `exact-version`, `no-pin` ``` - [`--pypi-keyring-provider `](#arg---pypi-keyring-provider) : Specifies whether to use the keyring to look up credentials for PyPI ``` **options**: `disabled`, `subprocess` ``` - [`--run-post-link-scripts`](#arg---run-post-link-scripts) : Run post-link scripts (insecure) - [`--tls-no-verify`](#arg---tls-no-verify) : Do not verify the TLS certificate of the server - [`--tls-root-certs `](#arg---tls-root-certs) : Which TLS root certificates to use: 'webpki' (bundled Mozilla roots), 'native' (system store), or 'all' (both) ``` **env**: `PIXI_TLS_ROOT_CERTS` ``` - [`--use-environment-activation-cache`](#arg---use-environment-activation-cache) : Use environment activation cache (experimental) ## Description Lists global environments with their dependencies and exposed commands. Can also display all packages within a specific global environment when using the --environment flag. All environments: - Yellow: the binaries that are exposed. - Green: the packages that are explicit dependencies of the environment. - Blue: the version of the installed package. - Cyan: the name of the environment. Per environment: - Green: packages that are explicitly installed. ## Examples We'll only show the dependencies and exposed binaries of the environment if they differ from the environment name. Here is an example of a few installed packages: ```text pixi global list ``` Results in: ```text Global environments at /home/user/.pixi: β”œβ”€β”€ gh: 2.57.0 β”œβ”€β”€ pixi-pack: 0.1.8 β”œβ”€β”€ python: 3.11.0 β”‚ └─ exposes: 2to3, 2to3-3.11, idle3, idle3.11, pydoc, pydoc3, pydoc3.11, python, python3, python3-config, python3.1, python3.11, python3.11-config β”œβ”€β”€ rattler-build: 0.22.0 β”œβ”€β”€ ripgrep: 14.1.0 β”‚ └─ exposes: rg β”œβ”€β”€ vim: 9.1.0611 β”‚ └─ exposes: ex, rview, rvim, view, vim, vimdiff, vimtutor, xxd └── zoxide: 0.9.6 ``` Here is an example of list of a single environment: ```text pixi g list -e pixi-pack ``` Results in: ```text The 'pixi-pack' environment has 8 packages: Package Version Build Size _libgcc_mutex 0.1 conda_forge 2.5 KiB _openmp_mutex 4.5 2_gnu 23.1 KiB ca-certificates 2024.8.30 hbcca054_0 155.3 KiB libgcc 14.1.0 h77fa898_1 826.5 KiB libgcc-ng 14.1.0 h69a702a_1 50.9 KiB libgomp 14.1.0 h77fa898_1 449.4 KiB openssl 3.3.2 hb9d3cd8_0 2.8 MiB pixi-pack 0.1.8 hc762bcd_0 4.3 MiB Package Version Build Size Exposes: pixi-pack Channels: conda-forge Platform: linux-64 ``` # [pixi](../../) [global](../) remove Removes dependencies from an environment ## Usage ```text pixi global remove [OPTIONS] ... ``` ## Arguments - [``](#arg-%3CPACKAGE%3E) : Specifies the package that should be removed ``` May be provided more than once. **required**: `true` ``` ## Options - [`--environment (-e) `](#arg---environment) : Specifies the environment that the dependencies need to be removed from ## Config Options - [`--auth-file `](#arg---auth-file) : Path to the file containing the authentication token - [`--concurrent-downloads `](#arg---concurrent-downloads) : Max concurrent network requests, default is `50` - [`--concurrent-solves `](#arg---concurrent-solves) : Max concurrent solves, default is the number of CPUs - [`--pinning-strategy `](#arg---pinning-strategy) : Set pinning strategy ``` **options**: `semver`, `minor`, `major`, `latest-up`, `exact-version`, `no-pin` ``` - [`--pypi-keyring-provider `](#arg---pypi-keyring-provider) : Specifies whether to use the keyring to look up credentials for PyPI ``` **options**: `disabled`, `subprocess` ``` - [`--run-post-link-scripts`](#arg---run-post-link-scripts) : Run post-link scripts (insecure) - [`--tls-no-verify`](#arg---tls-no-verify) : Do not verify the TLS certificate of the server - [`--tls-root-certs `](#arg---tls-root-certs) : Which TLS root certificates to use: 'webpki' (bundled Mozilla roots), 'native' (system store), or 'all' (both) ``` **env**: `PIXI_TLS_ROOT_CERTS` ``` - [`--use-environment-activation-cache`](#arg---use-environment-activation-cache) : Use environment activation cache (experimental) ## Description Removes dependencies from an environment Use `pixi global uninstall` to remove the whole environment Example: `pixi global remove --environment python numpy` ## Examples ```shell pixi global remove -e my-env package1 package2 ``` # [pixi](../../) [global](../) shortcut Interact with the shortcuts on your machine ## Usage ```text pixi global shortcut ``` ## Subcommands | Command | Description | | ------------------- | --------------------------------------------------- | | [`add`](add/) | Add a shortcut from an environment to your machine. | | [`remove`](remove/) | Remove shortcuts from your machine | # [pixi](../../) [global](../) sync Sync global manifest with installed environments ## Usage ```text pixi global sync [OPTIONS] ``` ## Config Options - [`--auth-file `](#arg---auth-file) : Path to the file containing the authentication token - [`--concurrent-downloads `](#arg---concurrent-downloads) : Max concurrent network requests, default is `50` - [`--concurrent-solves `](#arg---concurrent-solves) : Max concurrent solves, default is the number of CPUs - [`--pinning-strategy `](#arg---pinning-strategy) : Set pinning strategy ``` **options**: `semver`, `minor`, `major`, `latest-up`, `exact-version`, `no-pin` ``` - [`--pypi-keyring-provider `](#arg---pypi-keyring-provider) : Specifies whether to use the keyring to look up credentials for PyPI ``` **options**: `disabled`, `subprocess` ``` - [`--run-post-link-scripts`](#arg---run-post-link-scripts) : Run post-link scripts (insecure) - [`--tls-no-verify`](#arg---tls-no-verify) : Do not verify the TLS certificate of the server - [`--tls-root-certs `](#arg---tls-root-certs) : Which TLS root certificates to use: 'webpki' (bundled Mozilla roots), 'native' (system store), or 'all' (both) ``` **env**: `PIXI_TLS_ROOT_CERTS` ``` - [`--use-environment-activation-cache`](#arg---use-environment-activation-cache) : Use environment activation cache (experimental) # [pixi](../../) [global](../) tree Show a tree of dependencies for a specific global environment ## Usage ```text pixi global tree [OPTIONS] --environment [REGEX] ``` ## Arguments - [``](#arg-%3CREGEX%3E) : List only packages matching a regular expression ## Options - [`--environment (-e) `](#arg---environment) : The environment to list packages for ``` **required**: `true` ``` - [`--invert (-i)`](#arg---invert) : Invert tree and show what depends on a given package in the regex argument ## Description Show a tree of a global environment dependencies Dependency names highlighted in green are directly specified in the manifest. # [pixi](../../) [global](../) uninstall Uninstalls environments from the global environment. ## Usage ```text pixi global uninstall [OPTIONS] ... ``` ## Arguments - [``](#arg-%3CENVIRONMENT%3E) : Specifies the environments that are to be removed ``` May be provided more than once. **required**: `true` ``` ## Config Options - [`--auth-file `](#arg---auth-file) : Path to the file containing the authentication token - [`--concurrent-downloads `](#arg---concurrent-downloads) : Max concurrent network requests, default is `50` - [`--concurrent-solves `](#arg---concurrent-solves) : Max concurrent solves, default is the number of CPUs - [`--pinning-strategy `](#arg---pinning-strategy) : Set pinning strategy ``` **options**: `semver`, `minor`, `major`, `latest-up`, `exact-version`, `no-pin` ``` - [`--pypi-keyring-provider `](#arg---pypi-keyring-provider) : Specifies whether to use the keyring to look up credentials for PyPI ``` **options**: `disabled`, `subprocess` ``` - [`--run-post-link-scripts`](#arg---run-post-link-scripts) : Run post-link scripts (insecure) - [`--tls-no-verify`](#arg---tls-no-verify) : Do not verify the TLS certificate of the server - [`--tls-root-certs `](#arg---tls-root-certs) : Which TLS root certificates to use: 'webpki' (bundled Mozilla roots), 'native' (system store), or 'all' (both) ``` **env**: `PIXI_TLS_ROOT_CERTS` ``` - [`--use-environment-activation-cache`](#arg---use-environment-activation-cache) : Use environment activation cache (experimental) ## Description Uninstalls environments from the global environment. Example: `pixi global uninstall pixi-pack rattler-build` ## Examples ```shell pixi global uninstall my-env pixi global uninstall pixi-pack rattler-build ``` # [pixi](../../) [global](../) update Updates environments in the global environment ## Usage ```text pixi global update [OPTIONS] [ENVIRONMENTS]... ``` ## Arguments - [``](#arg-%3CENVIRONMENTS%3E) : Specifies the environments that are to be updated ``` May be provided more than once. ``` ## Config Options - [`--auth-file `](#arg---auth-file) : Path to the file containing the authentication token - [`--concurrent-downloads `](#arg---concurrent-downloads) : Max concurrent network requests, default is `50` - [`--concurrent-solves `](#arg---concurrent-solves) : Max concurrent solves, default is the number of CPUs - [`--pinning-strategy `](#arg---pinning-strategy) : Set pinning strategy ``` **options**: `semver`, `minor`, `major`, `latest-up`, `exact-version`, `no-pin` ``` - [`--pypi-keyring-provider `](#arg---pypi-keyring-provider) : Specifies whether to use the keyring to look up credentials for PyPI ``` **options**: `disabled`, `subprocess` ``` - [`--run-post-link-scripts`](#arg---run-post-link-scripts) : Run post-link scripts (insecure) - [`--tls-no-verify`](#arg---tls-no-verify) : Do not verify the TLS certificate of the server - [`--tls-root-certs `](#arg---tls-root-certs) : Which TLS root certificates to use: 'webpki' (bundled Mozilla roots), 'native' (system store), or 'all' (both) ``` **env**: `PIXI_TLS_ROOT_CERTS` ``` - [`--use-environment-activation-cache`](#arg---use-environment-activation-cache) : Use environment activation cache (experimental) ## Examples ```shell pixi global update pixi global update pixi-pack pixi global update bat rattler-build ``` # [pixi](../../) [global](../) upgrade-all Upgrade all globally installed packages This command has been removed, please use `pixi global update` instead ## Usage ```text pixi global upgrade-all [OPTIONS] ``` ## Options - [`--channel (-c) `](#arg---channel) : The channels to consider as a name or a url. Multiple channels can be specified by using this field multiple times ``` May be provided more than once. ``` - [`--platform `](#arg---platform) : The platform to install the package for ``` **default**: `current_platform` ``` ## Config Options - [`--auth-file `](#arg---auth-file) : Path to the file containing the authentication token - [`--concurrent-downloads `](#arg---concurrent-downloads) : Max concurrent network requests, default is `50` - [`--concurrent-solves `](#arg---concurrent-solves) : Max concurrent solves, default is the number of CPUs - [`--pinning-strategy `](#arg---pinning-strategy) : Set pinning strategy ``` **options**: `semver`, `minor`, `major`, `latest-up`, `exact-version`, `no-pin` ``` - [`--pypi-keyring-provider `](#arg---pypi-keyring-provider) : Specifies whether to use the keyring to look up credentials for PyPI ``` **options**: `disabled`, `subprocess` ``` - [`--run-post-link-scripts`](#arg---run-post-link-scripts) : Run post-link scripts (insecure) - [`--tls-no-verify`](#arg---tls-no-verify) : Do not verify the TLS certificate of the server - [`--tls-root-certs `](#arg---tls-root-certs) : Which TLS root certificates to use: 'webpki' (bundled Mozilla roots), 'native' (system store), or 'all' (both) ``` **env**: `PIXI_TLS_ROOT_CERTS` ``` - [`--use-environment-activation-cache`](#arg---use-environment-activation-cache) : Use environment activation cache (experimental) # [pixi](../../) [global](../) upgrade Upgrade specific package which is installed globally. This command has been removed, please use `pixi global update` instead ## Usage ```text pixi global upgrade [OPTIONS] [SPECS]... ``` ## Arguments - [``](#arg-%3CSPECS%3E) : Specifies the packages to upgrade ``` May be provided more than once. ``` ## Options - [`--channel (-c) `](#arg---channel) : The channels to consider as a name or a url. Multiple channels can be specified by using this field multiple times ``` May be provided more than once. ``` - [`--platform `](#arg---platform) : The platform to install the package for ``` **default**: `current_platform` ``` # [pixi](../../../) [global](../../) [expose](../) add Add exposed binaries from an environment to your global environment ## Usage ```text pixi global expose add [OPTIONS] --environment [MAPPING]... ``` ## Arguments - [``](#arg-%3CMAPPING%3E) : Add mapping which describe which executables are exposed. The syntax is `exposed_name=executable_name`, so for example `python3.10=python`. Alternatively, you can input only an executable_name and `executable_name=executable_name` is assumed ``` May be provided more than once. ``` ## Options - [`--environment (-e) `](#arg---environment) : The environment to which the binaries should be exposed ``` **required**: `true` ``` ## Config Options - [`--auth-file `](#arg---auth-file) : Path to the file containing the authentication token - [`--concurrent-downloads `](#arg---concurrent-downloads) : Max concurrent network requests, default is `50` - [`--concurrent-solves `](#arg---concurrent-solves) : Max concurrent solves, default is the number of CPUs - [`--pinning-strategy `](#arg---pinning-strategy) : Set pinning strategy ``` **options**: `semver`, `minor`, `major`, `latest-up`, `exact-version`, `no-pin` ``` - [`--pypi-keyring-provider `](#arg---pypi-keyring-provider) : Specifies whether to use the keyring to look up credentials for PyPI ``` **options**: `disabled`, `subprocess` ``` - [`--run-post-link-scripts`](#arg---run-post-link-scripts) : Run post-link scripts (insecure) - [`--tls-no-verify`](#arg---tls-no-verify) : Do not verify the TLS certificate of the server - [`--tls-root-certs `](#arg---tls-root-certs) : Which TLS root certificates to use: 'webpki' (bundled Mozilla roots), 'native' (system store), or 'all' (both) ``` **env**: `PIXI_TLS_ROOT_CERTS` ``` - [`--use-environment-activation-cache`](#arg---use-environment-activation-cache) : Use environment activation cache (experimental) ## Description Add exposed binaries from an environment to your global environment Example: - `pixi global expose add python310=python3.10 python3=python3 --environment myenv` - `pixi global add --environment my_env pytest pytest-cov --expose pytest=pytest` ## Examples ```shell pixi global expose add python --environment my-env pixi global expose add py310=python3.10 --environment python ``` # [pixi](../../../) [global](../../) [expose](../) remove Remove exposed binaries from the global environment ## Usage ```text pixi global expose remove [OPTIONS] [EXPOSED_NAME]... ``` ## Arguments - [``](#arg-%3CEXPOSED_NAME%3E) : The exposed names that should be removed Can be specified multiple times ``` May be provided more than once. ``` ## Config Options - [`--auth-file `](#arg---auth-file) : Path to the file containing the authentication token - [`--concurrent-downloads `](#arg---concurrent-downloads) : Max concurrent network requests, default is `50` - [`--concurrent-solves `](#arg---concurrent-solves) : Max concurrent solves, default is the number of CPUs - [`--pinning-strategy `](#arg---pinning-strategy) : Set pinning strategy ``` **options**: `semver`, `minor`, `major`, `latest-up`, `exact-version`, `no-pin` ``` - [`--pypi-keyring-provider `](#arg---pypi-keyring-provider) : Specifies whether to use the keyring to look up credentials for PyPI ``` **options**: `disabled`, `subprocess` ``` - [`--run-post-link-scripts`](#arg---run-post-link-scripts) : Run post-link scripts (insecure) - [`--tls-no-verify`](#arg---tls-no-verify) : Do not verify the TLS certificate of the server - [`--tls-root-certs `](#arg---tls-root-certs) : Which TLS root certificates to use: 'webpki' (bundled Mozilla roots), 'native' (system store), or 'all' (both) ``` **env**: `PIXI_TLS_ROOT_CERTS` ``` - [`--use-environment-activation-cache`](#arg---use-environment-activation-cache) : Use environment activation cache (experimental) ## Description Remove exposed binaries from the global environment `pixi global expose remove python310 python3 --environment myenv` will remove the exposed names `python310` and `python3` from the environment `myenv` ## Examples ```shell pixi global expose remove python pixi global expose remove py310 python3 ``` # [pixi](../../../) [global](../../) [shortcut](../) add Add a shortcut from an environment to your machine. ## Usage ```text pixi global shortcut add [OPTIONS] --environment [PACKAGE]... ``` ## Arguments - [``](#arg-%3CPACKAGE%3E) : The package name to add the shortcuts from ``` May be provided more than once. ``` ## Options - [`--environment (-e) `](#arg---environment) : The environment from which the shortcut should be added ``` **required**: `true` ``` ## Config Options - [`--auth-file `](#arg---auth-file) : Path to the file containing the authentication token - [`--concurrent-downloads `](#arg---concurrent-downloads) : Max concurrent network requests, default is `50` - [`--concurrent-solves `](#arg---concurrent-solves) : Max concurrent solves, default is the number of CPUs - [`--pinning-strategy `](#arg---pinning-strategy) : Set pinning strategy ``` **options**: `semver`, `minor`, `major`, `latest-up`, `exact-version`, `no-pin` ``` - [`--pypi-keyring-provider `](#arg---pypi-keyring-provider) : Specifies whether to use the keyring to look up credentials for PyPI ``` **options**: `disabled`, `subprocess` ``` - [`--run-post-link-scripts`](#arg---run-post-link-scripts) : Run post-link scripts (insecure) - [`--tls-no-verify`](#arg---tls-no-verify) : Do not verify the TLS certificate of the server - [`--tls-root-certs `](#arg---tls-root-certs) : Which TLS root certificates to use: 'webpki' (bundled Mozilla roots), 'native' (system store), or 'all' (both) ``` **env**: `PIXI_TLS_ROOT_CERTS` ``` - [`--use-environment-activation-cache`](#arg---use-environment-activation-cache) : Use environment activation cache (experimental) # [pixi](../../../) [global](../../) [shortcut](../) remove Remove shortcuts from your machine ## Usage ```text pixi global shortcut remove [OPTIONS] [SHORTCUT]... ``` ## Arguments - [``](#arg-%3CSHORTCUT%3E) : The shortcut that should be removed ``` May be provided more than once. ``` ## Config Options - [`--auth-file `](#arg---auth-file) : Path to the file containing the authentication token - [`--concurrent-downloads `](#arg---concurrent-downloads) : Max concurrent network requests, default is `50` - [`--concurrent-solves `](#arg---concurrent-solves) : Max concurrent solves, default is the number of CPUs - [`--pinning-strategy `](#arg---pinning-strategy) : Set pinning strategy ``` **options**: `semver`, `minor`, `major`, `latest-up`, `exact-version`, `no-pin` ``` - [`--pypi-keyring-provider `](#arg---pypi-keyring-provider) : Specifies whether to use the keyring to look up credentials for PyPI ``` **options**: `disabled`, `subprocess` ``` - [`--run-post-link-scripts`](#arg---run-post-link-scripts) : Run post-link scripts (insecure) - [`--tls-no-verify`](#arg---tls-no-verify) : Do not verify the TLS certificate of the server - [`--tls-root-certs `](#arg---tls-root-certs) : Which TLS root certificates to use: 'webpki' (bundled Mozilla roots), 'native' (system store), or 'all' (both) ``` **env**: `PIXI_TLS_ROOT_CERTS` ``` - [`--use-environment-activation-cache`](#arg---use-environment-activation-cache) : Use environment activation cache (experimental) # [pixi](../../) [task](../) add Add a command to the workspace ## Usage ```text pixi task add [OPTIONS] ... ``` ## Arguments - [``](#arg-%3CNAME%3E) : Task name ``` **required**: `true` ``` - [``](#arg-%3CCOMMAND%3E) : One or more commands to actually execute ``` May be provided more than once. **required**: `true` ``` ## Options - [`--depends-on `](#arg---depends-on) : Depends on these other commands ``` May be provided more than once. ``` - [`--platform (-p) `](#arg---platform) : The platform for which the task should be added - [`--feature (-f) `](#arg---feature) : The feature for which the task should be added - [`--cwd `](#arg---cwd) : The working directory relative to the root of the workspace - [`--env `](#arg---env) : The environment variable to set, use --env key=value multiple times for more than one variable ``` May be provided more than once. ``` - [`--default-environment `](#arg---default-environment) : Add a default environment for the task - [`--description `](#arg---description) : A description of the task to be added - [`--clean-env`](#arg---clean-env) : Isolate the task from the shell environment, and only use the pixi environment to run the task - [`--arg `](#arg---arg) : The arguments to pass to the task ``` May be provided more than once. ``` ## Examples ```shell pixi task add cow cowpy "Hello User" pixi task add tls ls --cwd tests pixi task add test cargo t --depends-on build pixi task add build-osx "METAL=1 cargo build" --platform osx-64 pixi task add train python train.py --feature cuda pixi task add publish-pypi "hatch publish --yes --repo main" --feature build --env HATCH_CONFIG=config/hatch.toml --description "Publish the package to pypi" ``` This adds the following to the [manifest file](../../../../pixi_manifest/): ```toml [tasks] cow = "cowpy \"Hello User\"" tls = { cmd = "ls", cwd = "tests" } test = { cmd = "cargo t", depends-on = ["build"] } [target.osx-64.tasks] build-osx = "METAL=1 cargo build" [feature.cuda.tasks] train = "python train.py" [feature.build.tasks] publish-pypi = { cmd = "hatch publish --yes --repo main", env = { HATCH_CONFIG = "config/hatch.toml" }, description = "Publish the package to pypi" } ``` Which you can then run with the `run` command: ```shell pixi run cow # Extra arguments will be passed to the tasks command. pixi run test --test test1 ``` # [pixi](../../) [task](../) alias Alias another specific command ## Usage ```text pixi task alias [OPTIONS] ... ``` ## Arguments - [``](#arg-%3CALIAS%3E) : Alias name ``` **required**: `true` ``` - [``](#arg-%3CDEPENDS_ON%3E) : Depends on these tasks to execute ``` May be provided more than once. **required**: `true` ``` ## Options - [`--platform (-p) `](#arg---platform) : The platform for which the alias should be added - [`--description `](#arg---description) : The description of the alias task ## Examples ```shell pixi task alias test-all test-py test-cpp test-rust pixi task alias --platform linux-64 test test-linux pixi task alias moo cow ``` # [pixi](../../) [task](../) list List all tasks in the workspace ## Usage ```text pixi task list [OPTIONS] ``` ## Options - [`--summary (-s)`](#arg---summary) : Tasks available for this machine per environment - [`--environment (-e) `](#arg---environment) : The environment the list should be generated for. If not specified, the default environment is used - [`--json`](#arg---json) : List as json instead of a tree If not specified, the default environment is used ## Examples ```shell pixi task list pixi task list --environment cuda pixi task list --summary ``` # [pixi](../../) [task](../) remove Remove a command from the workspace ## Usage ```text pixi task remove [OPTIONS] [TASK_NAME]... ``` ## Arguments - [``](#arg-%3CTASK_NAME%3E) : Task name to remove ``` May be provided more than once. ``` ## Options - [`--platform (-p) `](#arg---platform) : The platform for which the task should be removed - [`--feature (-f) `](#arg---feature) : The feature for which the task should be removed ## Examples ```shell pixi task remove cow pixi task remove --platform linux-64 test pixi task remove --feature cuda task ``` # [pixi](../../) [upload](../) anaconda Options for uploading to a Anaconda.org server ## Usage ```text pixi upload anaconda [OPTIONS] --owner ``` ## Options - [`--owner (-o) `](#arg---owner) : The owner of the distribution (e.g. conda-forge or your username) ``` **required**: `true` **env**: `ANACONDA_OWNER` ``` - [`--channel (-c) `](#arg---channel) : The channel / label to upload the package to (e.g. main / rc) ``` May be provided more than once. **env**: `ANACONDA_CHANNEL` ``` - [`--api-key (-a) `](#arg---api-key) : The Anaconda API key, if none is provided, the token is read from the keychain / auth-file ``` **env**: `ANACONDA_API_KEY` ``` - [`--url (-u) `](#arg---url) : The URL to the Anaconda server ``` **env**: `ANACONDA_SERVER_URL` ``` - [`--force (-f)`](#arg---force) : Replace files on conflict ``` **env**: `ANACONDA_FORCE` ``` # [pixi](../../) [upload](../) artifactory Options for uploading to a Artifactory channel. Authentication is used from the keychain / auth-file ## Usage ```text pixi upload artifactory [OPTIONS] --url --channel ``` ## Options - [`--url (-u) `](#arg---url) : The URL to your Artifactory server ``` **required**: `true` **env**: `ARTIFACTORY_SERVER_URL` ``` - [`--channel (-c) `](#arg---channel) : The URL to your channel ``` **required**: `true` **env**: `ARTIFACTORY_CHANNEL` ``` - [`--token (-t) `](#arg---token) : Your Artifactory token ``` **env**: `ARTIFACTORY_TOKEN` ``` # [pixi](../../) [upload](../) conda-forge Options for uploading to conda-forge ## Usage ```text pixi upload conda-forge [OPTIONS] --staging-token --feedstock --feedstock-token ``` ## Options - [`--staging-token `](#arg---staging-token) : The Anaconda API key ``` **required**: `true` **env**: `STAGING_BINSTAR_TOKEN` ``` - [`--feedstock `](#arg---feedstock) : The feedstock name ``` **required**: `true` **env**: `FEEDSTOCK_NAME` ``` - [`--feedstock-token `](#arg---feedstock-token) : The feedstock token ``` **required**: `true` **env**: `FEEDSTOCK_TOKEN` ``` - [`--staging-channel `](#arg---staging-channel) : The staging channel name ``` **env**: `STAGING_CHANNEL` ``` - [`--anaconda-url `](#arg---anaconda-url) : The Anaconda Server URL ``` **env**: `ANACONDA_SERVER_URL` ``` - [`--validation-endpoint `](#arg---validation-endpoint) : The validation endpoint url ``` **env**: `VALIDATION_ENDPOINT` ``` - [`--provider `](#arg---provider) : The CI provider ``` **env**: `CI` ``` - [`--dry-run`](#arg---dry-run) : Dry run, don't actually upload anything ``` **env**: `DRY_RUN` ``` # [pixi](../../) [upload](../) prefix Options for uploading to a prefix.dev server. Authentication is used from the keychain / auth-file ## Usage ```text pixi upload prefix [OPTIONS] --channel ``` ## Options - [`--url (-u) `](#arg---url) : The URL to the prefix.dev server (only necessary for self-hosted instances) ``` **env**: `PREFIX_SERVER_URL` **default**: `https://prefix.dev` ``` - [`--channel (-c) `](#arg---channel) : The channel to upload the package to ``` **required**: `true` **env**: `PREFIX_CHANNEL` ``` - [`--api-key (-a) `](#arg---api-key) : The prefix.dev API key, if none is provided, the token is read from the keychain / auth-file ``` **env**: `PREFIX_API_KEY` ``` - [`--attestation `](#arg---attestation) : Upload an attestation file alongside the package. Note: if you add an attestation, you can *only* upload a single package. Mutually exclusive with --generate-attestation - [`--generate-attestation`](#arg---generate-attestation) : Automatically generate attestation using cosign in CI. Mutually exclusive with --attestation - [`--store-github-attestation`](#arg---store-github-attestation) : Also store the generated attestation to GitHub's attestation API. Requires `GITHUB_TOKEN` environment variable and only works in GitHub Actions. The attestation will be associated with the current repository - [`--skip-existing (-s)`](#arg---skip-existing) : Skip upload if package already exists - [`--force`](#arg---force) : Force overwrite existing packages # [pixi](../../) [upload](../) quetz Upload to a Quetz server. Authentication is used from the keychain / auth-file ## Usage ```text pixi upload quetz [OPTIONS] --url --channel ``` ## Options - [`--url (-u) `](#arg---url) : The URL to your Quetz server ``` **required**: `true` **env**: `QUETZ_SERVER_URL` ``` - [`--channel (-c) `](#arg---channel) : The URL to your channel ``` **required**: `true` **env**: `QUETZ_CHANNEL` ``` - [`--api-key (-a) `](#arg---api-key) : The Quetz API key, if none is provided, the token is read from the keychain / auth-file ``` **env**: `QUETZ_API_KEY` ``` # [pixi](../../) [upload](../) s3 Options for uploading to S3 ## Usage ```text pixi upload s3 [OPTIONS] --channel ``` ## Options - [`--channel (-c) `](#arg---channel) : The channel URL in the S3 bucket to upload the package to, e.g., `s3://my-bucket/my-channel` ``` **required**: `true` **env**: `S3_CHANNEL` ``` - [`--force`](#arg---force) : Replace files if it already exists ## S3 Credentials - [`--endpoint-url `](#arg---endpoint-url) : The endpoint URL of the S3 backend ``` **env**: `S3_ENDPOINT_URL` ``` - [`--region `](#arg---region) : The region of the S3 backend ``` **env**: `S3_REGION` ``` - [`--access-key-id `](#arg---access-key-id) : The access key ID for the S3 bucket ``` **env**: `S3_ACCESS_KEY_ID` ``` - [`--secret-access-key `](#arg---secret-access-key) : The secret access key for the S3 bucket ``` **env**: `S3_SECRET_ACCESS_KEY` ``` - [`--session-token `](#arg---session-token) : The session token for the S3 bucket ``` **env**: `S3_SESSION_TOKEN` ``` - [`--addressing-style `](#arg---addressing-style) : How to address the bucket ``` **env**: `S3_ADDRESSING_STYLE` **default**: `virtual-host` **options**: `virtual-host`, `path` ``` # [pixi](../../) [workspace](../) channel Commands to manage workspace channels ## Usage ```text pixi workspace channel [OPTIONS] ``` ## Subcommands | Command | Description | | ------------------- | ------------------------------------------------------------ | | [`add`](add/) | Adds a channel to the manifest and updates the lockfile | | [`list`](list/) | List the channels in the manifest | | [`remove`](remove/) | Remove channel(s) from the manifest and updates the lockfile | ## Global Options - [`--manifest-path (-m) `](#arg---manifest-path) : The path to `pixi.toml`, `pyproject.toml`, or the workspace directory - [`--workspace (-w) `](#arg---workspace) : Name of the workspace # [pixi](../../) [workspace](../) description Commands to manage workspace description ## Usage ```text pixi workspace description [OPTIONS] ``` ## Subcommands | Command | Description | | ------------- | ----------------------------- | | [`get`](get/) | Get the workspace description | | [`set`](set/) | Set the workspace description | ## Global Options - [`--manifest-path (-m) `](#arg---manifest-path) : The path to `pixi.toml`, `pyproject.toml`, or the workspace directory - [`--workspace (-w) `](#arg---workspace) : Name of the workspace # [pixi](../../) [workspace](../) environment Commands to manage workspace environments ## Usage ```text pixi workspace environment [OPTIONS] ``` ## Subcommands | Command | Description | | ------------------- | -------------------------------------------- | | [`add`](add/) | Adds an environment to the manifest file | | [`list`](list/) | List the environments in the manifest file | | [`remove`](remove/) | Remove an environment from the manifest file | ## Global Options - [`--manifest-path (-m) `](#arg---manifest-path) : The path to `pixi.toml`, `pyproject.toml`, or the workspace directory - [`--workspace (-w) `](#arg---workspace) : Name of the workspace # [pixi](../../) [workspace](../) export Commands to export workspaces to other formats ## Usage ```text pixi workspace export ``` ## Subcommands | Command | Description | | --------------------------------------------- | ------------------------------------------------------------------- | | [`conda-explicit-spec`](conda-explicit-spec/) | Export workspace environment to a conda explicit specification file | | [`conda-environment`](conda-environment/) | Export workspace environment to a conda environment.yaml file | # [pixi](../../) [workspace](../) feature Commands to manage workspace features ## Usage ```text pixi workspace feature [OPTIONS] ``` ## Subcommands | Command | Description | | ------------------- | --------------------------------------- | | [`list`](list/) | List the features in the manifest file | | [`remove`](remove/) | Remove a feature from the manifest file | ## Global Options - [`--manifest-path (-m) `](#arg---manifest-path) : The path to `pixi.toml`, `pyproject.toml`, or the workspace directory - [`--workspace (-w) `](#arg---workspace) : Name of the workspace # [pixi](../../) [workspace](../) name Commands to manage workspace name ## Usage ```text pixi workspace name [OPTIONS] ``` ## Subcommands | Command | Description | | ------------- | ---------------------- | | [`get`](get/) | Get the workspace name | | [`set`](set/) | Set the workspace name | ## Global Options - [`--manifest-path (-m) `](#arg---manifest-path) : The path to `pixi.toml`, `pyproject.toml`, or the workspace directory - [`--workspace (-w) `](#arg---workspace) : Name of the workspace # [pixi](../../) [workspace](../) platform Commands to manage workspace platforms ## Usage ```text pixi workspace platform [OPTIONS] ``` ## Subcommands | Command | Description | | ------------------- | ------------------------------------------------------------------- | | [`add`](add/) | Adds a platform(s) to the workspace file and updates the lockfile | | [`list`](list/) | List the platforms in the workspace file | | [`remove`](remove/) | Remove platform(s) from the workspace file and updates the lockfile | ## Global Options - [`--manifest-path (-m) `](#arg---manifest-path) : The path to `pixi.toml`, `pyproject.toml`, or the workspace directory - [`--workspace (-w) `](#arg---workspace) : Name of the workspace # [pixi](../../) [workspace](../) register Commands to manage the registry of workspaces. Default command will add a new workspace ## Usage ```text pixi workspace register [OPTIONS] [COMMAND] ``` ## Subcommands | Command | Description | | ------------------- | -------------------------------------------- | | [`list`](list/) | List the registered workspaces | | [`remove`](remove/) | Remove a workspace from registry | | [`prune`](prune/) | Prune disassociated workspaces from registry | ## Options - [`--name (-n) `](#arg---name) : Name of the workspace to register. Defaults to the name of the current workspace - [`--path (-p) `](#arg---path) : Path to register. Defaults to the path to the current workspace - [`--force (-f)`](#arg---force) : Overwrite the workspace entry if the name of the workspace already exists in the registry ## Global Options - [`--manifest-path (-m) `](#arg---manifest-path) : The path to `pixi.toml`, `pyproject.toml`, or the workspace directory - [`--workspace (-w) `](#arg---workspace) : Name of the workspace # [pixi](../../) [workspace](../) requires-pixi Commands to manage the pixi minimum version requirement ## Usage ```text pixi workspace requires-pixi [OPTIONS] ``` ## Subcommands | Command | Description | | ------------------- | ------------------------------------------- | | [`get`](get/) | Get the pixi minimum version requirement | | [`set`](set/) | Set the pixi minimum version requirement | | [`unset`](unset/) | Remove the pixi minimum version requirement | | [`verify`](verify/) | Verify the pixi minimum version requirement | ## Global Options - [`--manifest-path (-m) `](#arg---manifest-path) : The path to `pixi.toml`, `pyproject.toml`, or the workspace directory - [`--workspace (-w) `](#arg---workspace) : Name of the workspace # [pixi](../../) [workspace](../) system-requirements Commands to manage workspace system requirements ## Usage ```text pixi workspace system-requirements [OPTIONS] ``` ## Subcommands | Command | Description | | --------------- | ------------------------------------------ | | [`add`](add/) | Adds an environment to the manifest file | | [`list`](list/) | List the environments in the manifest file | ## Global Options - [`--manifest-path (-m) `](#arg---manifest-path) : The path to `pixi.toml`, `pyproject.toml`, or the workspace directory - [`--workspace (-w) `](#arg---workspace) : Name of the workspace # [pixi](../../) [workspace](../) version Commands to manage workspace version ## Usage ```text pixi workspace version [OPTIONS] ``` ## Subcommands | Command | Description | | ----------------- | ----------------------------------- | | [`get`](get/) | Get the workspace version | | [`set`](set/) | Set the workspace version | | [`major`](major/) | Bump the workspace version to MAJOR | | [`minor`](minor/) | Bump the workspace version to MINOR | | [`patch`](patch/) | Bump the workspace version to PATCH | ## Global Options - [`--manifest-path (-m) `](#arg---manifest-path) : The path to `pixi.toml`, `pyproject.toml`, or the workspace directory - [`--workspace (-w) `](#arg---workspace) : Name of the workspace # [pixi](../../../) [workspace](../../) [channel](../) add Adds a channel to the manifest and updates the lockfile ## Usage ```text pixi workspace channel add [OPTIONS] ... ``` ## Arguments - [``](#arg-%3CCHANNEL%3E) : The channel name or URL ``` May be provided more than once. **required**: `true` ``` ## Options - [`--priority `](#arg---priority) : Specify the channel priority - [`--prepend`](#arg---prepend) : Add the channel(s) to the beginning of the channels list, making them the highest priority - [`--feature (-f) `](#arg---feature) : The name of the feature to modify ## Config Options - [`--auth-file `](#arg---auth-file) : Path to the file containing the authentication token - [`--concurrent-downloads `](#arg---concurrent-downloads) : Max concurrent network requests, default is `50` - [`--concurrent-solves `](#arg---concurrent-solves) : Max concurrent solves, default is the number of CPUs - [`--pinning-strategy `](#arg---pinning-strategy) : Set pinning strategy ``` **options**: `semver`, `minor`, `major`, `latest-up`, `exact-version`, `no-pin` ``` - [`--pypi-keyring-provider `](#arg---pypi-keyring-provider) : Specifies whether to use the keyring to look up credentials for PyPI ``` **options**: `disabled`, `subprocess` ``` - [`--run-post-link-scripts`](#arg---run-post-link-scripts) : Run post-link scripts (insecure) - [`--tls-no-verify`](#arg---tls-no-verify) : Do not verify the TLS certificate of the server - [`--tls-root-certs `](#arg---tls-root-certs) : Which TLS root certificates to use: 'webpki' (bundled Mozilla roots), 'native' (system store), or 'all' (both) ``` **env**: `PIXI_TLS_ROOT_CERTS` ``` - [`--use-environment-activation-cache`](#arg---use-environment-activation-cache) : Use environment activation cache (experimental) ## Update Options - [`--no-install`](#arg---no-install) : Don't modify the environment, only modify the lock-file - [`--frozen`](#arg---frozen) : Install the environment as defined in the lockfile, doesn't update lockfile if it isn't up-to-date with the manifest file ``` **env**: `PIXI_FROZEN` ``` - [`--locked`](#arg---locked) : Check if lockfile is up-to-date before installing the environment, aborts when lockfile isn't up-to-date with the manifest file ``` **env**: `PIXI_LOCKED` ``` # [pixi](../../../) [workspace](../../) [channel](../) list List the channels in the manifest ## Usage ```text pixi workspace channel list [OPTIONS] ``` ## Options - [`--urls`](#arg---urls) : Whether to display the channel's names or urls # [pixi](../../../) [workspace](../../) [channel](../) remove Remove channel(s) from the manifest and updates the lockfile ## Usage ```text pixi workspace channel remove [OPTIONS] ... ``` ## Arguments - [``](#arg-%3CCHANNEL%3E) : The channel name or URL ``` May be provided more than once. **required**: `true` ``` ## Options - [`--priority `](#arg---priority) : Specify the channel priority - [`--prepend`](#arg---prepend) : Add the channel(s) to the beginning of the channels list, making them the highest priority - [`--feature (-f) `](#arg---feature) : The name of the feature to modify ## Config Options - [`--auth-file `](#arg---auth-file) : Path to the file containing the authentication token - [`--concurrent-downloads `](#arg---concurrent-downloads) : Max concurrent network requests, default is `50` - [`--concurrent-solves `](#arg---concurrent-solves) : Max concurrent solves, default is the number of CPUs - [`--pinning-strategy `](#arg---pinning-strategy) : Set pinning strategy ``` **options**: `semver`, `minor`, `major`, `latest-up`, `exact-version`, `no-pin` ``` - [`--pypi-keyring-provider `](#arg---pypi-keyring-provider) : Specifies whether to use the keyring to look up credentials for PyPI ``` **options**: `disabled`, `subprocess` ``` - [`--run-post-link-scripts`](#arg---run-post-link-scripts) : Run post-link scripts (insecure) - [`--tls-no-verify`](#arg---tls-no-verify) : Do not verify the TLS certificate of the server - [`--tls-root-certs `](#arg---tls-root-certs) : Which TLS root certificates to use: 'webpki' (bundled Mozilla roots), 'native' (system store), or 'all' (both) ``` **env**: `PIXI_TLS_ROOT_CERTS` ``` - [`--use-environment-activation-cache`](#arg---use-environment-activation-cache) : Use environment activation cache (experimental) ## Update Options - [`--no-install`](#arg---no-install) : Don't modify the environment, only modify the lock-file - [`--frozen`](#arg---frozen) : Install the environment as defined in the lockfile, doesn't update lockfile if it isn't up-to-date with the manifest file ``` **env**: `PIXI_FROZEN` ``` - [`--locked`](#arg---locked) : Check if lockfile is up-to-date before installing the environment, aborts when lockfile isn't up-to-date with the manifest file ``` **env**: `PIXI_LOCKED` ``` # [pixi](../../../) [workspace](../../) [description](../) get Get the workspace description ## Usage ```text pixi workspace description get ``` ## Description Get the workspace description. Example: `pixi workspace description get` # [pixi](../../../) [workspace](../../) [description](../) set Set the workspace description ## Usage ```text pixi workspace description set ``` ## Arguments - [``](#arg-%3CDESCRIPTION%3E) : The workspace description ``` **required**: `true` ``` ## Description Set the workspace description. Example: `pixi workspace description set "My awesome workspace"` # [pixi](../../../) [workspace](../../) [environment](../) add Adds an environment to the manifest file ## Usage ```text pixi workspace environment add [OPTIONS] ``` ## Arguments - [``](#arg-%3CNAME%3E) : The name of the environment to add ``` **required**: `true` ``` ## Options - [`--feature (-f) `](#arg---feature) : Features to add to the environment ``` May be provided more than once. ``` - [`--solve-group `](#arg---solve-group) : The solve-group to add the environment to - [`--no-default-feature`](#arg---no-default-feature) : Don't include the default feature in the environment ``` **default**: `false` ``` - [`--force`](#arg---force) : Update the manifest even if the environment already exists ``` **default**: `false` ``` # [pixi](../../../) [workspace](../../) [environment](../) list List the environments in the manifest file ## Usage ```text pixi workspace environment list ``` # [pixi](../../../) [workspace](../../) [environment](../) remove Remove an environment from the manifest file ## Usage ```text pixi workspace environment remove ``` ## Arguments - [``](#arg-%3CNAME%3E) : The name of the environment to remove ``` **required**: `true` ``` # [pixi](../../../) [workspace](../../) [export](../) conda-environment Export workspace environment to a conda environment.yaml file ## Usage ```text pixi workspace export conda-environment [OPTIONS] [OUTPUT_PATH] ``` ## Arguments - [``](#arg-%3COUTPUT_PATH%3E) : Explicit path to export the environment file to ## Options - [`--platform (-p) `](#arg---platform) : The platform to render the environment file for. Defaults to the current platform - [`--environment (-e) `](#arg---environment) : The environment to render the environment file for. Defaults to the default environment - [`--name (-n) `](#arg---name) : The name to use for the rendered conda environment. Defaults to the environment name ## Global Options - [`--manifest-path (-m) `](#arg---manifest-path) : The path to `pixi.toml`, `pyproject.toml`, or the workspace directory - [`--workspace (-w) `](#arg---workspace) : Name of the workspace # [pixi](../../../) [workspace](../../) [export](../) conda-explicit-spec Export workspace environment to a conda explicit specification file ## Usage ```text pixi workspace export conda-explicit-spec [OPTIONS] ``` ## Arguments - [``](#arg-%3COUTPUT_DIR%3E) : Output directory for rendered explicit environment spec files ``` **required**: `true` ``` ## Options - [`--environment (-e) `](#arg---environment) : The environments to render. Can be repeated for multiple environments ``` May be provided more than once. ``` - [`--platform (-p) `](#arg---platform) : The platform to render. Can be repeated for multiple platforms. Defaults to all platforms available for selected environments ``` May be provided more than once. ``` - [`--ignore-pypi-errors`](#arg---ignore-pypi-errors) : PyPI dependencies are not supported in the conda explicit spec file ``` **default**: `false` ``` - [`--ignore-source-errors`](#arg---ignore-source-errors) : Source dependencies are not supported in the conda explicit spec file ``` **default**: `false` ``` ## Config Options - [`--auth-file `](#arg---auth-file) : Path to the file containing the authentication token - [`--concurrent-downloads `](#arg---concurrent-downloads) : Max concurrent network requests, default is `50` - [`--concurrent-solves `](#arg---concurrent-solves) : Max concurrent solves, default is the number of CPUs - [`--pinning-strategy `](#arg---pinning-strategy) : Set pinning strategy ``` **options**: `semver`, `minor`, `major`, `latest-up`, `exact-version`, `no-pin` ``` - [`--pypi-keyring-provider `](#arg---pypi-keyring-provider) : Specifies whether to use the keyring to look up credentials for PyPI ``` **options**: `disabled`, `subprocess` ``` - [`--run-post-link-scripts`](#arg---run-post-link-scripts) : Run post-link scripts (insecure) - [`--tls-no-verify`](#arg---tls-no-verify) : Do not verify the TLS certificate of the server - [`--tls-root-certs `](#arg---tls-root-certs) : Which TLS root certificates to use: 'webpki' (bundled Mozilla roots), 'native' (system store), or 'all' (both) ``` **env**: `PIXI_TLS_ROOT_CERTS` ``` - [`--use-environment-activation-cache`](#arg---use-environment-activation-cache) : Use environment activation cache (experimental) ## Update Options - [`--frozen`](#arg---frozen) : Install the environment as defined in the lockfile, doesn't update lockfile if it isn't up-to-date with the manifest file ``` **env**: `PIXI_FROZEN` ``` - [`--locked`](#arg---locked) : Check if lockfile is up-to-date before installing the environment, aborts when lockfile isn't up-to-date with the manifest file ``` **env**: `PIXI_LOCKED` ``` - [`--no-install`](#arg---no-install) : Don't modify the environment, only modify the lock-file ## Global Options - [`--manifest-path (-m) `](#arg---manifest-path) : The path to `pixi.toml`, `pyproject.toml`, or the workspace directory - [`--workspace (-w) `](#arg---workspace) : Name of the workspace # [pixi](../../../) [workspace](../../) [feature](../) list List the features in the manifest file ## Usage ```text pixi workspace feature list ``` # [pixi](../../../) [workspace](../../) [feature](../) remove Remove a feature from the manifest file ## Usage ```text pixi workspace feature remove ``` ## Arguments - [``](#arg-%3CFEATURE%3E) : The name of the feature to remove ``` **required**: `true` ``` # [pixi](../../../) [workspace](../../) [name](../) get Get the workspace name ## Usage ```text pixi workspace name get ``` # [pixi](../../../) [workspace](../../) [name](../) set Set the workspace name ## Usage ```text pixi workspace name set ``` ## Arguments - [``](#arg-%3CNAME%3E) : The workspace name, please only use lowercase letters (a-z), digits (0-9), hyphens (-), and underscores (\_) ``` **required**: `true` ``` ## Description Set the workspace name. Example: `pixi workspace name set "my-workspace"` # [pixi](../../../) [workspace](../../) [platform](../) add Adds a platform(s) to the workspace file and updates the lockfile ## Usage ```text pixi workspace platform add [OPTIONS] ... ``` ## Arguments - [``](#arg-%3CPLATFORM%3E) : The platform name(s) to add ``` May be provided more than once. **required**: `true` ``` ## Options - [`--no-install`](#arg---no-install) : Don't update the environment, only add changed packages to the lock-file - [`--feature (-f) `](#arg---feature) : The name of the feature to add the platform to # [pixi](../../../) [workspace](../../) [platform](../) list List the platforms in the workspace file ## Usage ```text pixi workspace platform list ``` # [pixi](../../../) [workspace](../../) [platform](../) remove Remove platform(s) from the workspace file and updates the lockfile ## Usage ```text pixi workspace platform remove [OPTIONS] ... ``` ## Arguments - [``](#arg-%3CPLATFORM%3E) : The platform name to remove ``` May be provided more than once. **required**: `true` ``` ## Options - [`--no-install`](#arg---no-install) : Don't update the environment, only remove the platform(s) from the lock-file - [`--feature (-f) `](#arg---feature) : The name of the feature to remove the platform from # [pixi](../../../) [workspace](../../) [register](../) list List the registered workspaces ## Usage ```text pixi workspace register list [OPTIONS] ``` ## Options - [`--json`](#arg---json) : Output in JSON format # [pixi](../../../) [workspace](../../) [register](../) prune Prune disassociated workspaces from registry ## Usage ```text pixi workspace register prune ``` # [pixi](../../../) [workspace](../../) [register](../) remove Remove a workspace from registry ## Usage ```text pixi workspace register remove ``` ## Arguments - [``](#arg-%3CNAME%3E) : Name of the workspace to unregister ``` **required**: `true` ``` # [pixi](../../../) [workspace](../../) [requires-pixi](../) get Get the pixi minimum version requirement ## Usage ```text pixi workspace requires-pixi get ``` # [pixi](../../../) [workspace](../../) [requires-pixi](../) set Set the pixi minimum version requirement ## Usage ```text pixi workspace requires-pixi set ``` ## Arguments - [``](#arg-%3CVERSION%3E) : The required pixi version ``` **required**: `true` ``` ## Description Set the pixi minimum version requirement. Example: `pixi workspace pixi-minimum set 0.42` # [pixi](../../../) [workspace](../../) [requires-pixi](../) unset Remove the pixi minimum version requirement ## Usage ```text pixi workspace requires-pixi unset ``` # [pixi](../../../) [workspace](../../) [requires-pixi](../) verify Verify the pixi minimum version requirement ## Usage ```text pixi workspace requires-pixi verify ``` # [pixi](../../../) [workspace](../../) [system-requirements](../) add Adds an environment to the manifest file ## Usage ```text pixi workspace system-requirements add [OPTIONS] ``` ## Arguments - [``](#arg-%3CREQUIREMENT%3E) : The name of the system requirement to add ``` **required**: `true` **options**: `linux`, `cuda`, `macos`, `glibc`, `other-libc` ``` - [``](#arg-%3CVERSION%3E) : The version of the requirement ``` **required**: `true` ``` ## Options - [`--family `](#arg---family) : The Libc family, this can only be specified for requirement `other-libc` - [`--feature (-f) `](#arg---feature) : The name of the feature to modify # [pixi](../../../) [workspace](../../) [system-requirements](../) list List the environments in the manifest file ## Usage ```text pixi workspace system-requirements list [OPTIONS] ``` ## Options - [`--json`](#arg---json) : List the system requirements in JSON format - [`--environment (-e) `](#arg---environment) : The environment to list the system requirements for # [pixi](../../../) [workspace](../../) [version](../) get Get the workspace version ## Usage ```text pixi workspace version get ``` # [pixi](../../../) [workspace](../../) [version](../) major Bump the workspace version to MAJOR ## Usage ```text pixi workspace version major ``` # [pixi](../../../) [workspace](../../) [version](../) minor Bump the workspace version to MINOR ## Usage ```text pixi workspace version minor ``` # [pixi](../../../) [workspace](../../) [version](../) patch Bump the workspace version to PATCH ## Usage ```text pixi workspace version patch ``` # [pixi](../../../) [workspace](../../) [version](../) set Set the workspace version ## Usage ```text pixi workspace version set ``` ## Arguments - [``](#arg-%3CVERSION%3E) : The new workspace version ``` **required**: `true` ``` # Miscellaneous documentation # Changelog All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). ### [0.66.0] - 2026-03-16 #### ✨ Highlights Want a `conda`/`mamba` like workflow for Pixi workspaces? This release brings registered workspaces! You can now register your Pixi workspace and then use its name to refer to it from anywhere on your machine. For example: ```shell cd path/to/a/pixi/workspace pixi workspace register cd pixi run --workspace workspace-name task-name pixi shell -w workspace-name pixi shell-hook -w workspace-name ``` You can also specify `constraints` for packages that may be part of your environment without explicitly requiring them (similar to `run_constraints` for Conda packages): ```toml [constraints] openssl = ">=3" ``` #### Added - Add `constraints` to limit dependency versions by @delsner in [#5603](https://github.com/prefix-dev/pixi/pull/5603) - `pixi search` improvements: allow arbitrary MatchSpecs, add `--json` by @pavelzw in [#5442](https://github.com/prefix-dev/pixi/pull/5442) - Add atomic write utilities for safe file operations by @baszalmstra in [#5500](https://github.com/prefix-dev/pixi/pull/5500) - Support `--` separator to pass extra args to typed-arg tasks by @ruben-arts in [#5569](https://github.com/prefix-dev/pixi/pull/5569) - Add template args for env vars in tasks as well by @tdejager in [#5613](https://github.com/prefix-dev/pixi/pull/5613) - Allow users to use Pixi named workspaces through a registry by @soapy1 in [#5277](https://github.com/prefix-dev/pixi/pull/5277) - Add `pyproject.toml` schema by @bollwyvl in [#5583](https://github.com/prefix-dev/pixi/pull/5583) #### Documentation - Add `pixi-browse` by @pavelzw in [#5642](https://github.com/prefix-dev/pixi/pull/5642) and [#5664](https://github.com/prefix-dev/pixi/pull/5664) - Rewrite docs page on lock file by @VeckoTheGecko in [#5404](https://github.com/prefix-dev/pixi/pull/5404) - Fix pixi-build docs about uv in installer selection by @kilian-hu in [#5670](https://github.com/prefix-dev/pixi/pull/5670) - Add prefix.dev docs to deployment by @wolfv in [#5671](https://github.com/prefix-dev/pixi/pull/5671) - Fix typo in pyproject.toml setup documentation by @LiamConnors in [#5620](https://github.com/prefix-dev/pixi/pull/5620) #### Fixed - Allow to solve environments with different platforms in the same solve group by @borchero in [#5538](https://github.com/prefix-dev/pixi/pull/5538) - Race condition with error coalescing by @baszalmstra in [#5591](https://github.com/prefix-dev/pixi/pull/5591) - Support implicit table syntax in pyproject.toml parsing by @suleman1412 in [#5580](https://github.com/prefix-dev/pixi/pull/5580) - Updated `aws-lc-sys` to 0.38.0 by @baszalmstra in [#5610](https://github.com/prefix-dev/pixi/pull/5610) - Hash computation in release by @wolfv in [#5605](https://github.com/prefix-dev/pixi/pull/5605) - Editability check during pypi install by @tdejager in [#5617](https://github.com/prefix-dev/pixi/pull/5617) - Avoid panic when current working directory no longer exists by @mohitdebian in [#5652](https://github.com/prefix-dev/pixi/pull/5652) - Cache file path corruption when package name contains dots by @ytausch in [#5668](https://github.com/prefix-dev/pixi/pull/5668) - `pixi clean` behavior improvements by @ruben-arts in [#5685](https://github.com/prefix-dev/pixi/pull/5685) - Use `mp.suspend` for `pixi_progress::println!` by @lucascolley in [#5459](https://github.com/prefix-dev/pixi/pull/5459) #### New Contributors - @soapy1 made their first contribution in [#5277](https://github.com/prefix-dev/pixi/pull/5277) - @mohitdebian made their first contribution in [#5652](https://github.com/prefix-dev/pixi/pull/5652) - @suleman1412 made their first contribution in [#5580](https://github.com/prefix-dev/pixi/pull/5580) ### [0.65.0] - 2026-02-26 #### ✨ Highlights We're now properly signing our own Windows binaries resulting in no errors from the "smart screen". #### Added - Add list_packages for `pixi-gui` by @haecker-felix in [#4930](https://github.com/prefix-dev/pixi/pull/4930) - Add `choices` to tasks args, with arg validation by @Hofer-Julian in [#5543](https://github.com/prefix-dev/pixi/pull/5543) - Build new trampoline binaries with signing, integrate windows signing by @wolfv in [#5523](https://github.com/prefix-dev/pixi/pull/5523) - Add `--json` flag to `pixi global list` by @Hofer-Julian in [#5530](https://github.com/prefix-dev/pixi/pull/5530) #### Documentation - Improve sidebar rendering by @Hofer-Julian in [#5550](https://github.com/prefix-dev/pixi/pull/5550) - Improve documentation for shell completions by @pavelzw in [#5546](https://github.com/prefix-dev/pixi/pull/5546) #### Fixed - `tool.pixi.pypi-options.no-build = true` in combination with `--locked` by @hameerabbasi in [#5554](https://github.com/prefix-dev/pixi/pull/5554) ### [0.64.0] - 2026-02-23 #### ✨ Highlights Big release with lots of different fixes and small features, but no overarching theme this time. #### Added - Add `--dry-run` flag to `pixi lock` command by @akshatsrivastava11 in [#5288](https://github.com/prefix-dev/pixi/pull/5288) - Add `--executable` flag to `pixi run` by @kajal-jotwani in [#5253](https://github.com/prefix-dev/pixi/pull/5253) - `pixi workspace export conda-environment` handles env variables by @SrisharanVS in [#5425](https://github.com/prefix-dev/pixi/pull/5425) - Add `--templated` flag to `pixi run` by @pavelzw in [#5489](https://github.com/prefix-dev/pixi/pull/5489) - Add `{{ pixi.init_cwd }}` template variable for task inputs/outputs by @Premkumar-2004 in [#5505](https://github.com/prefix-dev/pixi/pull/5505) #### Documentation - ROS2 tutorial commands for building C++ nodes by @wjwwood in [#5320](https://github.com/prefix-dev/pixi/pull/5320) - Clarify which installation method to use for local development by @Hofer-Julian in [#5392](https://github.com/prefix-dev/pixi/pull/5392) - Task default-environment field by @JeppeKlitgaard in [#5400](https://github.com/prefix-dev/pixi/pull/5400) - Fix some minor typos by @kurtmckee in [#5427](https://github.com/prefix-dev/pixi/pull/5427) - Extend setup-pixi documentation with working-directory by @pavelzw in [#5416](https://github.com/prefix-dev/pixi/pull/5416) - Add snakedown to community list by @savente93 in [#5436](https://github.com/prefix-dev/pixi/pull/5436) - Small typo fix by @zuble in [#5460](https://github.com/prefix-dev/pixi/pull/5460) - Add Artifactory documentation by @pavelzw in [#5451](https://github.com/prefix-dev/pixi/pull/5451) - Add `pixi-skills` extension by @pavelzw in [#5471](https://github.com/prefix-dev/pixi/pull/5471) - Document `description` field for tasks by @VeckoTheGecko in [#5479](https://github.com/prefix-dev/pixi/pull/5479) - Explain de-duplication via hard links and reflinks by @Hofer-Julian in [#5485](https://github.com/prefix-dev/pixi/pull/5485) - Mention `bun` in available software by @pavelzw in [#5496](https://github.com/prefix-dev/pixi/pull/5496) - Add Xarray and Parcels by @VeckoTheGecko in [#5499](https://github.com/prefix-dev/pixi/pull/5499) - Pin `click` package by @Hofer-Julian in [#5532](https://github.com/prefix-dev/pixi/pull/5532) - Fix typo by @pavelzw in [#5533](https://github.com/prefix-dev/pixi/pull/5533) #### Fixed - Fish shell integration is broken on older version of fish by @tdejager in [#5225](https://github.com/prefix-dev/pixi/pull/5225) - Extend catch_unwind to cover lock_pypi_packages for proper panic handling by @nichmor in [#5324](https://github.com/prefix-dev/pixi/pull/5324) - Skip license-file validation when build.source is git or URL by @baszalmstra in [#4994](https://github.com/prefix-dev/pixi/pull/4994) - Adjust license file paths for subdirectory manifests by @nichmor in [#5327](https://github.com/prefix-dev/pixi/pull/5327) - Changing `package.build.config` does not invalidate caches by @baszalmstra in [#5371](https://github.com/prefix-dev/pixi/pull/5371) - Add back `is_explicit` to `pixi list --json` by @renan-r-santos in [#5391](https://github.com/prefix-dev/pixi/pull/5391) - Installing mallformed wheels by @nichmor in [#5387](https://github.com/prefix-dev/pixi/pull/5387) - Indicate pixi self-update in requires-pixi error message by @varun-kht in [#5399](https://github.com/prefix-dev/pixi/pull/5399) - Prevent package updates when appending channels by @benmoss in [#5405](https://github.com/prefix-dev/pixi/pull/5405) - Add `compiler(c)` per default with `pixi-build-rust` by @Hofer-Julian in [#5457](https://github.com/prefix-dev/pixi/pull/5457) - Ignore `PIXI_` env vars when --manifest-path is different to `PIXI_PROJECT_ROOT` by @Hofer-Julian in [#5441](https://github.com/prefix-dev/pixi/pull/5441) - Deadlock for duplicate packages from different sources by @baszalmstra in [#5447](https://github.com/prefix-dev/pixi/pull/5447) - Reuse existing `tool.pixi.feature.pypi-dependencies` table by @Premkumar-2004 in [#5504](https://github.com/prefix-dev/pixi/pull/5504) - Follow symlinks to directories in glob pattern matching by @baszalmstra in [#5502](https://github.com/prefix-dev/pixi/pull/5502) #### New Contributors - @Premkumar-2004 made their first contribution in [#5505](https://github.com/prefix-dev/pixi/pull/5505) - @zuble made their first contribution in [#5460](https://github.com/prefix-dev/pixi/pull/5460) - @SrisharanVS made their first contribution in [#5425](https://github.com/prefix-dev/pixi/pull/5425) - @kurtmckee made their first contribution in [#5427](https://github.com/prefix-dev/pixi/pull/5427) - @benmoss made their first contribution in [#5405](https://github.com/prefix-dev/pixi/pull/5405) - @varun-kht made their first contribution in [#5399](https://github.com/prefix-dev/pixi/pull/5399) - @kajal-jotwani made their first contribution in [#5253](https://github.com/prefix-dev/pixi/pull/5253) - @JeppeKlitgaard made their first contribution in [#5400](https://github.com/prefix-dev/pixi/pull/5400) - @wjwwood made their first contribution in [#5320](https://github.com/prefix-dev/pixi/pull/5320) - @akshatsrivastava11 made their first contribution in [#5288](https://github.com/prefix-dev/pixi/pull/5288) ### [0.63.2] - 2026-01-19 #### ✨ Highlights This release brings important fixes for Pixi Build and PyPI support. #### Documentation - Update CHANGELOG.md to remove duplicated introduction by @ickc in [#5308](https://github.com/prefix-dev/pixi/pull/5308) - Describe git support for package source by @Hofer-Julian in [#5314](https://github.com/prefix-dev/pixi/pull/5314) #### Fixed - Dont check run-exports for source dependencies by @baszalmstra in [#5302](https://github.com/prefix-dev/pixi/pull/5302) - Loading of uv certificates by @tdejager in [#5313](https://github.com/prefix-dev/pixi/pull/5313) - Downstream tests by @Hofer-Julian in [#5316](https://github.com/prefix-dev/pixi/pull/5316) #### Refactor - The uv client to be created in a single place by @tdejager in [#5311](https://github.com/prefix-dev/pixi/pull/5311) #### New Contributors - @ickc made their first contribution in [#5308](https://github.com/prefix-dev/pixi/pull/5308) ### [0.63.1] - 2026-01-15 #### ✨ Highlights Yes, a patch release the day after looks like we messed up the last release, but we really just wanted to get these fixes out πŸ™ƒ #### Fixed - An issue with source-interdependencies and dev packages by @wolfv in [#5292](https://github.com/prefix-dev/pixi/pull/5292) - Retain `build.source` spec in lock-file for relative paths by @baszalmstra in [#5247](https://github.com/prefix-dev/pixi/pull/5247) ### [0.63.0] - 2026-01-14 #### ✨ Highlights Pixi now supports [PEP508 environment markers](https://peps.python.org/pep-0508/#environment-markers) for PyPI dependencies. Tasks can specify a `default_environment`, making it easier to run tasks without explicitly selecting an environment. Error messages become more readable with syntax highlighting in error reports. As usual this release also includes a lot of bug fixes. This version introduces a breaking chance in the communication protocol between build backends and pixi. New versions of the build backends that support this protocol have been released but if you pin your build backends to an older version you might encounter an error. Updating the version constraints of your build backend will fix this. #### Added - `default_environment` option for specifying the default environment for a task by @prady0t in [#5164](https://github.com/prefix-dev/pixi/pull/5164) - Add set_channels() to WorkspaceContext by @haecker-felix in [#5172](https://github.com/prefix-dev/pixi/pull/5172) - Expose PIXI_VERSION const by @haecker-felix in [#5232](https://github.com/prefix-dev/pixi/pull/5232) - Add arborium syntax highlighting to miette error reporting by @Hofer-Julian in [#5231](https://github.com/prefix-dev/pixi/pull/5231) - Source records nameless match spec by @baszalmstra in [#5103](https://github.com/prefix-dev/pixi/pull/5103) - Fix installation reading editable from the lock incorrectly by @tdejager in [#5249](https://github.com/prefix-dev/pixi/pull/5249) - Support PEP508 environment markers by @hameerabbasi in [#5241](https://github.com/prefix-dev/pixi/pull/5241) #### Documentation - Add section on pinned package conflicts in conda and PyPI integration by @maurosilber in [#5217](https://github.com/prefix-dev/pixi/pull/5217) - Explain the matchspec and source spec by @ruben-arts in [#5224](https://github.com/prefix-dev/pixi/pull/5224) - Improve system requirements documentation clarity by @Hofer-Julian in [#5264](https://github.com/prefix-dev/pixi/pull/5264) #### Fixed - Hover color on footer links by @ruben-arts in [#5189](https://github.com/prefix-dev/pixi/pull/5189) - `pixi lock` backend override by @nichmor in [#5179](https://github.com/prefix-dev/pixi/pull/5179) - Reporter context retrieval by @ruben-arts in [#5202](https://github.com/prefix-dev/pixi/pull/5202) - Stale metadata when pointing to file by @nichmor in [#5203](https://github.com/prefix-dev/pixi/pull/5203) - Improve python version specifier handling in pypi.rs by @ruben-arts in [#5211](https://github.com/prefix-dev/pixi/pull/5211) - Correct admonition on pixi_manifest page by @claudiushaag in [#5252](https://github.com/prefix-dev/pixi/pull/5252) - Fix freeze and update examples by @baszalmstra in [#5255](https://github.com/prefix-dev/pixi/pull/5255) - Use latest versions of build backends by @baszalmstra in [#5258](https://github.com/prefix-dev/pixi/pull/5258) - Move retry middleware to the front by @pavelzw in [#5257](https://github.com/prefix-dev/pixi/pull/5257) - Use new uv caching mechanism to determine freshness by @tdejager in [#5254](https://github.com/prefix-dev/pixi/pull/5254) - Change `TlsRootCerts` to select `All` by default by @tdejager in [#5244](https://github.com/prefix-dev/pixi/pull/5244) - Recognize incompatible python wheels by @hunger in [#5273](https://github.com/prefix-dev/pixi/pull/5273) - Preserve branch reference by @nichmor in [#5215](https://github.com/prefix-dev/pixi/pull/5215) - Operation was cancelled error by @baszalmstra in [#5287](https://github.com/prefix-dev/pixi/pull/5287) - Comparison of None in git source subdir vs empty string by @wolfv in [#5269](https://github.com/prefix-dev/pixi/pull/5269) #### Style - Docs/ polish by @hunger in [#5234](https://github.com/prefix-dev/pixi/pull/5234) #### New Contributors - @hunger made their first contribution in [#5273](https://github.com/prefix-dev/pixi/pull/5273) - @claudiushaag made their first contribution in [#5252](https://github.com/prefix-dev/pixi/pull/5252) ### [0.62.2] - 2025-12-22 #### ✨ Highlights This is a small patch release fixing issues with source packages and caching. #### Fixed - Include variants when calculating cache key by @nichmor in [#5167](https://github.com/prefix-dev/pixi/pull/5167) - Source packages with git source were always out-of-date by @baszalmstra in [#5178](https://github.com/prefix-dev/pixi/pull/5178) ### [0.62.1] - 2025-12-18 #### ✨ Highlights Small release with fixes related to the conda source dependencies. #### Added - Resolving PyPI deps with a `SourceRecord` Python by @lucascolley in [#5159](https://github.com/prefix-dev/pixi/pull/5159) - Refactor pixi pypi spec by @tdejager in [#5155](https://github.com/prefix-dev/pixi/pull/5155) #### Documentation - Add `dev` table documentation by @ruben-arts in [#5163](https://github.com/prefix-dev/pixi/pull/5163) #### Fixed - Let `pixi run` or `pixi install` fail on unsupported platforms by @Hofer-Julian in [#5141](https://github.com/prefix-dev/pixi/pull/5141) - Include dev dependencies when extracting packages from solve groups by @baszalmstra in [#5156](https://github.com/prefix-dev/pixi/pull/5156) - Update lock-file on change by @baszalmstra in [#5158](https://github.com/prefix-dev/pixi/pull/5158) ### [0.62.0] - 2025-12-17 #### ✨ Highlights Do you need all the build/host/run dependencies of a package? Now you can add source packages to the `[dev]` table to get them all at once without installing the package itself. ```toml [dev] my-package = { path = "src" } ``` #### Breaking change for `pixi-build` preview This release removes the input hashes from the lockfile for source dependencies to reduce unnecessary lockfile changes. This may cause some lockfiles with source dependencies to become invalid. Rerun `pixi lock` to fix the lockfile. The changes in this release should significantly reduce lockfile churn when working with source packages going forward. #### Added - Add cache path in the error by @nichmor in [#5091](https://github.com/prefix-dev/pixi/pull/5091) - Add `feature` CLI commands and add remove_feature to pixi_api by @haecker-felix in [#5086](https://github.com/prefix-dev/pixi/pull/5086) - Stop recording PyPI `editable` in lockfile by @tdejager in [#5106](https://github.com/prefix-dev/pixi/pull/5106) - Add `--fields` argument to `pixi list` by @baszalmstra in [#5105](https://github.com/prefix-dev/pixi/pull/5105) - Add `-m` short alias for manifest_path option by @paugier in [#5066](https://github.com/prefix-dev/pixi/pull/5066) - Add description / channel / platform functionality by @haecker-felix in [#5107](https://github.com/prefix-dev/pixi/pull/5107) - Add `[dev]` dependencies by @baszalmstra in [#4778](https://github.com/prefix-dev/pixi/pull/4778) - Remove `input.hash` from the lockfile by @nichmor [#5011](https://github.com/prefix-dev/pixi/pull/5011) #### Documentation - Add documentation for RATTLER_AUTH_FILE environment variable by @Hofer-Julian in [#5116](https://github.com/prefix-dev/pixi/pull/5116) - Add imprint and privacy policy by @wolfv in [#5120](https://github.com/prefix-dev/pixi/pull/5120) - Improve platforms clarity by @ruben-arts in [#5133](https://github.com/prefix-dev/pixi/pull/5133) #### Fixed - Exclude reserved names from task arg names in schema by @bollwyvl in [#5078](https://github.com/prefix-dev/pixi/pull/5078) - Change binary to source should always select source by @baszalmstra in [#5098](https://github.com/prefix-dev/pixi/pull/5098) - Handle empty dirs when `global install bla` fails by @mrswastik-robot in [#4860](https://github.com/prefix-dev/pixi/pull/4860) - Enhance feature removal confirmation message by @Hofer-Julian in [#5115](https://github.com/prefix-dev/pixi/pull/5115) - Use global config tls setting with `self-update` by @tdejager in [#5119](https://github.com/prefix-dev/pixi/pull/5119) - Mark more tests as online by @baszalmstra in [#5104](https://github.com/prefix-dev/pixi/pull/5104) - DAQ passthrough by @TheSkyentist in [#5126](https://github.com/prefix-dev/pixi/pull/5126) - Enforce github actions security with zizmor by @Hofer-Julian in [#5134](https://github.com/prefix-dev/pixi/pull/5134) - Accidentally always compiling for rustls by @tdejager in [#5132](https://github.com/prefix-dev/pixi/pull/5132) - Zizmor medium severity lints by @Hofer-Julian in [#5144](https://github.com/prefix-dev/pixi/pull/5144) #### Refactor - Sync "pixi workspace feature remove" behaviour with "pixi remove" by @haecker-felix in [#5129](https://github.com/prefix-dev/pixi/pull/5129) - Bumping up to rust v1.90 by @prady0t in [#5112](https://github.com/prefix-dev/pixi/pull/5112) #### New Contributors - @prady0t made their first contribution in [#5112](https://github.com/prefix-dev/pixi/pull/5112) - @TheSkyentist made their first contribution in [#5126](https://github.com/prefix-dev/pixi/pull/5126) ### [0.61.0] - 2025-12-09 #### ✨ Highlights This Pixi release features a new and improved `pixi upload` functionality, that is shared with `rattler-build` through `rattler`. #### Changed - Add list_environments, add_environment, remove_environment to Pixi API by @haecker-felix in [#4918](https://github.com/prefix-dev/pixi/pull/4918) - Optimize git checkouts in pypi tests by @baszalmstra in [#5035](https://github.com/prefix-dev/pixi/pull/5035) - Use local git fixtures for tests by @baszalmstra in [#5047](https://github.com/prefix-dev/pixi/pull/5047) - Optimize pypi add tests by @baszalmstra in [#5048](https://github.com/prefix-dev/pixi/pull/5048) - Allow loading of native certificate store by @tdejager in [#5013](https://github.com/prefix-dev/pixi/pull/5013) - New rattler-upload functionality by @tdejager in [#5017](https://github.com/prefix-dev/pixi/pull/5017) - Optimize integration tests to use local fixtures by @baszalmstra in [#5064](https://github.com/prefix-dev/pixi/pull/5064) #### Fixed - Mark more tests as `online_tests` by @mgorny in [#5060](https://github.com/prefix-dev/pixi/pull/5060) - Use absolute_path() when computing workspace root to preserve symlinks by @claydugo in [#5059](https://github.com/prefix-dev/pixi/pull/5059) - Index was being ignored during upgrades by @tdejager in [#5062](https://github.com/prefix-dev/pixi/pull/5062) - Use single quotes for CLI arg joining to fix backslash escaping by @baszalmstra in [#5063](https://github.com/prefix-dev/pixi/pull/5063) - Don't assume that shell config file ends on newline by @MikkelSchubert in [#4873](https://github.com/prefix-dev/pixi/pull/4873) - Fix docs-dev post setup-pixi run by @ruben-arts in [#5088](https://github.com/prefix-dev/pixi/pull/5088) - Mark `test_add_url_no_channel` as slow by @Hofer-Julian in [#5093](https://github.com/prefix-dev/pixi/pull/5093) #### New Contributors - @MikkelSchubert made their first contribution in [#4873](https://github.com/prefix-dev/pixi/pull/4873) ### [0.60.0] - 2025-12-03 #### ✨ Highlights This release, our first in a month, brings a massive amount of changes and improvements. Pixi Build continues to get more powerful and stable with every iteration. We especially focused on making development with ROS and the broader robotics ecosystem as smooth as possible. Finally, this release contains a lot of bug fixes and documentation improvements, often driven by our amazing community 🫢 #### Changed - Add more variables to task context by @baszalmstra in [#4949](https://github.com/prefix-dev/pixi/pull/4949) - Improve `pixi list` description by @ShalokShalom in [#4852](https://github.com/prefix-dev/pixi/pull/4852) - Fix pixi exec example by @pavelzw in [#4868](https://github.com/prefix-dev/pixi/pull/4868) - Bump pixi-build-api-version to 3 for unique variant guarantees by @baszalmstra in [#4900](https://github.com/prefix-dev/pixi/pull/4900) - Gracefully handle newer lock-file versions by @baszalmstra in [#4897](https://github.com/prefix-dev/pixi/pull/4897) - Expose manifest features by @haecker-felix in [#4876](https://github.com/prefix-dev/pixi/pull/4876) - Consume `package.xml` manifest for ROS by @remimimimimi in [#4820](https://github.com/prefix-dev/pixi/pull/4820) - Implement package search by @haecker-felix in [#4910](https://github.com/prefix-dev/pixi/pull/4910) - Add PIXI_DOWNLOAD_URL to use install scripts in private network by @millsks in [#4942](https://github.com/prefix-dev/pixi/pull/4942) - Accept relative paths in `pixi exec` by @tdejager in [#4945](https://github.com/prefix-dev/pixi/pull/4945) - Improve authentication handling and credential masking by @millsks in [#4948](https://github.com/prefix-dev/pixi/pull/4948) - Insecure tls by @jamesfricker in [#4067](https://github.com/prefix-dev/pixi/pull/4067) - Resolve `~` in `config.detached_environments` by @MartinJepsen in [#4968](https://github.com/prefix-dev/pixi/pull/4968) - Allow setting pixi binary install dir separately by @AntoinePrv in [#4978](https://github.com/prefix-dev/pixi/pull/4978) - Implement pypi pre-release support by @tdejager in [#4984](https://github.com/prefix-dev/pixi/pull/4984) - Add add_conda_deps / add_pypi_deps / remove_conda_deps / remove_pypi_deps by @haecker-felix in [#4915](https://github.com/prefix-dev/pixi/pull/4915) #### Documentation - Add SciPy to community pages by @lucascolley in [#4923](https://github.com/prefix-dev/pixi/pull/4923) - Fix typo in `readthedocs-override` example by @jtpio in [#4957](https://github.com/prefix-dev/pixi/pull/4957) - `project` -> `workspace` in docs by @Dashlander in [#4921](https://github.com/prefix-dev/pixi/pull/4921) - Fix rendering of Rust tutorial by @ShalokShalom in [#4859](https://github.com/prefix-dev/pixi/pull/4859) - Fix typos by @pavelzw in [#4887](https://github.com/prefix-dev/pixi/pull/4887) - Fix typos and grammar errors by @Zachanardo in [#4966](https://github.com/prefix-dev/pixi/pull/4966) - Fix pixi s3 auth example text by @trent-abc in [#5002](https://github.com/prefix-dev/pixi/pull/5002) #### Fixed - Out-of-tree satisfiability fixed by @tdejager in [#4872](https://github.com/prefix-dev/pixi/pull/4872) - Dont ignore build folder in command_dispatcher by @tdejager in [#4855](https://github.com/prefix-dev/pixi/pull/4855) - Solve build source relative to the manifest path by @nichmor in [#4863](https://github.com/prefix-dev/pixi/pull/4863) - Git source lockfile invalidation by @remimimimimi in [#4874](https://github.com/prefix-dev/pixi/pull/4874) - Git dependency updates triggered erroneously by @nichmor in [#4858](https://github.com/prefix-dev/pixi/pull/4858) - Recursive optional dependencies and solve groups infinite loop by @tdejager in [#4890](https://github.com/prefix-dev/pixi/pull/4890) - Ensure `.pixi/.gitignore` is created during `pixi build` by @baszalmstra in [#4884](https://github.com/prefix-dev/pixi/pull/4884) - More descriptive message for tokio panics by @nichmor in [#4893](https://github.com/prefix-dev/pixi/pull/4893) - Task cache dependency issue by @nichmor in [#4898](https://github.com/prefix-dev/pixi/pull/4898) - Disable diff driver for pixi lock in generated `.gitattributes` by @h-vetinari in [#4913](https://github.com/prefix-dev/pixi/pull/4913) - Create separate workdir per variant by @nichmor in [#4934](https://github.com/prefix-dev/pixi/pull/4934) - Fix logging panic by converting itertools::Format to string before passing to tracing by @haecker-felix in [#4938](https://github.com/prefix-dev/pixi/pull/4938) - Solve false positive `ChannelPriorityCombinationError` by @MartinJepsen in [#4943](https://github.com/prefix-dev/pixi/pull/4943) - Increase timeout for Windows x86_64 test job by @baszalmstra in [#4955](https://github.com/prefix-dev/pixi/pull/4955) - Preserve symlinked manifest paths by @claydugo in [#4912](https://github.com/prefix-dev/pixi/pull/4912) - Improved two tests to not use big packages or slow repodata by @ruben-arts in [#4959](https://github.com/prefix-dev/pixi/pull/4959) - Better out-of source caching and source code propagation by @tdejager in [#4875](https://github.com/prefix-dev/pixi/pull/4875) - Only use mapping fallback when conda-forge is not specifically by @ruben-arts in [#4952](https://github.com/prefix-dev/pixi/pull/4952) - Improve error messages for conda-pypi mapping failures by @baszalmstra in [#4976](https://github.com/prefix-dev/pixi/pull/4976) - Correct PIXI_BIN_DIR variable reference in installation script error message by @Ninefrm in [#4981](https://github.com/prefix-dev/pixi/pull/4981) - Input globs normalisation and force reinstall by @nichmor in [#4931](https://github.com/prefix-dev/pixi/pull/4931) - Check pypi dependency-overrides in lock-file satisfiability by @baszalmstra in [#4995](https://github.com/prefix-dev/pixi/pull/4995) - Reconfigure renovate by @baszalmstra in [#4997](https://github.com/prefix-dev/pixi/pull/4997) - Devcontainer image link by @VeckoTheGecko in [#5043](https://github.com/prefix-dev/pixi/pull/5043) - Remove duplicate header by @aosen-xiong in [#4885](https://github.com/prefix-dev/pixi/pull/4885) - Remove "starting to locate" from pixi build by @ruben-arts in [#4933](https://github.com/prefix-dev/pixi/pull/4933) #### New Contributors - @trent-abc made their first contribution in [#5002](https://github.com/prefix-dev/pixi/pull/5002) - @Ninefrm made their first contribution in [#4981](https://github.com/prefix-dev/pixi/pull/4981) - @AntoinePrv made their first contribution in [#4978](https://github.com/prefix-dev/pixi/pull/4978) - @MartinJepsen made their first contribution in [#4968](https://github.com/prefix-dev/pixi/pull/4968) - @jamesfricker made their first contribution in [#4067](https://github.com/prefix-dev/pixi/pull/4067) - @Zachanardo made their first contribution in [#4966](https://github.com/prefix-dev/pixi/pull/4966) - @jtpio made their first contribution in [#4957](https://github.com/prefix-dev/pixi/pull/4957) - @claydugo made their first contribution in [#4912](https://github.com/prefix-dev/pixi/pull/4912) - @millsks made their first contribution in [#4948](https://github.com/prefix-dev/pixi/pull/4948) - @Dashlander made their first contribution in [#4921](https://github.com/prefix-dev/pixi/pull/4921) - @aosen-xiong made their first contribution in [#4885](https://github.com/prefix-dev/pixi/pull/4885) - @ShalokShalom made their first contribution in [#4859](https://github.com/prefix-dev/pixi/pull/4859) ### [0.59.0] - 2025-10-29 #### ✨ Highlights This release introduces the ability to set the strategy used in the solve. You can learn more about this feature in the [documentation](https://pixi.sh/dev/reference/pixi_manifest/#solve-strategy-optional). However, the main reason we are making this release is because one of our dependencies `astral-tokio-tar` below 0.5.6 has a high severity security issue titled `TARmageddon`. Updating that dependency fixes that. #### Added - Add `solve-strategy` to the manifest and solve by @bobozaur in [#4789](https://github.com/prefix-dev/pixi/pull/4789) #### Changed - Upgrade rust toolchain by @tdejager in [#4815](https://github.com/prefix-dev/pixi/pull/4815) - Update patch script to patch versions by @tdejager in [#4823](https://github.com/prefix-dev/pixi/pull/4823) - Configurable export name by @charles-turner-1 in [#4838](https://github.com/prefix-dev/pixi/pull/4838) #### Documentation - Use custom search separator by @Hofer-Julian in [#4835](https://github.com/prefix-dev/pixi/pull/4835) #### Fixed - CLI logging again by @tdejager in [#4812](https://github.com/prefix-dev/pixi/pull/4812) - Slim down trampoline dependency tree by removing `pixi_utils` by @wolfv in [#4817](https://github.com/prefix-dev/pixi/pull/4817) - Lefthook parallel by @Hofer-Julian in [#4836](https://github.com/prefix-dev/pixi/pull/4836) - CVE-2025-62518 by updating astral-tokio-tar by @niklaskorz in [#4833](https://github.com/prefix-dev/pixi/pull/4833) #### New Contributors - @charles-turner-1 made their first contribution in [#4838](https://github.com/prefix-dev/pixi/pull/4838) - @niklaskorz made their first contribution in [#4833](https://github.com/prefix-dev/pixi/pull/4833) - @bobozaur made their first contribution in [#4789](https://github.com/prefix-dev/pixi/pull/4789) ### [0.58.0] - 2025-10-22 #### ✨ Highlights This release adds important bugfixes and changes in the discovery logic. Pixi Build already had the ability to directly depend on `recipe.yaml` files backed by `pixi-build-rattler-build` without the need to specify a separate package manifest. So the following code just works: ```toml [dependencies] package = { path = "/path/to/recipe.yaml" } ``` This still works, but we stopped hardcoding the channel for the backends. Now, it will first try to find a workspace manifest and extract its channels. If that doesn't work, it will fallback to the default channels in your Pixi config. #### Added - Add some more debug-logging if rebuilds are acting up by @tdejager in [#4794](https://github.com/prefix-dev/pixi/pull/4794) #### Changed - Automatic detection of ros backend for package.xml files by @ruben-arts in [#4782](https://github.com/prefix-dev/pixi/pull/4782) #### Documentation - Fix link to boost package by @h-vetinari in [#4793](https://github.com/prefix-dev/pixi/pull/4793) #### Fixed - Fix testsuite tests configuration by @remimimimimi in [#4795](https://github.com/prefix-dev/pixi/pull/4795) - Target specific inline variants by @Hofer-Julian in [#4803](https://github.com/prefix-dev/pixi/pull/4803) - Reinstall should rebuild a source package by @nichmor in [#4809](https://github.com/prefix-dev/pixi/pull/4809) #### New Contributors - @h-vetinari made their first contribution in [#4793](https://github.com/prefix-dev/pixi/pull/4793) ### [0.57.0] - 2025-10-20 #### ✨ Highlights There's a new way to include variants in to a pixi workspace! Use `build-variants-files` to reference external variant definitions from YAML files. ```toml [workspace] build-variants-files = [ "./pinning/conda_build_config.yaml", "./variants/overrides.yaml", ] ``` Read more about this feature in the [docs](https://pixi.sh/dev/reference/pixi_manifest/#build-variants-files-optional). We deprecated the following syntax in the pixi manifest and give explicit warning when it's used: - `[project]`: should be replaced by `[workspace]`. - `[build-dependencies]` and `[host-dependencies]`: should be replaced by `[dependencies]`. If you're working on pixi-build backend note that we deprecated build-api v0. And we also fixed a lot of things! #### Changed - Correctly parse directory requirements by @tdejager in [#4710](https://github.com/prefix-dev/pixi/pull/4710) - Load variants from files by @Hofer-Julian in [#4665](https://github.com/prefix-dev/pixi/pull/4665) - Always regenerate metadata on override by @tdejager in [#4774](https://github.com/prefix-dev/pixi/pull/4774) - Canonicalize source path in build-backend initialization by @tdejager in [#4781](https://github.com/prefix-dev/pixi/pull/4781) #### Fixed - Mark more online tests by @mgorny in [#4595](https://github.com/prefix-dev/pixi/pull/4595) - Always create the $PREFIX directory by @wolfv in [#4716](https://github.com/prefix-dev/pixi/pull/4716) - `BrokenPipe` errors on more commands by @mrswastik-robot in [#4730](https://github.com/prefix-dev/pixi/pull/4730) - Respect --no-progress again by @remimimimimi in [#4739](https://github.com/prefix-dev/pixi/pull/4739) - BrokenPipe error on `pixi global list` by @mrswastik-robot in [#4748](https://github.com/prefix-dev/pixi/pull/4748) - Recursive optional dependencies by @tdejager in [#4743](https://github.com/prefix-dev/pixi/pull/4743) - Do not include hidden folders when matching if source package is stale by @nichmor in [#4728](https://github.com/prefix-dev/pixi/pull/4728) - Ignore gitignore globs by @nichmor in [#4765](https://github.com/prefix-dev/pixi/pull/4765) - Only use extension to differentiate between source or binary dependencies by @baszalmstra in [#4737](https://github.com/prefix-dev/pixi/pull/4737) - Deprecate `[project]` by @Hofer-Julian in [#4771](https://github.com/prefix-dev/pixi/pull/4771) - Change logging directive by @tdejager in [#4773](https://github.com/prefix-dev/pixi/pull/4773) - Deprecate `[build-dependencies]` and `[host-dependencies]` by @Hofer-Julian in [#4767](https://github.com/prefix-dev/pixi/pull/4767) - `-v/--quiet` should take precedence over `RUST_LOG` by @tdejager in [#4779](https://github.com/prefix-dev/pixi/pull/4779) - Use which to locate bash on windows by @fstanis in [#4776](https://github.com/prefix-dev/pixi/pull/4776) - Propagate target-platform flags for pixi build by @AdamDorwart in [#4703](https://github.com/prefix-dev/pixi/pull/4703) #### Refactor - Move diff into a separate pixi_diff crate by @haecker-felix in [#4697](https://github.com/prefix-dev/pixi/pull/4697) #### Removed - Remove build-api v0 by @baszalmstra in [#4754](https://github.com/prefix-dev/pixi/pull/4754) #### New Contributors - @AdamDorwart made their first contribution in [#4703](https://github.com/prefix-dev/pixi/pull/4703) ### [0.56.0] - 2025-10-06 #### ✨ Highlights Install a `.conda` package directly using `pixi global install`: ```text pixi global install --path /path/to/package-name.conda ``` #### Added - Add paxton-as-pixi SVG by @VeckoTheGecko in [#4592](https://github.com/prefix-dev/pixi/pull/4592) - Add a hyperlink to lock file docs by @lucascolley in [#4600](https://github.com/prefix-dev/pixi/pull/4600) - Add description of a workspace to first workspace docs by @lucascolley in [#4602](https://github.com/prefix-dev/pixi/pull/4602) - Add a tutorial on `pixi import` and `pixi init --import` by @lucascolley in [#4631](https://github.com/prefix-dev/pixi/pull/4631) #### Changed - Option to ignore env var during activation by @Hofer-Julian in [#4619](https://github.com/prefix-dev/pixi/pull/4619) - Add new (minimal) pixi_api abstraction crate by @haecker-felix in [#4546](https://github.com/prefix-dev/pixi/pull/4546) - Drop StyledText abstraction, rename config to workspace by @haecker-felix in [#4647](https://github.com/prefix-dev/pixi/pull/4647) - More simple introduction to manifest reference by @lucascolley in [#4601](https://github.com/prefix-dev/pixi/pull/4601) - Direct `.conda` global installation by @lucascolley in [#4502](https://github.com/prefix-dev/pixi/pull/4502) - Implement task support for WorkspaceContext by @haecker-felix in [#4667](https://github.com/prefix-dev/pixi/pull/4667) - Unsafe-best-match for build as well by @tdejager in [#4649](https://github.com/prefix-dev/pixi/pull/4649) #### Documentation - `project` -> `workspace`, improve `first_workspace` page by @lucascolley in [#4586](https://github.com/prefix-dev/pixi/pull/4586) - Fix bash completion sourcing example by @Hofer-Julian in [#4590](https://github.com/prefix-dev/pixi/pull/4590) - `project` -> `workspace` in README also by @lucascolley in [#4589](https://github.com/prefix-dev/pixi/pull/4589) - Fix typo by @Hofer-Julian in [#4596](https://github.com/prefix-dev/pixi/pull/4596) - Fix broken hyperlink by @magsol in [#4605](https://github.com/prefix-dev/pixi/pull/4605) - Add global environments in setup-pixi by @pavelzw in [#4627](https://github.com/prefix-dev/pixi/pull/4627) - Add warning when viewing old docs version by @lucascolley in [#4628](https://github.com/prefix-dev/pixi/pull/4628) - Fix list in pixi extensions page by @pavelzw in [#4630](https://github.com/prefix-dev/pixi/pull/4630) - Update doc to include global environment caching information by @olivier-lacroix in [#4672](https://github.com/prefix-dev/pixi/pull/4672) #### Fixed - Correct SIGINT forwarding by @remimimimimi in [#4552](https://github.com/prefix-dev/pixi/pull/4552) - Inconsistent caching when input or output globs unmatched by @tdejager in [#4547](https://github.com/prefix-dev/pixi/pull/4547) - Obscure error when importing `environment.yml` with empty `pip:` by @Hofer-Julian in [#4609](https://github.com/prefix-dev/pixi/pull/4609) - Use source name for a package by @nichmor in [#4597](https://github.com/prefix-dev/pixi/pull/4597) - Pixi init config loading by @Hofer-Julian in [#4610](https://github.com/prefix-dev/pixi/pull/4610) - `add_tests::add_with_channel` by @Hofer-Julian in [#4618](https://github.com/prefix-dev/pixi/pull/4618) - Optional dependencies break requirement conversion code by @Hofer-Julian in [#4603](https://github.com/prefix-dev/pixi/pull/4603) - Handle `url::pkg` dependencies from conda env file by @lucascolley in [#4621](https://github.com/prefix-dev/pixi/pull/4621) - Panic when trying to resolve cross-platform deps by @nichmor in [#4612](https://github.com/prefix-dev/pixi/pull/4612) - Adapt testsuite CI by @Hofer-Julian in [#4632](https://github.com/prefix-dev/pixi/pull/4632) - Skip multi-output test by @Hofer-Julian in [#4653](https://github.com/prefix-dev/pixi/pull/4653) - Upgrade all features by default by @lucascolley in [#4646](https://github.com/prefix-dev/pixi/pull/4646) - Available tasks output by @remimimimimi in [#4655](https://github.com/prefix-dev/pixi/pull/4655) - Restore $status before calling \_\_fish_prompt_orig by @fstanis in [#4651](https://github.com/prefix-dev/pixi/pull/4651) - Use correct equality specifier for conda-environment export with git subdir pypi dep by @ihnorton in [#4658](https://github.com/prefix-dev/pixi/pull/4658) - Fix test-exports integration test after PR4658 by @ihnorton in [#4695](https://github.com/prefix-dev/pixi/pull/4695) - `pixi list` shouldn't panic in case of `BrokenPipe` error by @mrswastik-robot in [#4673](https://github.com/prefix-dev/pixi/pull/4673) - Double relative manifest path by @remimimimimi in [#4699](https://github.com/prefix-dev/pixi/pull/4699) #### Performance - Use `ignore` crate instead of `wax` crate for globbing by @tdejager in [#4578](https://github.com/prefix-dev/pixi/pull/4578) - Initialize the reqwest client lazily by @baszalmstra in [#4666](https://github.com/prefix-dev/pixi/pull/4666) - Initialize the environment variables lazily for sdist environments by @baszalmstra in [#4685](https://github.com/prefix-dev/pixi/pull/4685) #### Refactor - Extracted pixi_install_pypi from core by @tdejager in [#4643](https://github.com/prefix-dev/pixi/pull/4643) #### New Contributors - @ihnorton made their first contribution in [#4695](https://github.com/prefix-dev/pixi/pull/4695) - @fstanis made their first contribution in [#4651](https://github.com/prefix-dev/pixi/pull/4651) - @magsol made their first contribution in [#4605](https://github.com/prefix-dev/pixi/pull/4605) - @VeckoTheGecko made their first contribution in [#4592](https://github.com/prefix-dev/pixi/pull/4592) ### [0.55.0] - 2025-09-15 #### ✨ Highlights This cycle, the Pixi team focused on squashing bugs. We especially focused on problems that were annoying and open for some time, but never quite important to fix *right now*. #### ⚠️ Breaking Change The environment variable overwriting logic is changed. If you think you haven't read this for the first time, then you are right! We already attempted to fix the order and other weird aspects of our environment variable handling in the past, but had to revert it, since it broke too many things. This time we touched significantly less logic so we hope that the impact will be minimal. Previously, the variables in your own environment would overwrite the variables set in the Pixi manifest. This is now reversed, meaning that the variables set in the Pixi manifest will overwrite the variables in your own environment. Also task environment variables will now be considered even if that environment variable was already defined outside of Pixi. More info can be found in the [documentation](https://pixi.sh/v0.55.0/reference/environment_variables/). #### Changed - Search in `pixi global` directory as well, along with PATH by @mrswastik-robot in [#4365](https://github.com/prefix-dev/pixi/pull/4365) - Add cargo-deny by @haecker-felix in [#4539](https://github.com/prefix-dev/pixi/pull/4539) #### Documentation - Add hyperlinks for `cargo` and `npm` by @lucascolley in [#4582](https://github.com/prefix-dev/pixi/pull/4582) - Update cuda tags in `pixi-docker` by @mbrobbel in [#4534](https://github.com/prefix-dev/pixi/pull/4534) - Refactor 'pixi-extensions' docs to the latest changes by @mrswastik-robot in [#4541](https://github.com/prefix-dev/pixi/pull/4541) - Fix warning syntax for detached-environments by @lucascolley in [#4557](https://github.com/prefix-dev/pixi/pull/4557) #### Fixed - Check when to render as ninja string by @tdejager in [#4535](https://github.com/prefix-dev/pixi/pull/4535) - Honor explicit manifest by @remimimimimi in [#4536](https://github.com/prefix-dev/pixi/pull/4536) - Upgrade for all targets by @remimimimimi in [#4553](https://github.com/prefix-dev/pixi/pull/4553) - Set pixi cache dir when building cmake extensions by @nichmor in [#4567](https://github.com/prefix-dev/pixi/pull/4567) - Environment variable priority by @Hofer-Julian in [#4544](https://github.com/prefix-dev/pixi/pull/4544) - Clear filesystem caches in between `pixi run` steps by @baszalmstra in [#4523](https://github.com/prefix-dev/pixi/pull/4523) - Collect errors with `pixi global` install and uninstall by @Hofer-Julian in [#4565](https://github.com/prefix-dev/pixi/pull/4565) - Check for missing channels in `solve_pixi` by @lucascolley in [#4580](https://github.com/prefix-dev/pixi/pull/4580) #### New Contributors - @mbrobbel made their first contribution in [#4534](https://github.com/prefix-dev/pixi/pull/4534) ### [0.54.2] - 2025-09-08 #### Added - Add cancellation support to command dispatcher by @baszalmstra in [#4501](https://github.com/prefix-dev/pixi/pull/4501) - Support `win-32` emulation on `win-64` by @baszalmstra in [#4531](https://github.com/prefix-dev/pixi/pull/4531) #### Changed - Include version information in `self-update --dry-run` by @nicoddemus in [#4513](https://github.com/prefix-dev/pixi/pull/4513) #### Documentation - Fix task arg example by @Hofer-Julian in [#4521](https://github.com/prefix-dev/pixi/pull/4521) - Add `pixi-build-ros` tutorial by @ruben-arts in [#4507](https://github.com/prefix-dev/pixi/pull/4507) #### Fixed - Clear progress bar after install by @baszalmstra in [#4509](https://github.com/prefix-dev/pixi/pull/4509) - Rebuild if dependencies changed by @baszalmstra in [#4511](https://github.com/prefix-dev/pixi/pull/4511) - `pixi build` stop generating empty directories by @Hofer-Julian in [#4520](https://github.com/prefix-dev/pixi/pull/4520) - Documentation link and error in `pixi init` by @ruben-arts in [#4530](https://github.com/prefix-dev/pixi/pull/4530) #### Performance - Early out on installer file not containing the pixi uv installer by @ruben-arts in [#4525](https://github.com/prefix-dev/pixi/pull/4525) #### New Contributors - @nicoddemus made their first contribution in [#4513](https://github.com/prefix-dev/pixi/pull/4513) ### [0.54.1] - 2025-09-03 #### ✨ Highlights Small improvements and bug fixes. #### Changed - Fix `--frozen` and `--locked` collision by @tdejager in [#4488](https://github.com/prefix-dev/pixi/pull/4488) - Cache backend discovery by @baszalmstra in [#4492](https://github.com/prefix-dev/pixi/pull/4492) #### Fixed - Colors being escaped in cli output by @ruben-arts in [#4490](https://github.com/prefix-dev/pixi/pull/4490) - Print build log by default by @ruben-arts in [#4495](https://github.com/prefix-dev/pixi/pull/4495) - Panic on moving package source location by @Hofer-Julian in [#4496](https://github.com/prefix-dev/pixi/pull/4496) ### [0.54.0] - 2025-09-01 #### ✨ Highlights You can now use `pixi global tree` to visualize the dependency tree of a global environment. And you can install subsets of packages now works, for both conda and pypi packages: ```bash # Define which packages you want to install and which you want to skip. pixi install --only packageA --only packageB --skip packageC # Using this modified environment without updating it again can be done with: pixi run --as-is my_command pixi shell --as-is ``` #### Breaking Change Only for users using `preview = ["pixi-build"]`: In [#4410](https://github.com/prefix-dev/pixi/pull/4410) we've made `package.name` optional. e.g. ```toml [package] name = "my-package" # This is now optional version = "0.1.0" # This is now optional ``` Soon, the backends will be able to automatically get those values from `pyproject.toml`, `Cargo.toml`, `package.xml` etc. However, this results in the lockfiles not being `--locked` anymore. Running `pixi lock` or `pixi update` should fix this! #### Added - Add new `pixi global tree` command by @Carbonhell in [#4427](https://github.com/prefix-dev/pixi/pull/4427) - Add the option for multiple `--only` flags. by @tdejager in [#4477](https://github.com/prefix-dev/pixi/pull/4477) & [#4404](https://github.com/prefix-dev/pixi/pull/4404) #### Changed - Ability to ignore `pypi` packages during installation by @tdejager in [#4456](https://github.com/prefix-dev/pixi/pull/4456) - Move integration tests to pixi crate by @tdejager in [#4472](https://github.com/prefix-dev/pixi/pull/4472) #### Documentation - Extend `pixi global` tutorial with source dependencies by @Hofer-Julian in [#4407](https://github.com/prefix-dev/pixi/pull/4407) - Fix `pixi-build` getting started doc by @Tobias-Fischer in [#4415](https://github.com/prefix-dev/pixi/pull/4415) - Remove unused footnote in `lockfile.md` by @ZhenShuo2021 in [#4439](https://github.com/prefix-dev/pixi/pull/4439) #### Fixed - Relative windows --paths by @baszalmstra in [#4395](https://github.com/prefix-dev/pixi/pull/4395) - Auth middleware should be added after mirror rewrite by @maccam912 in [#4399](https://github.com/prefix-dev/pixi/pull/4399) - Occasionally hangs on exit by @baszalmstra in [#4409](https://github.com/prefix-dev/pixi/pull/4409) - Ensure we only create pypi prefix once by @baszalmstra in [#4416](https://github.com/prefix-dev/pixi/pull/4416) - Diagnostic source of solve error was not propagated by @baszalmstra in [#4417](https://github.com/prefix-dev/pixi/pull/4417) - Warn about no pinning strategy for unused features by @kilian-hu in [#4065](https://github.com/prefix-dev/pixi/pull/4065) - Load lock file with dependency override by @HernandoR in [#4419](https://github.com/prefix-dev/pixi/pull/4419) - Adapt schema for `[workspace.target.OS.build-variants]` by @Hofer-Julian in [#4445](https://github.com/prefix-dev/pixi/pull/4445) - Create virtual PyPI packages by @tdejager in [#4469](https://github.com/prefix-dev/pixi/pull/4469) - Pixi global update shortcuts by @Hofer-Julian in [#4463](https://github.com/prefix-dev/pixi/pull/4463) - Environment never recovering after subset install by @tdejager in [#4479](https://github.com/prefix-dev/pixi/pull/4479) #### Refactor - Move pixi crate into crates/pixi_cli by @haecker-felix in [#4377](https://github.com/prefix-dev/pixi/pull/4377) - Drop dedicated cli module from pixi_cli and move everything into /src by @haecker-felix in [#4398](https://github.com/prefix-dev/pixi/pull/4398) - Move global into new pixi_global crate by @haecker-felix in [#4388](https://github.com/prefix-dev/pixi/pull/4388) - Move task into new pixi_task crate by @haecker-felix in [#4401](https://github.com/prefix-dev/pixi/pull/4401) - BREAKING: make name optional by @baszalmstra in [#4410](https://github.com/prefix-dev/pixi/pull/4410) #### Removed - Remove outdated comment about fast channel by @lucascolley in [#4471](https://github.com/prefix-dev/pixi/pull/4471) #### New Contributors - @ZhenShuo2021 made their first contribution in [#4439](https://github.com/prefix-dev/pixi/pull/4439) - @Tobias-Fischer made their first contribution in [#4415](https://github.com/prefix-dev/pixi/pull/4415) - @kilian-hu made their first contribution in [#4065](https://github.com/prefix-dev/pixi/pull/4065) - @maccam912 made their first contribution in [#4399](https://github.com/prefix-dev/pixi/pull/4399) ### [0.53.0] - 2025-08-19 #### ✨ Highlights - Big cleanup of the CLI flags, mainly `--frozen`, `--locked`, and `--no-install`. - Added `--as-is` to `pixi run/shell` to run the command without installing the dependencies or touching the lockfile. - Support the Bash shell on Windows using `pixi shell`. - Pixi build can now support `package.build.source.path = "some/path"` to use a different source root for the build. #### ⚠️ Breaking Change We've removed `--no-lockfile-update` and replaced it with `--no-install --frozen`. On `pixi run/shell` you can use `--as-is` to run the command without installing the dependencies or touching the lockfile. #### Added - Add `--as-is` as a shorthand for `--no-install --frozen` by @tdejager in [#4357](https://github.com/prefix-dev/pixi/pull/4357) - Add profiling profile by @ruben-arts in [#4376](https://github.com/prefix-dev/pixi/pull/4376) #### Changed - Infer package name for source package with `pixi global install` by @Hofer-Julian in [#4340](https://github.com/prefix-dev/pixi/pull/4340) - Add `pixi --list` to view all the commands (pixi-extensions + built-in commands) by @mrswastik-robot in [#4307](https://github.com/prefix-dev/pixi/pull/4307) - Use log level info for build backends by @pavelzw in [#4354](https://github.com/prefix-dev/pixi/pull/4354) - Use `pixi build` with non-prefix channels, through fixing `run-exports` fetching by @remimimimimi in [#4179](https://github.com/prefix-dev/pixi/pull/4179) - Alternative source root for build by @remimimimimi in [#4240](https://github.com/prefix-dev/pixi/pull/4240) - Add `--build-platform` to `pixi build` by @baszalmstra in [#4298](https://github.com/prefix-dev/pixi/pull/4298) - Support `Bash` on Windows using 'pixi shell' by @mwiebe in [#3981](https://github.com/prefix-dev/pixi/pull/3981) - Move `build.channels` to `build.backend.channels` by @nichmor in [#4361](https://github.com/prefix-dev/pixi/pull/4361) - Return error on build dispatch panic by @tdejager in [#4382](https://github.com/prefix-dev/pixi/pull/4382) #### Documentation - Add document for proxy-config table by @gzm55 in [#4367](https://github.com/prefix-dev/pixi/pull/4367) #### Fixed - Cargo-machete action 0.9.1 by @bnjbvr in [#4368](https://github.com/prefix-dev/pixi/pull/4368) - Preserve comments when inserting dependency to manifest by @baszalmstra in [#4370](https://github.com/prefix-dev/pixi/pull/4370) - Now cache miss when a pypi no-binary, no-build was found by @tdejager in [#4362](https://github.com/prefix-dev/pixi/pull/4362) - Resolve shell quoting issue with pixi run commands by @chrisburr in [#4352](https://github.com/prefix-dev/pixi/pull/4352) - Allow dots in global environment names by @baszalmstra in [#4374](https://github.com/prefix-dev/pixi/pull/4374) - Improve `infer_package_name_from_spec` by @Hofer-Julian in [#4378](https://github.com/prefix-dev/pixi/pull/4378) - Replace `build.configuration` with `build.config` by @ruben-arts in [#4380](https://github.com/prefix-dev/pixi/pull/4380) - Pass `run-dependencies` and `run-exports` to packages by @baszalmstra in [#4373](https://github.com/prefix-dev/pixi/pull/4373) #### Refactor - Remove manual conflicts check for `--frozen` & `--locked` by @tdejager in [#4359](https://github.com/prefix-dev/pixi/pull/4359) #### New Contributors - @chrisburr made their first contribution in [#4352](https://github.com/prefix-dev/pixi/pull/4352) - @bnjbvr made their first contribution in [#4368](https://github.com/prefix-dev/pixi/pull/4368) ### [0.52.0] - 2025-08-14 #### ✨ Highlights You can now use `pixi global` to install source dependencies. ```text pixi global install --path path/to/my-package my-package ``` At the moment, you still have to specify the package name, which we will improve on later! #### ⚠️ Breaking Change In `v0.51.0` we changed the environment variable overwriting logic. This has be reverted in this release, as there are some issues with it. #### Features - Include named source dependencies through `pixi global` by @tdejager in [#4165](https://github.com/prefix-dev/pixi/pull/4165) #### Documentation - Fix example package name by @henningkayser in [#4331](https://github.com/prefix-dev/pixi/pull/4331) - Add keyring auth support doc and bump setup-pixi action version by @olivier-lacroix in [#4332](https://github.com/prefix-dev/pixi/pull/4332) - Pycharm integration via conda environments.txt file by @analog-cbarber in [#4290](https://github.com/prefix-dev/pixi/pull/4290) #### Fixed - Fish completion script by @ruben-arts in [#4315](https://github.com/prefix-dev/pixi/pull/4315) - Update named arg schema by @bollwyvl in [#4324](https://github.com/prefix-dev/pixi/pull/4324) - Revert environment logic changes by @Hofer-Julian in [#4346](https://github.com/prefix-dev/pixi/pull/4346) #### Refactor - Move all non cli code into `pixi_core` crate by @haecker-felix in [#4337](https://github.com/prefix-dev/pixi/pull/4337) #### New Contributors - @analog-cbarber made their first contribution in [#4290](https://github.com/prefix-dev/pixi/pull/4290) - @haecker-felix made their first contribution in [#4337](https://github.com/prefix-dev/pixi/pull/4337) - @henningkayser made their first contribution in [#4331](https://github.com/prefix-dev/pixi/pull/4331) ### [0.51.0] - 2025-08-12 #### ✨ Highlights Pixi now supports `--skip` on install which means you can skip the installation of a package. Which can be useful for things like layering Docker images. Pixi build got a lot of improvements, including the ability to use build backends from source. Starting with this release you can get build backends from conda-forge. We will release stable versions of the build backends on conda-forge, and we maintain a rolling distribution on the `pixi-build-backends` channel. The documentation has been updated to reflect this change. #### ⚠️ Breaking Change The environment variable overwriting logic is changed. Previously, the variables in your own environment would overwrite the variables set in the Pixi manifest. This is now reversed, meaning that the variables set in the Pixi manifest will overwrite the variables in your own environment. More info can be found in the [documentation](https://pixi.sh/dev/reference/environment_variables/). #### Added - Add new configuration options for concurrency and experimental features by @zelosleone in [#4223](https://github.com/prefix-dev/pixi/pull/4223) - Support for loong64 linux by @wszqkzqk in [#4163](https://github.com/prefix-dev/pixi/pull/4163) - Add channels to the build-v1 apis by @baszalmstra in [#4249](https://github.com/prefix-dev/pixi/pull/4249) - Support pip packages for `no-build-isolation` by @Hofer-Julian in [#4247](https://github.com/prefix-dev/pixi/pull/4247) - Add better logging for build backends by @baszalmstra in [#4276](https://github.com/prefix-dev/pixi/pull/4276) - Add `--build`, rename `--tool` to `--build_backends` by @lucascolley in [#4281](https://github.com/prefix-dev/pixi/pull/4281) - Add support for PIXI_ENVIRONMENT_NAME and PS1 prompt modification by @zelosleone in [#4101](https://github.com/prefix-dev/pixi/pull/4101) - Add the ability to skip install of local source dependencies by @olivier-lacroix in [#3092](https://github.com/prefix-dev/pixi/pull/3092) #### Changed - Prevent execution in parent of pixi home directory by @ytausch in [#4168](https://github.com/prefix-dev/pixi/pull/4168) - Add `did you mean` suggestions for the cmds (built-in + pixi extensions) by @mrswastik-robot in [#4058](https://github.com/prefix-dev/pixi/pull/4058) - Per platform extra options for pixi build configuration by @Hofer-Julian in [#4036](https://github.com/prefix-dev/pixi/pull/4036) - Named args in `depends-on` by @lucascolley in [#4148](https://github.com/prefix-dev/pixi/pull/4148) - Pass repodata records to build backend by @baszalmstra in [#4252](https://github.com/prefix-dev/pixi/pull/4252) - Extract reporters out of pixi into its own crate by @tdejager in [#4266](https://github.com/prefix-dev/pixi/pull/4266) - Allow using build backends from source by @baszalmstra in [#4145](https://github.com/prefix-dev/pixi/pull/4145) - PyPI `requirements.txt` format by @lucascolley in [#4270](https://github.com/prefix-dev/pixi/pull/4270) - Upgrade to uv 0.8.20 and get rid of non-async build dispatch calls by @tdejager in [#4289](https://github.com/prefix-dev/pixi/pull/4289) - `SourceSpec` struct composed of `SourceLocationSpec` by @lucascolley in [#4305](https://github.com/prefix-dev/pixi/pull/4305) #### Documentation - Update documentation on task names by @photex in [#4230](https://github.com/prefix-dev/pixi/pull/4230) - Update docs with `pixi-extensions` by @mrswastik-robot in [#4144](https://github.com/prefix-dev/pixi/pull/4144) - Mention md-tui support for reading from stdin by @pavelzw in [#4268](https://github.com/prefix-dev/pixi/pull/4268) - Add contributor docs for Python test snapshots by @lucascolley in [#4273](https://github.com/prefix-dev/pixi/pull/4273) - Update documentation and related manifests by @ruben-arts in [#4279](https://github.com/prefix-dev/pixi/pull/4279) - Fix 404 link by @pavelzw in [#4295](https://github.com/prefix-dev/pixi/pull/4295) - Mention glow for viewing markdown in the terminal by @pavelzw in [#4288](https://github.com/prefix-dev/pixi/pull/4288) - Fix typo by @pavelzw in [#4306](https://github.com/prefix-dev/pixi/pull/4306)[#4309](https://github.com/prefix-dev/pixi/pull/4309) - Simplify and fix the `pixi build` getting started by @ruben-arts in [#4304](https://github.com/prefix-dev/pixi/pull/4304) #### Fixed - Improve testing speed by using prefix channel by @ruben-arts in [#4227](https://github.com/prefix-dev/pixi/pull/4227) - Pixi-build preview-mode check by @remimimimimi in [#4224](https://github.com/prefix-dev/pixi/pull/4224) - Relative path to package for pixi global by @wolfv in [#4200](https://github.com/prefix-dev/pixi/pull/4200) - Replace syrupy with inline-snapshot by @lucascolley in [#4246](https://github.com/prefix-dev/pixi/pull/4246) - Forward CTRL+C signal to `deno_task_shell` by @wolfv in [#4243](https://github.com/prefix-dev/pixi/pull/4243) - Override environment variables based on priority by @magentaqin in [#3940](https://github.com/prefix-dev/pixi/pull/3940) - Exclude env key 'PROJECT_ENV' and evaluate referenced variables by @magentaqin in [#4275](https://github.com/prefix-dev/pixi/pull/4275) - Quick Demo example shell quoting by @notpeter in [#4285](https://github.com/prefix-dev/pixi/pull/4285) - Feature activation environment variable priority by @magentaqin in [#4282](https://github.com/prefix-dev/pixi/pull/4282) - Disable JLAP by default by @ruben-arts in [#4301](https://github.com/prefix-dev/pixi/pull/4301) #### New Contributors - @magentaqin made their first contribution in [#4282](https://github.com/prefix-dev/pixi/pull/4282) - @notpeter made their first contribution in [#4285](https://github.com/prefix-dev/pixi/pull/4285) - @lsetiawan made their first contribution in [#4248](https://github.com/prefix-dev/pixi/pull/4248) - @Carbonhell made their first contribution in [#4263](https://github.com/prefix-dev/pixi/pull/4263) - @matthewfeickert made their first contribution in [#4256](https://github.com/prefix-dev/pixi/pull/4256) - @wszqkzqk made their first contribution in [#4163](https://github.com/prefix-dev/pixi/pull/4163) - @photex made their first contribution in [#4230](https://github.com/prefix-dev/pixi/pull/4230) ### [0.50.2] - 2025-07-28 #### Documentation - Update setup-pixi docs by @pavelzw in [#4207](https://github.com/prefix-dev/pixi/pull/4207) - Update cli welcome in README by @pauljurczak in [#4211](https://github.com/prefix-dev/pixi/pull/4211) #### Fixed - Print build log if build fails by @Hofer-Julian in [#4205](https://github.com/prefix-dev/pixi/pull/4205) - Increase retention of pixi artifacts by @Hofer-Julian in [#4215](https://github.com/prefix-dev/pixi/pull/4215) - Network authentication pixi global by @ruben-arts in [#4222](https://github.com/prefix-dev/pixi/pull/4222) - Netrc issue and hash mismatch by @baszalmstra in [#4218](https://github.com/prefix-dev/pixi/pull/4218) #### New Contributors - @pauljurczak made their first contribution in [#4211](https://github.com/prefix-dev/pixi/pull/4211) ### [0.50.1] - 2025-07-25 #### ✨ Highlights Use `pixi import` to import `environment.yml` files into your Pixi manifest. #### Added - Add build profiles to not build in editable mode in `pixi build` by @baszalmstra in [#4202](https://github.com/prefix-dev/pixi/pull/4202) #### Changed - Implement `pixi import` for `environment.yml` by @lucascolley in [#4096](https://github.com/prefix-dev/pixi/pull/4096) #### Fixed - Global progress by @tdejager in [#4190](https://github.com/prefix-dev/pixi/pull/4190) - Update rattler and add test for variable expansion by @Hofer-Julian in [#4199](https://github.com/prefix-dev/pixi/pull/4199) ### [0.50.0] - 2025-07-22 #### ✨ Highlights This release contains loads of bug fixes and refactors, primarily to make `pixi build` more stable and feature rich in the near future. #### Added - Add `pypi-option.no-binary` by @thomas-maschler in [#4008](https://github.com/prefix-dev/pixi/pull/4008) - Add explicit workspace inheritance syntax by @baszalmstra in [#4078](https://github.com/prefix-dev/pixi/pull/4078) - Add `conda/outputs` and `conda/build_v2` backend protocol by @baszalmstra in [#4118](https://github.com/prefix-dev/pixi/pull/4118) - Add cyclic dependency support by @baszalmstra in [#4143](https://github.com/prefix-dev/pixi/pull/4143) - Rebuild source package if a build dependency changed by @baszalmstra in [#4171](https://github.com/prefix-dev/pixi/pull/4171) - Add `pypi-options.dependency-overrides` to override pypi dependencies by @HernandoR in [#3948](https://github.com/prefix-dev/pixi/pull/3948) #### Changed - Add `pixi init` as a suggestion in the error message, when `pyproject.toml` is without the `tool.pixi` section by @mrswastik-robot in [#3943](https://github.com/prefix-dev/pixi/pull/3943) - Improve error messages when a python interpreter is needed by @tdejager in [#4075](https://github.com/prefix-dev/pixi/pull/4075) - Manual validation of frozen and locked CLI arguments by @gshiba in [#4044](https://github.com/prefix-dev/pixi/pull/4044) - Better error for unexpected packages from build backend by @baszalmstra in [#4098](https://github.com/prefix-dev/pixi/pull/4098) - Implement stable hash for ProjectModelV1 to improve cache consistency by @baszalmstra in [#4094](https://github.com/prefix-dev/pixi/pull/4094) - Upgrade to uv 0.7.20 by @tdejager in [#4091](https://github.com/prefix-dev/pixi/pull/4091)[#4115](https://github.com/prefix-dev/pixi/pull/4115) - Use command dispatcher for `pixi global install` by @tdejager in [#4126](https://github.com/prefix-dev/pixi/pull/4126) - Notify which conda packages may have influenced the conflict by @tdejager in [#4135](https://github.com/prefix-dev/pixi/pull/4135) - Refactor spec implementation handling in global by @tdejager in [#4138](https://github.com/prefix-dev/pixi/pull/4138) - Use command dispatcher for pixi build by @baszalmstra in [#4156](https://github.com/prefix-dev/pixi/pull/4156) #### Documentation - Add `site_description` by @lucascolley in [#4088](https://github.com/prefix-dev/pixi/pull/4088) - Improve the `system-requirements` documentation by @ruben-arts in [#4068](https://github.com/prefix-dev/pixi/pull/4068) - Enable `content.code.select` by @lucascolley in [#4092](https://github.com/prefix-dev/pixi/pull/4092) - Add `conda-deny` documentation by @PaulKMueller in [#4090](https://github.com/prefix-dev/pixi/pull/4090) [#4124](https://github.com/prefix-dev/pixi/pull/4124) - Update `setup-pixi` docs for pixi-url-bearer-token by @ytausch in [#4127](https://github.com/prefix-dev/pixi/pull/4127) - Update the python tutorial to use the workspace command by @rongou in [#4128](https://github.com/prefix-dev/pixi/pull/4128) - Update `setup-pixi` docs for 0.8.13 by @ytausch in [#4175](https://github.com/prefix-dev/pixi/pull/4175) - Add `geovista` to community.md by @bjlittle in [#4183](https://github.com/prefix-dev/pixi/pull/4183) #### Fixed - Only print release notes on new version with `self-update` by @lucascolley in [#4054](https://github.com/prefix-dev/pixi/pull/4054) - Add an early check, before creating directories for `` while uninstalling them by @mrswastik-robot in [#4049](https://github.com/prefix-dev/pixi/pull/4049) - Update template variable for extra index URLs in init file by @noamgot in [#4072](https://github.com/prefix-dev/pixi/pull/4072) - Allow to set `pypi-config.allow-insecure-host` by @zen-xu in [#4107](https://github.com/prefix-dev/pixi/pull/4107) #### New Contributors - @rongou made their first contribution in [#4128](https://github.com/prefix-dev/pixi/pull/4128) - @PaulKMueller made their first contribution in [#4124](https://github.com/prefix-dev/pixi/pull/4124) - @gshiba made their first contribution in [#4044](https://github.com/prefix-dev/pixi/pull/4044) - @thomas-maschler made their first contribution in [#4008](https://github.com/prefix-dev/pixi/pull/4008) - @bjlittle made their first contribution in [#4183](https://github.com/prefix-dev/pixi/pull/4183) ### [0.49.0] - 2025-06-30 #### ✨ Highlights This release enables `pixi` to pick up extensions that are installed as `pixi-`. This is similar to `cargo`, `git` and other tools. This means that you can now install extensions like this: ```shell pixi global install pixi-pack pixi pack ``` It also allows you to use `pixi exec` more easily: ```shell pixi exec --with numpy python -c "import numpy; print(numpy.__version__)" # Previous command is equivalent to: pixi exec --spec numpy --spec python python -c "import numpy; print(numpy.__version__)" ``` #### Added - Add `turtlebot4` simulation example to `ros2-nav2` by @wep21 in [#3988](https://github.com/prefix-dev/pixi/pull/3988) - Add `--with` option to `pixi exec` by @lucascolley in [#4011](https://github.com/prefix-dev/pixi/pull/4011) - Implement external `pixi-` command discovery for pixi extensions by @mrswastik-robot in [#3968](https://github.com/prefix-dev/pixi/pull/3968) #### Changed - Remove egg-info from gitignore and fix whitespace in beginning by @pavelzw in [#3964](https://github.com/prefix-dev/pixi/pull/3964) #### Documentation - Refactor getting started and python tutorial by @ruben-arts in [#3977](https://github.com/prefix-dev/pixi/pull/3977) - Add links to backend docs by @Hofer-Julian in [#4010](https://github.com/prefix-dev/pixi/pull/4010) - Improve content and layout by @ruben-arts in [#4003](https://github.com/prefix-dev/pixi/pull/4003) - Update pixi-pack documentation for parallel downloads by @delsner in [#4018](https://github.com/prefix-dev/pixi/pull/4018) - Add pixi pack to our extensions by @Hofer-Julian in [#4019](https://github.com/prefix-dev/pixi/pull/4019) - Explain conda and pypi mix by @ruben-arts in [#4022](https://github.com/prefix-dev/pixi/pull/4022) - Mention other extensions by @pavelzw in [#4026](https://github.com/prefix-dev/pixi/pull/4026) - Update pixi-pack docs for separate packages by @delsner in [#4025](https://github.com/prefix-dev/pixi/pull/4025) - Update title pixi-diff-to-markdown by @Hofer-Julian in [#4027](https://github.com/prefix-dev/pixi/pull/4027) - Add example of passing `arg` to `depended-on` task by @theavey in [#4030](https://github.com/prefix-dev/pixi/pull/4030) - Tweak nav headings by @lucascolley in [#4045](https://github.com/prefix-dev/pixi/pull/4045) - Fix formatting in pixi-pack by @pavelzw in [#4050](https://github.com/prefix-dev/pixi/pull/4050) #### Fixed - Multi output handling in Pixi by @Hofer-Julian in [#3961](https://github.com/prefix-dev/pixi/pull/3961) - Check for the environments not the environments dir by @ruben-arts in [#4005](https://github.com/prefix-dev/pixi/pull/4005) - Only trigger rebuild when relevant parts of the package manifest changed by @Hofer-Julian in [#3966](https://github.com/prefix-dev/pixi/pull/3966) - Lazy raise error of pypi building environment by @gzm55 in [#4009](https://github.com/prefix-dev/pixi/pull/4009) - Don't error on readonly fs with ignore files by @ruben-arts in [#3984](https://github.com/prefix-dev/pixi/pull/3984) - Fix example & tweak some wording by @lucascolley in [#4046](https://github.com/prefix-dev/pixi/pull/4046) #### Refactor - Building with command dispatcher by @baszalmstra in [#3967](https://github.com/prefix-dev/pixi/pull/3967) #### New Contributors - @theavey made their first contribution in [#4030](https://github.com/prefix-dev/pixi/pull/4030) - @xhochy made their first contribution in [#4014](https://github.com/prefix-dev/pixi/pull/4014) - @wep21 made their first contribution in [#3988](https://github.com/prefix-dev/pixi/pull/3988) ### [0.48.2] - 2025-06-16 #### ✨ Highlights This is a minor release with a couple of bugfixes. A new feature is the support for `mojoproject.toml` files which is used to develop on projects written in the Mojo programming language. This enables users to migrate from the [deprecated](https://docs.modular.com/magic/) Magic package manager to Pixi. #### Added - Support legacy mojoproject.toml by @zbowling in [#3942](https://github.com/prefix-dev/pixi/pull/3942) #### Changed - Update pixi-install-to-prefix by @ytausch in [#3924](https://github.com/prefix-dev/pixi/pull/3924) - Negotiate pixi build RPC interface through interface package by @Hofer-Julian in [#3927](https://github.com/prefix-dev/pixi/pull/3927) #### Documentation - Fix `discover_pixi` docstring by @Hofer-Julian in [#3928](https://github.com/prefix-dev/pixi/pull/3928) #### Fixed - Fix caching by @Hofer-Julian in [#3933](https://github.com/prefix-dev/pixi/pull/3933) - Always pass index locations by @nichmor in [#3947](https://github.com/prefix-dev/pixi/pull/3947) - Prefer to use MatchSpec instead of wildcard as package filter by @trim21 in [#3926](https://github.com/prefix-dev/pixi/pull/3926) - Typo in the doc strings by @Hofer-Julian in [#3954](https://github.com/prefix-dev/pixi/pull/3954) #### Refactor - Conda solving with command dispatcher by @baszalmstra in [#3909](https://github.com/prefix-dev/pixi/pull/3909) #### Removed - Remove `error_to_snapshot` by @Hofer-Julian in [#3934](https://github.com/prefix-dev/pixi/pull/3934) ### [0.48.1] - 2025-06-10 #### ✨ Highlights This is a minor release with a couple of bugs fixed. Additionally, `pixi self-update` accepts now the flags `--force` and `--no-release-note`. #### Added - Add cli options for self-update: --force and --no-release-note by @gzm55 in [#3888](https://github.com/prefix-dev/pixi/pull/3888) - Add pixi build testsuite by @Hofer-Julian in [#3891](https://github.com/prefix-dev/pixi/pull/3891) #### Fixed - Discovery error message by @Hofer-Julian in [#3903](https://github.com/prefix-dev/pixi/pull/3903) - `pixi lock` reporting by @Hofer-Julian in [#3896](https://github.com/prefix-dev/pixi/pull/3896) - Backslashes in editable path by @tdejager in [#3895](https://github.com/prefix-dev/pixi/pull/3895) - No longer panics, when a conda dependency is a PyPI get dependency by @ruben-arts in [#3905](https://github.com/prefix-dev/pixi/pull/3905) #### Removed - Remove pixi build tests by @Hofer-Julian in [#3892](https://github.com/prefix-dev/pixi/pull/3892) #### New Contributors - @simonjung1603 made their first contribution in [#3565](https://github.com/prefix-dev/pixi/pull/3565) ### [0.48.0] - 2025-06-02 #### ✨ Highlights Support for recursive source run dependencies when using `pixi build`. This means, you can now add source dependencies in the `run-dependencies` section of your Pixi package: ```toml [package.run-dependencies] cpp_math = { path = "packages/cpp_math" } ``` #### Added - Add `XDG_CONFIG_HOME` as configuration location on macOS by @ruben-arts in [#3759](https://github.com/prefix-dev/pixi/pull/3759) - Support relative path input globs for `pixi build` by @nichmor in [#3812](https://github.com/prefix-dev/pixi/pull/3812) - Add `condapackageignore` file to exclude `.pixi` directory from builds by @zelosleone in [#3840](https://github.com/prefix-dev/pixi/pull/3840) #### Changed - Improve type of outputs, add `Eq`, `PartialEq`, etc. by @wolfv in [#3822](https://github.com/prefix-dev/pixi/pull/3822) - Transform reporter events into tree by @baszalmstra in [#3834](https://github.com/prefix-dev/pixi/pull/3834) - Add release notes to the `self-update` including `--dry-run` by @chrisliebaer in [#3397](https://github.com/prefix-dev/pixi/pull/3397) - Migrate to `uv_distribution_types` for package requirements and update uv by @zelosleone in [#3872](https://github.com/prefix-dev/pixi/pull/3872) #### Documentation - Start using recursive source run dependencies by @Hofer-Julian in [#3768](https://github.com/prefix-dev/pixi/pull/3768) - Simplify documentation frontpage by @ruben-arts in [#3802](https://github.com/prefix-dev/pixi/pull/3802) - Add security policy by @pavelzw in [#3823](https://github.com/prefix-dev/pixi/pull/3823) - Fix typo in multi_environment.md by @AH-Merii in [#3797](https://github.com/prefix-dev/pixi/pull/3797) - Update pixi-pack docs for allow `--inject`ing wheels by @e8035669 in [#3853](https://github.com/prefix-dev/pixi/pull/3853) - Separator backend override by @Hofer-Julian in [#3857](https://github.com/prefix-dev/pixi/pull/3857) #### Fixed - Adapt for backend update by @Hofer-Julian in [#3767](https://github.com/prefix-dev/pixi/pull/3767) - Hashing for same package-name by @tdejager in [#3775](https://github.com/prefix-dev/pixi/pull/3775) - Recursive source run deps by @Hofer-Julian in [#3712](https://github.com/prefix-dev/pixi/pull/3712) - Workspace version and name inheritance by @baszalmstra in [#3786](https://github.com/prefix-dev/pixi/pull/3786) - Examples in self-update_extender by @sjpfenninger in [#3793](https://github.com/prefix-dev/pixi/pull/3793) - Take into account tasks arguments when caching by @nichmor in [#3782](https://github.com/prefix-dev/pixi/pull/3782) - Hanging on ssh passphrase by @nichmor in [#3761](https://github.com/prefix-dev/pixi/pull/3761) - Keep index on pypi dependency upgrade by @remimimimimi in [#3746](https://github.com/prefix-dev/pixi/pull/3746) - Help user when command not found by @ruben-arts in [#3803](https://github.com/prefix-dev/pixi/pull/3803) - Failing ci and improve test by @tdejager in [#3798](https://github.com/prefix-dev/pixi/pull/3798) - Space is a valid separator between date and time in `exclude-newer` by @trim21 in [#3764](https://github.com/prefix-dev/pixi/pull/3764) - Source globs and make them unique by @wolfv in [#3831](https://github.com/prefix-dev/pixi/pull/3831) - Validate `depends-on` must be a list by @YoganshSharma in [#3832](https://github.com/prefix-dev/pixi/pull/3832) - Path diff not calculated on Windows by @Hofer-Julian in [#3824](https://github.com/prefix-dev/pixi/pull/3824) - Unify reqwest Client for self_update when downloading archives by @gzm55 in [#3346](https://github.com/prefix-dev/pixi/pull/3346) - Fix main CI with some clippy and conflict fixes by @ruben-arts in [#3858](https://github.com/prefix-dev/pixi/pull/3858) - Filter duplicated path_diff entries for pixi global by @Hofer-Julian in [#3859](https://github.com/prefix-dev/pixi/pull/3859) - Update help message for unsupported PyPI platform error to include adding Python dependency by @zelosleone in [#3861](https://github.com/prefix-dev/pixi/pull/3861) #### Refactor - Command dispatcher by @baszalmstra in [#3791](https://github.com/prefix-dev/pixi/pull/3791) - Move `pixi_docs` to Cargo workspace by @Hofer-Julian in [#3844](https://github.com/prefix-dev/pixi/pull/3844) - Move fetching of source metadata to command dispatcher by @baszalmstra in [#3843](https://github.com/prefix-dev/pixi/pull/3843) - Alphabetize command list in CLI help by @dhirschfeld in [#3817](https://github.com/prefix-dev/pixi/pull/3817) #### New Contributors - @e8035669 made their first contribution in [#3853](https://github.com/prefix-dev/pixi/pull/3853) - @chrisliebaer made their first contribution in [#3397](https://github.com/prefix-dev/pixi/pull/3397) - @YoganshSharma made their first contribution in [#3832](https://github.com/prefix-dev/pixi/pull/3832) - @remimimimimi made their first contribution in [#3746](https://github.com/prefix-dev/pixi/pull/3746) - @sjpfenninger made their first contribution in [#3793](https://github.com/prefix-dev/pixi/pull/3793) ### [0.47.0] - 2025-05-12 #### ✨ Highlights - We now support `exclude-newer` to avoid getting packages that are build after the given date/timestamp. - The minijinja syntax now also works in `depends-on` and `inputs`/`outputs` of the tasks. #### Added - Add `--check` option to lock command by @noamgot in [#3663](https://github.com/prefix-dev/pixi/pull/3663) - Add `exclude-newer` to workspace by @baszalmstra in [#3633](https://github.com/prefix-dev/pixi/pull/3633) - Add environment size and prefix to pixi info by @MridulS in [#3674](https://github.com/prefix-dev/pixi/pull/3674) - Support jinja inputs outputs by @prsabahrami in [#3638](https://github.com/prefix-dev/pixi/pull/3638) - Support minijinja templates in arguments passed to `depends-on` by @prsabahrami in [#3668](https://github.com/prefix-dev/pixi/pull/3668) #### Changed - Change the way paths are handled by @tdejager in [#3658](https://github.com/prefix-dev/pixi/pull/3658) - Add build section to pixi config by @pavelzw in [#3502](https://github.com/prefix-dev/pixi/pull/3502) - Enable `tool.uv.sources` to work by @tdejager in [#3636](https://github.com/prefix-dev/pixi/pull/3636) - Installer use PIXI_REPOURL env as download base by @gzm55 in [#3558](https://github.com/prefix-dev/pixi/pull/3558) - Use a table for task list by @bollwyvl in [#3708](https://github.com/prefix-dev/pixi/pull/3708) #### Fixed - Add support for Visual Studio 2022 in dependencies and lock file by @zelosleone in [#3643](https://github.com/prefix-dev/pixi/pull/3643) - Json prints of the tasks by @prsabahrami in [#3637](https://github.com/prefix-dev/pixi/pull/3637) - Allow no build isolation for all packages by @baszalmstra in [#3657](https://github.com/prefix-dev/pixi/pull/3657) - Using the value of pattern_timeout for the shell initialization warning message by @noamgot in [#3660](https://github.com/prefix-dev/pixi/pull/3660) - Pypi panic with path dependencies in lock file by @Hofer-Julian in [#3690](https://github.com/prefix-dev/pixi/pull/3690) - Don't remove non-owned PyPI installs by @tdejager in [#3694](https://github.com/prefix-dev/pixi/pull/3694) - Task arg schema by @Hofer-Julian in [#3703](https://github.com/prefix-dev/pixi/pull/3703) - Normalize URL by removing SHA256 fragment in requirement source by @zelosleone in [#3696](https://github.com/prefix-dev/pixi/pull/3696) - Error on improper pyproject.toml configuration by @ruben-arts in [#3704](https://github.com/prefix-dev/pixi/pull/3704) - Package target selector platform serialization by @ruben-arts in [#3720](https://github.com/prefix-dev/pixi/pull/3720) - Task arg parsing panic by @Hofer-Julian in [#3731](https://github.com/prefix-dev/pixi/pull/3731) - Remove priority-queue spec limit due to rust edition by @gzm55 in [#3672](https://github.com/prefix-dev/pixi/pull/3672) #### Refactor - Move pypi requirement to crate by @baszalmstra in [#3689](https://github.com/prefix-dev/pixi/pull/3689) #### Documentation - Fix fish completion command by @pavelzw in [#3642](https://github.com/prefix-dev/pixi/pull/3642) - Download from github release by @Hofer-Julian in [#3653](https://github.com/prefix-dev/pixi/pull/3653) - Mention pixi docker blog post by @pavelzw in [#3655](https://github.com/prefix-dev/pixi/pull/3655) - Remove duplicate entry of ndonnx by @gnodar01 in [#3664](https://github.com/prefix-dev/pixi/pull/3664) - Clarify default env by @Hofer-Julian in [#3661](https://github.com/prefix-dev/pixi/pull/3661) - Fix typo by @mdeff in [#3673](https://github.com/prefix-dev/pixi/pull/3673) - Clarify which pyproject_toml is used by @zoed191 in [#3681](https://github.com/prefix-dev/pixi/pull/3681) - Add s3 middleware and mirror middleware to pixi-pack by @pavelzw in [#3679](https://github.com/prefix-dev/pixi/pull/3679) - Add pyfixest to community projects by @s3alfisc in [#3693](https://github.com/prefix-dev/pixi/pull/3693) - Update starship page by @Hofer-Julian in [#3697](https://github.com/prefix-dev/pixi/pull/3697) - Fix broken project manifest link by @lkstrp in [#3713](https://github.com/prefix-dev/pixi/pull/3713) - Mention YouTrack tracking issues for pixi by @pavelzw in [#3748](https://github.com/prefix-dev/pixi/pull/3748) - Support local `pixi-pack` executables for self-extracting by @FSP1020 in [#3745](https://github.com/prefix-dev/pixi/pull/3745) - Mention `pixi-install-to-prefix` by @pavelzw in [#3750](https://github.com/prefix-dev/pixi/pull/3750) - Add install method `scoop` on Windows by @trim21 in [#3737](https://github.com/prefix-dev/pixi/pull/3737) - Add a local repo as the dependency by @kemingy in [#3666](https://github.com/prefix-dev/pixi/pull/3666) #### New Contributors - @FSP1020 made their first contribution in [#3745](https://github.com/prefix-dev/pixi/pull/3745) - @lkstrp made their first contribution in [#3713](https://github.com/prefix-dev/pixi/pull/3713) - @zelosleone made their first contribution in [#3696](https://github.com/prefix-dev/pixi/pull/3696) - @s3alfisc made their first contribution in [#3693](https://github.com/prefix-dev/pixi/pull/3693) - @zoed191 made their first contribution in [#3681](https://github.com/prefix-dev/pixi/pull/3681) - @MridulS made their first contribution in [#3674](https://github.com/prefix-dev/pixi/pull/3674) - @mdeff made their first contribution in [#3673](https://github.com/prefix-dev/pixi/pull/3673) - @gnodar01 made their first contribution in [#3664](https://github.com/prefix-dev/pixi/pull/3664) ### [0.46.0] - 2025-04-22 #### ⚠️ Breaking Change `arg` names in `tasks` can no longer contain dashes (`-`). This restriction is due to the integration of `Minijinja` for rendering tasks, where dashes could be misinterpreted as a subtraction operator. #### ✨ Highlights This release comes with another set of features for the `tasks`! - The command of a task is now able to use `minijinja` for rendering the command. ```toml [tasks] # The arg `text`, converted to uppercase, will be printed. task1 = { cmd = "echo {{ text | upper }}", args = ["text"] } # If arg `text` contains 'hoi', it will be converted to lowercase. The result will be printed. task2 = { cmd = "echo {{ text | lower if 'hoi' in text }}", args = [ { arg = "text", default = "" }, ] } # With `a` and `b` being strings, they will be appended and then printed. task3 = { cmd = "echo {{ a + b }}", args = ["a", { arg = "b", default = "!" }] } # `names` will be split by whitespace and then every name will be printed separately task4 = { cmd = "{% for name in names | split %} echo {{ name }};{% endfor %}", args = [ "names", ] } ``` - Shortened composition of tasks with `depends-on` key. ```toml [tasks] test-all = [{ task = "test", args = ["all"] }] # Equivalent to: test-all = { depends-on = [{task = "test", args = ["all"] }]} ``` - The `depends-on` key can now include the environment that the task should run in. ```toml [tasks] # Using the shortened composition of tasks test-all = [ { task = "test", environment = "py311" }, { task = "test", environment = "py312" }, ] ``` #### Added - Integrate minijinja for tasks' command's rendering by @prsabahrami in [#3579](https://github.com/prefix-dev/pixi/pull/3579) - Support for riscv64 linux by @Hofer-Julian in [#3606](https://github.com/prefix-dev/pixi/pull/3606) - Task Environment Selection by @prsabahrami in [#3501](https://github.com/prefix-dev/pixi/pull/3501) - Shortened task composition with `depends-on` key by @prsabahrami in [#3450](https://github.com/prefix-dev/pixi/pull/3540) #### Changed - Format shell script with shfmt by @gzm55 in [#3552](https://github.com/prefix-dev/pixi/pull/3552) - Improve error message at missing pixi section by @joyanedel in [#3516](https://github.com/prefix-dev/pixi/pull/3516) - Install.sh supports installing without tar and unzip commands by @gzm55 in [#3551](https://github.com/prefix-dev/pixi/pull/3551) #### Documentation - Community: add `xsf` by @lucascolley in [#3515](https://github.com/prefix-dev/pixi/pull/3515) - Mention installation with `wget` instead of `curl` by @paugier in [#3547](https://github.com/prefix-dev/pixi/pull/3547) - Fix typo in `advanced_tasks.md` by @AH-Merii in [#3555](https://github.com/prefix-dev/pixi/pull/3555) - Update to call pixi task "start" in Index.md by @philipreese in [#3487](https://github.com/prefix-dev/pixi/pull/3487) - Migrate ros2.md example to use robostack-humble channel by @traversaro in [#3520](https://github.com/prefix-dev/pixi/pull/3520) - Provide guidance on using `direnv` by @phreed in [#3513](https://github.com/prefix-dev/pixi/pull/3513) - Remove unused ordered list in system_requirements.md by @kemingy in [#3590](https://github.com/prefix-dev/pixi/pull/3590) - Update `authentication.md` to fix typo in package name by @PanTheDev in [#3615](https://github.com/prefix-dev/pixi/pull/3615) - Replace `project` with `workspace` by @munechika-koyo in [#3623](https://github.com/prefix-dev/pixi/pull/3623) and in [#3620](https://github.com/prefix-dev/pixi/pull/3620) - Rename `pixi build` examples by @Hofer-Julian in [#3632](https://github.com/prefix-dev/pixi/pull/3632) #### Fixed - Updating windows `installation.md` to correspond to `installation.ps1` by @Ahschreyer in [#3507](https://github.com/prefix-dev/pixi/pull/3507) - Fix panic for `pixi task list` for platform specific tasks by @synapticarbors in [#3510](https://github.com/prefix-dev/pixi/pull/3510) - Improve error message if build backend crashes by @baszalmstra in [#3543](https://github.com/prefix-dev/pixi/pull/3543) - Check unzip command on msys and add ITs for install.sh by @gzm55 in [#3458](https://github.com/prefix-dev/pixi/pull/3458) - Shell-hook `--no-completion` by @Hofer-Julian in [#3553](https://github.com/prefix-dev/pixi/pull/3553) - Fixed a typo in init.rs by @noamgot in [#3561](https://github.com/prefix-dev/pixi/pull/3561) - Pixi-shell: bump timeout to 3 secs, fix docs link by @wolfv in [#3528](https://github.com/prefix-dev/pixi/pull/3528) - Invalidate lock-file if a pypi dependency is requested by @baszalmstra in [#3562](https://github.com/prefix-dev/pixi/pull/3562) - Build backend missing executable by @baszalmstra in [#3527](https://github.com/prefix-dev/pixi/pull/3527) - Community page link in README by @elonzh in [#3595](https://github.com/prefix-dev/pixi/pull/3595) - Mark `add_tests::add_pypi_git` as an online test by @mgorny in [#3586](https://github.com/prefix-dev/pixi/pull/3586) - Update `git-cliff` by @Hofer-Julian in [#3614](https://github.com/prefix-dev/pixi/pull/3614) - Pypi local directory satisfiability by @tdejager in [#3631](https://github.com/prefix-dev/pixi/pull/3631) - Don't keep reinstalling local pypi archives by @tdejager in [#3618](https://github.com/prefix-dev/pixi/pull/3618) - Don't resolve for previously locked platforms by @baszalmstra in [#3635](https://github.com/prefix-dev/pixi/pull/3635) #### Refactor - Reduce difference between default and named feature by @baszalmstra in [#3545](https://github.com/prefix-dev/pixi/pull/3545) - Update `pixi.toml` to use args by @prsabahrami in [#3531](https://github.com/prefix-dev/pixi/pull/3531) - Refactor of pypi installer type by @tdejager in [#3563](https://github.com/prefix-dev/pixi/pull/3563) #### New Contributors - @renovate[bot] made their first contribution in [#3626](https://github.com/prefix-dev/pixi/pull/3626) - @munechika-koyo made their first contribution in [#3623](https://github.com/prefix-dev/pixi/pull/3623) - @elonzh made their first contribution in [#3595](https://github.com/prefix-dev/pixi/pull/3595) - @Ahschreyer made their first contribution in [#3507](https://github.com/prefix-dev/pixi/pull/3507) - @kemingy made their first contribution in [#3590](https://github.com/prefix-dev/pixi/pull/3590) - @joyanedel made their first contribution in [#3516](https://github.com/prefix-dev/pixi/pull/3516) - @phreed made their first contribution in [#3513](https://github.com/prefix-dev/pixi/pull/3513) - @AH-Merii made their first contribution in [#3555](https://github.com/prefix-dev/pixi/pull/3555) - @paugier made their first contribution in [#3547](https://github.com/prefix-dev/pixi/pull/3547) - @mwiebe made their first contribution in [#3519](https://github.com/prefix-dev/pixi/pull/3519) ### [0.45.0] - 2025-04-07 #### ✨ Highlights This release brings in numerous improvements and bug fixes and one big feature: argument variables tasks! If you do add `args`, you will have more convenient way of specifying arguments, which works with pipes and even allows you to set defaults. Let's say you define this manifest: ```toml [tasks.install] cmd = "cargo install {{ type }} --path {{ path }}" args = ["path", { arg = "type", default = "--release" }] # `path` is mandatory, `type` is optional with a default ``` Both of the invocations now work, since `type` is optional: ```bash pixi run install /path/to/manifest pixi run install /path/to/manifest --debug ``` If you don't specify `args` for your tasks everything which you append to the CLI will also be appended to the task. ```toml [tasks.install] cmd = "cargo install" ``` Therefore, running `pixi run install --debug --path /path/to/manifest` will lead to `cargo install --debug --path /path/to/manifest` being run inside the environment. This was already the behavior before this release, so existing tasks should continue to work. Learn more in our documentation: https://pixi.sh/v0.45.0/workspace/advanced_tasks/#using-task-arguments #### Changed - Argument variables in tasks by @prsabahrami in [#3433](https://github.com/prefix-dev/pixi/pull/3433) - Make workspace name optional by @baszalmstra in [#3526](https://github.com/prefix-dev/pixi/pull/3526) #### Documentation - Added task cwd default behaviour by @danpal96 in [#3470](https://github.com/prefix-dev/pixi/pull/3470) - Move direnv section to separate page by @pavelzw in [#3472](https://github.com/prefix-dev/pixi/pull/3472) - Exclude extender files from search by @Hofer-Julian in [#3473](https://github.com/prefix-dev/pixi/pull/3473) - Update getting_started.md to correctly reference py313 instead of py312 by @philipreese in [#3489](https://github.com/prefix-dev/pixi/pull/3489) - Move environment var section by @Hofer-Julian in [#3498](https://github.com/prefix-dev/pixi/pull/3498) - Rename remaining `pixi project` to `pixi workspace` by @Hofer-Julian in [#3486](https://github.com/prefix-dev/pixi/pull/3486) - Mention pypi support in pixi-pack by @pavelzw in [#3508](https://github.com/prefix-dev/pixi/pull/3508) - Document that activation scripts are not simply sourced by @traversaro in [#3506](https://github.com/prefix-dev/pixi/pull/3506) - Update pixi-pack docs for ignoring non-wheel pypi packages by @delsner in [#3523](https://github.com/prefix-dev/pixi/pull/3523) #### Fixed - `pixi run deno` by @Hofer-Julian in [#3484](https://github.com/prefix-dev/pixi/pull/3484) - 'pixi config list proxy-config' by @gzm55 in [#3497](https://github.com/prefix-dev/pixi/pull/3497) - Shell-hook, avoid running unexpected commands by @gzm55 in [#3493](https://github.com/prefix-dev/pixi/pull/3493) - `pixi global` stop checking for `quicklaunch` on Windows by @Hofer-Julian in [#3521](https://github.com/prefix-dev/pixi/pull/3521) #### Performance - Only call `pixi global` completion functions when necessary by @Hofer-Julian in [#3477](https://github.com/prefix-dev/pixi/pull/3477) #### Refactor - Change section header from [project] to [workspace] in the docs source files by @prsabahrami in [#3494](https://github.com/prefix-dev/pixi/pull/3494) #### New Contributors - @philipreese made their first contribution in [#3489](https://github.com/prefix-dev/pixi/pull/3489) - @danpal96 made their first contribution in [#3470](https://github.com/prefix-dev/pixi/pull/3470) ### [0.44.0] - 2025-03-31 #### ✨ Highlights - ⌨️ Support of [shell completions](https://pixi.sh/v0.44.0/global_tools/introduction/#shell-completions) with `pixi global` - πŸ› οΈ [`requires-pixi`](https://pixi.sh/v0.44.0/reference/pixi_manifest/#requires-pixi-optional) key in \`pixi.toml. This is especially useful to require a minimum Pixi version when using the manifest. - βš™οΈ Add configuration to run [post link scripts](https://pixi.sh/v0.44.0/reference/pixi_configuration/#run-post-link-scripts). This is useful for workspaces with packages which fail to work otherwise. We advise to only enable the config if it is actually needed. #### Added - Add run export information to search by @baszalmstra in [#3428](https://github.com/prefix-dev/pixi/pull/3428) - Add 'requires-pixi' manifest key and subcommands to control the eldest pixi for building a project by @gzm55 in [#3358](https://github.com/prefix-dev/pixi/pull/3358) - Add proxy-config and activate https/http proxy for pixi commands by @gzm55 in [#3320](https://github.com/prefix-dev/pixi/pull/3320) - Support shell completions with `pixi global` by @wolfv in [#3319](https://github.com/prefix-dev/pixi/pull/3319) - Add configuration to run link scripts by @ruben-arts in [#3347](https://github.com/prefix-dev/pixi/pull/3347) #### Changed - Make install.sh posix compliant by @gzm55 in [#3450](https://github.com/prefix-dev/pixi/pull/3450) #### Documentation - Remove reference to archived mybinder.org example by @scottyhq in [#3435](https://github.com/prefix-dev/pixi/pull/3435) - Tweak config naming convention note by @salim-b in [#3444](https://github.com/prefix-dev/pixi/pull/3444) - Mention self-extracting binaries in pixi_pack by @gdementen in [#3446](https://github.com/prefix-dev/pixi/pull/3446) - Remove main heading by @Hofer-Julian in [#3454](https://github.com/prefix-dev/pixi/pull/3454) - Community: add metrology-apis by @lucascolley in [#3461](https://github.com/prefix-dev/pixi/pull/3461) #### Fixed - Error on package not provided by build backend by @baszalmstra in [#3430](https://github.com/prefix-dev/pixi/pull/3430) - Git does not update source files by @nichmor in [#3425](https://github.com/prefix-dev/pixi/pull/3425) - `pixi global` make sure that `prefix_path_entries` are always in `path_diff` by @Hofer-Julian in [#3407](https://github.com/prefix-dev/pixi/pull/3407) #### Performance - Skip redundant installation in `pixi global update` by @Glatzel in [#3404](https://github.com/prefix-dev/pixi/pull/3404) #### New Contributors - @gdementen made their first contribution in [#3446](https://github.com/prefix-dev/pixi/pull/3446) - @scottyhq made their first contribution in [#3435](https://github.com/prefix-dev/pixi/pull/3435) ### [0.43.3] - 2025-03-25 #### Added - Add build folder for pixi build by @nichmor in [#3410](https://github.com/prefix-dev/pixi/pull/3410) #### Fixed - Discover closest package when running pixi build by @nichmor in [#3412](https://github.com/prefix-dev/pixi/pull/3412) - Propagate error diagnostics from backends by @baszalmstra in [#3426](https://github.com/prefix-dev/pixi/pull/3426) ### [0.43.2] - 2025-03-25 #### ✨ Highlights - Various `pixi global` fixes: [#3420](https://github.com/prefix-dev/pixi/pull/3420), [#3420](https://github.com/prefix-dev/pixi/pull/3420) - Start a non-login shell using `pixi shell`: [#3419](https://github.com/prefix-dev/pixi/pull/3419) #### Documentation - Don't mirror conda-forge's label channels by @pavelzw in [#3409](https://github.com/prefix-dev/pixi/pull/3409) #### Fixed - Broken `pixi global` migration by @Hofer-Julian in [#3420](https://github.com/prefix-dev/pixi/pull/3420) - Ignore broken shortcuts by @Hofer-Julian in [#3422](https://github.com/prefix-dev/pixi/pull/3422) - Start a non-login shell using `pixi shell` by @Ehab-Ibrahim in [#3419](https://github.com/prefix-dev/pixi/pull/3419) #### New Contributors - @Ehab-Ibrahim made their first contribution in [#3419](https://github.com/prefix-dev/pixi/pull/3419) ### [0.43.1] - 2025-03-24 #### ✨ Highlights - Fixes problems introduced with `0.43.0` - Adds support for uv mirror middleware - Makes `pixi shell` more robust. #### Changed - Upgrade uv to 0.6.9 by @gzm55 in [#3374](https://github.com/prefix-dev/pixi/pull/3374) - Global path diff by @Hofer-Julian in [#3384](https://github.com/prefix-dev/pixi/pull/3384) - Add uv mirror middlewares by @gzm55 in [#3306](https://github.com/prefix-dev/pixi/pull/3306) #### Documentation - Fix broken link in changelog by @Hofer-Julian in [#3391](https://github.com/prefix-dev/pixi/pull/3391) - Fix a typo in set_extender.md by @trim21 in [#3386](https://github.com/prefix-dev/pixi/pull/3386) - Fix redirect by @Hofer-Julian in [#3396](https://github.com/prefix-dev/pixi/pull/3396) #### Fixed - Upgrade zip to 2.4.2 by @gzm55 in [#3389](https://github.com/prefix-dev/pixi/pull/3389) - Improve shell execution by covering more edge-cases by @wolfv in [#3321](https://github.com/prefix-dev/pixi/pull/3321) - Stop requiring `PATH` for `pixi global` activation by @Hofer-Julian in [#3403](https://github.com/prefix-dev/pixi/pull/3403) - Improve error message for python integration tests by @Hofer-Julian in [#3408](https://github.com/prefix-dev/pixi/pull/3408) #### New Contributors - @trim21 made their first contribution in [#3386](https://github.com/prefix-dev/pixi/pull/3386) ### [0.43.0] - 2025-03-20 #### ✨ Highlights - πŸš€ Added support for [shortcuts](https://pixi.sh/v0.43.0/global_tools/introduction/#shortcuts) in `pixi global`. - πŸ”„ Introduced [`pixi reinstall`](https://pixi.sh/v0.43.0/reference/cli/pixi/reinstall/). - πŸ—ƒοΈ Enabled [sharded repodata](https://prefix.dev/blog/sharded_repodata) by default. - πŸ“š Big documentation improvements - Restructuring of chapters - Generated [CLI docs](https://pixi.sh/v0.43.0/reference/cli/pixi/) - Renaming `[project]` to `[workspace]` #### Added - Support for shortcuts in `pixi global` by @Hofer-Julian in [#3226](https://github.com/prefix-dev/pixi/pull/3226) - Add tutorial for pixi build rattler build by @nichmor in [#3330](https://github.com/prefix-dev/pixi/pull/3330) - Add `pixi reinstall` by @Hofer-Julian in [#3344](https://github.com/prefix-dev/pixi/pull/3344) - Add `pixi global shortcut` CLI by @ruben-arts in [#3341](https://github.com/prefix-dev/pixi/pull/3341) - `pixi exec --list` by @lucascolley in [#3311](https://github.com/prefix-dev/pixi/pull/3311) - Autogeneration of the CLI documentation. by @ruben-arts in [#3268](https://github.com/prefix-dev/pixi/pull/3268) #### Changed - Default to "workspace" with `pixi init` by @Hofer-Julian in [#3277](https://github.com/prefix-dev/pixi/pull/3277) - Enable sharded repodata by default by @ruben-arts in [#3285](https://github.com/prefix-dev/pixi/pull/3285) #### Documentation - Set sso_region in s3 config example by @pavelzw in [#3289](https://github.com/prefix-dev/pixi/pull/3289) - Refactor by @Hofer-Julian in [#3265](https://github.com/prefix-dev/pixi/pull/3265) - Adjust keep in sync note by @pavelzw in [#3297](https://github.com/prefix-dev/pixi/pull/3297) - Rename project to workspace by @Hofer-Julian in [#3300](https://github.com/prefix-dev/pixi/pull/3300) - Use consistently "Pixi" instead of "pixi" by @Hofer-Julian in [#3302](https://github.com/prefix-dev/pixi/pull/3302) - More Pixi capitalistation by @lucascolley in [#3304](https://github.com/prefix-dev/pixi/pull/3304) - Update README.md to note PATH changes go in `~/.bashrc`, not `~/.bash_profile` by @petebachant in [#3305](https://github.com/prefix-dev/pixi/pull/3305) - Clarify pixi spelling by @Hofer-Julian in [#3363](https://github.com/prefix-dev/pixi/pull/3363) - Fix typo by @pavelzw in [#3385](https://github.com/prefix-dev/pixi/pull/3385) #### Fixed - Run test_build_git_source_deps_from_tag again for Windows by @Hofer-Julian in [#3273](https://github.com/prefix-dev/pixi/pull/3273) - Print all tasks for the current platform in `pixi info` by @ruben-arts in [#3284](https://github.com/prefix-dev/pixi/pull/3284) - Fix "extra-slow" snapshot by @Hofer-Julian in [#3298](https://github.com/prefix-dev/pixi/pull/3298) - `pixi global install --force-reinstall` by @Hofer-Julian in [#3307](https://github.com/prefix-dev/pixi/pull/3307) - Mark more tests as "slow" by @Hofer-Julian in [#3310](https://github.com/prefix-dev/pixi/pull/3310) - Mark `test_pixi_auth` as extra slow by @Hofer-Julian in [#3309](https://github.com/prefix-dev/pixi/pull/3309) - Use --locked to run the generation of CLI docs by @ruben-arts in [#3322](https://github.com/prefix-dev/pixi/pull/3322) - Make --git work with --branch again by @ruben-arts in [#3323](https://github.com/prefix-dev/pixi/pull/3323) - Don't prematurely shutdown runtime by @baszalmstra in [#3325](https://github.com/prefix-dev/pixi/pull/3325) - Let amend_pypi_purls() always use reqwest client with the mirror middle ware by @gzm55 in [#3336](https://github.com/prefix-dev/pixi/pull/3336) - Update build backend configuration by @nichmor in [#3352](https://github.com/prefix-dev/pixi/pull/3352) - Use new windows runners with the dev drive feature by @ruben-arts in [#3361](https://github.com/prefix-dev/pixi/pull/3361) - Fix winget releaser job by @ruben-arts in [#3380](https://github.com/prefix-dev/pixi/pull/3380) - Use windows latest as arm build runner by @ruben-arts in [#3378](https://github.com/prefix-dev/pixi/pull/3378) - Use compilers instead of custom set of dependencies by @ruben-arts in [#3337](https://github.com/prefix-dev/pixi/pull/3337) - Some unexpected behavior of `pixi global update` by @Glatzel in [#3373](https://github.com/prefix-dev/pixi/pull/3373) #### Refactor - Replace ignore crate with pixi_glob by @prsabahrami in [#3333](https://github.com/prefix-dev/pixi/pull/3333) - Pypi mapping into cached client by @baszalmstra in [#3318](https://github.com/prefix-dev/pixi/pull/3318) #### Removed - Remove conda-build protocol by @nichmor in [#3349](https://github.com/prefix-dev/pixi/pull/3349) #### New Contributors - @Glatzel made their first contribution in [#3373](https://github.com/prefix-dev/pixi/pull/3373) - @prsabahrami made their first contribution in [#3333](https://github.com/prefix-dev/pixi/pull/3333) - @gzm55 made their first contribution in [#3336](https://github.com/prefix-dev/pixi/pull/3336) - @petebachant made their first contribution in [#3305](https://github.com/prefix-dev/pixi/pull/3305) ### [0.42.1] - 2025-03-05 #### Fixed - Ignore `__archspec` in virtual package matching by @ruben-arts in [#3281](https://github.com/prefix-dev/pixi/pull/3281) ### [0.42.0] - 2025-03-04 #### ✨ Highlights This release introduces an improved way of [dealing with Virtual Packages](https://github.com/prefix-dev/pixi/pull/2849). For example, previously pixi would not allow this configuration on a non-CUDA machine: ```toml [system-requirements] cuda = "12" [dependencies] python = "*" ``` Now this setup also works on non-CUDA machines, because it only stops if the packages themselves actually depend on CUDA. This is a first step to make the use of system-requirements/virtual-packages more flexible. #### Changed - Validate machine using lockfile by @ruben-arts in [#2849](https://github.com/prefix-dev/pixi/pull/2849) - Upgrade `uv` crates to `0.6.1` by @nichmor in [#3216](https://github.com/prefix-dev/pixi/pull/3216) #### Documentation - Add s3 upload section by @pavelzw in [#3168](https://github.com/prefix-dev/pixi/pull/3168) - Document cmake build backend `extra-args` by @wolfv in [#3167](https://github.com/prefix-dev/pixi/pull/3167) - Sync pixi-pack docs with PR #104 (add --use-cache) by @awesomebytes in [#3189](https://github.com/prefix-dev/pixi/pull/3189) - Mention add_pip_as_python_dependency in compatibility mode for pixi-pack by @pavelzw in [#3188](https://github.com/prefix-dev/pixi/pull/3188) - Mention run-install in setup-pixi documentation by @pavelzw in [#3185](https://github.com/prefix-dev/pixi/pull/3185) - Update python.md by @carschandler in [#3220](https://github.com/prefix-dev/pixi/pull/3220) - Add section about using `pixi exec` in shebangs by @pavelzw in [#3201](https://github.com/prefix-dev/pixi/pull/3201) - Fix snake_case config note by @salim-b in [#3232](https://github.com/prefix-dev/pixi/pull/3232) - Fix note about config locations by @salim-b in [#3231](https://github.com/prefix-dev/pixi/pull/3231) - Fix note formatting by @salim-b in [#3230](https://github.com/prefix-dev/pixi/pull/3230) - Improve looks of a link by @ruben-arts in [#3229](https://github.com/prefix-dev/pixi/pull/3229) - Add rattler-index s3 documentation by @pavelzw in [#3175](https://github.com/prefix-dev/pixi/pull/3175) - Minor fix (three -> four) by @tylere in [#3240](https://github.com/prefix-dev/pixi/pull/3240) - Add documentation about starship by @pavelzw in [#3242](https://github.com/prefix-dev/pixi/pull/3242) - Add missing docs for `pixi install --all` by @Hofer-Julian in [#3256](https://github.com/prefix-dev/pixi/pull/3256) - Typo in cli.md by @boisgera in [#3210](https://github.com/prefix-dev/pixi/pull/3210) #### Fixed - Improve UX on missing platforms by @ruben-arts in [#3169](https://github.com/prefix-dev/pixi/pull/3169) - Allow usage of `--branch` `--tag` `--rev` for `--pypi` with `git` by @nichmor in [#3132](https://github.com/prefix-dev/pixi/pull/3132) - Flush `shell` activation file after writing by @wolfv in [#3130](https://github.com/prefix-dev/pixi/pull/3130) - Improve `pixi list` output for conda source packages by @ruben-arts in [#3170](https://github.com/prefix-dev/pixi/pull/3170) - Pixi global revert error message by @Hofer-Julian in [#3207](https://github.com/prefix-dev/pixi/pull/3207) - Return err when `pixi list` doesn't find pkg by @savente93 in [#3212](https://github.com/prefix-dev/pixi/pull/3212) - Add caching of regular build by @tdejager in [#3238](https://github.com/prefix-dev/pixi/pull/3238) #### Refactor - Moving of types, renames and error updates by @tdejager in [#3228](https://github.com/prefix-dev/pixi/pull/3228) #### New Contributors - @salim-b made their first contribution in [#3230](https://github.com/prefix-dev/pixi/pull/3230) - @savente93 made their first contribution in [#3212](https://github.com/prefix-dev/pixi/pull/3212) - @boisgera made their first contribution in [#3210](https://github.com/prefix-dev/pixi/pull/3210) - @xiaoxiangmoe made their first contribution in [#3191](https://github.com/prefix-dev/pixi/pull/3191) - @awesomebytes made their first contribution in [#3189](https://github.com/prefix-dev/pixi/pull/3189) ### [0.41.4] - 2025-02-18 #### ✨ Highlights This release add support for S3 backends. You can configure a custom S3 backend in your `pixi.toml` file. This allows you to use a custom S3 bucket as a channel for your project. ```toml # pixi.toml [project] channels = ["s3://my-bucket/custom-channel"] [project.s3-options.my-bucket] endpoint-url = "https://my-s3-host" region = "us-east-1" force-path-style = false ``` #### Changed - Implement `package.build.configuration` parsing by @wolfv in [#3115](https://github.com/prefix-dev/pixi/pull/3115) - Add S3 backend support by @delsner in [#2825](https://github.com/prefix-dev/pixi/pull/2825) #### Documentation - Add S3 documentation by @pavelzw in [#2835](https://github.com/prefix-dev/pixi/pull/2835) - Document git dependencies in pixi build documentation by @nichmor in [#3126](https://github.com/prefix-dev/pixi/pull/3126) #### Fixed - Manually exposed executables are removed after `pixi global update` by @Hofer-Julian in [#3109](https://github.com/prefix-dev/pixi/pull/3109) - Changing cmake doesn't trigger rebuild by @Hofer-Julian in [#3102](https://github.com/prefix-dev/pixi/pull/3102) - `BUILD_EDITABLE_PYTHON` env flag by @Hofer-Julian in [#3128](https://github.com/prefix-dev/pixi/pull/3128) - Change the progress message during mapping of packages by @tdejager in [#3155](https://github.com/prefix-dev/pixi/pull/3155) - Skip unneeded url parse and only add git+ when needed by @ruben-arts in [#3139](https://github.com/prefix-dev/pixi/pull/3139) - Reinstall if required is source and installed is from registry by @ruben-arts in [#3131](https://github.com/prefix-dev/pixi/pull/3131) ### [0.41.3] - 2025-02-12 #### Changed - Added `--dry-run` flag to pixi run by @noamgot in [#3107](https://github.com/prefix-dev/pixi/pull/3107) #### Fixed - Make prefix creation during solve thread-safe by @nichmor in [#3099](https://github.com/prefix-dev/pixi/pull/3099) - Passing a file as `--manifest-path` by @tdejager in [#3111](https://github.com/prefix-dev/pixi/pull/3111) #### New Contributors - @noamgot made their first contribution in [#3107](https://github.com/prefix-dev/pixi/pull/3107) ### [0.41.2] - 2025-02-11 #### ✨ Highlights This release introduces the ability to add environment variables to the `init --import` command. We also upgraded the `uv` crate to `v0.5.29`. #### Changed - Add environment variables to `init --import` by @zklaus in [#3083](https://github.com/prefix-dev/pixi/pull/3083) - Upgrade uv to `v0.5.29` by @tdejager in [#3075](https://github.com/prefix-dev/pixi/pull/3075) #### Documentation - Add Bodo to Community.md by @IsaacWarren in [#3103](https://github.com/prefix-dev/pixi/pull/3103) #### Fixed - Json Schema by @Hofer-Julian in [#3082](https://github.com/prefix-dev/pixi/pull/3082) - Getting records for wrong platform by @tdejager in [#3084](https://github.com/prefix-dev/pixi/pull/3084) #### Refactor - Split workspace and package manifests by @baszalmstra in [#3043](https://github.com/prefix-dev/pixi/pull/3043) - Env module by @tdejager in [#3074](https://github.com/prefix-dev/pixi/pull/3074) #### New Contributors - @IsaacWarren made their first contribution in [#3103](https://github.com/prefix-dev/pixi/pull/3103) - @zklaus made their first contribution in [#3083](https://github.com/prefix-dev/pixi/pull/3083) ### [0.41.1] - 2025-02-07 #### Fixed - Pixi authentication by @ruben-arts in [#3070](https://github.com/prefix-dev/pixi/pull/3070) ### [0.41.0] - 2025-02-05 #### ✨ Highlights This release introduces lazily creating solve environments for the `pypi-dependencies` resulting in a significant speedup for environments that only depend on wheels. If you want to force the use of wheels you can now also set `no-build` in the `pypi-options` table. To test this you can now just use `pixi lock` to create a lockfile without installing an environment. #### Added - Add `pixi lock` by @Hofer-Julian in [#3061](https://github.com/prefix-dev/pixi/pull/3061) and [#3064](https://github.com/prefix-dev/pixi/pull/3064) - Add `no-build` to `pypi-options` by @tdejager in [#2997](https://github.com/prefix-dev/pixi/pull/2997) #### Changed - Lazily initiate solve environments for `pypi-dependencies` by @nichmor and @tdejager in [#3029](https://github.com/prefix-dev/pixi/pull/3029) - Use Github Releases `/latest` for `self-update` and prompt on downgrades by @jaimergp in [#2989](https://github.com/prefix-dev/pixi/pull/2989) - Set PS1 in shell-hook too by @jaimergp in [#2991](https://github.com/prefix-dev/pixi/pull/2991) - Prevent line-based 3-way merge on pixi.lock by @ChristianRothQC in [#3019](https://github.com/prefix-dev/pixi/pull/3019) - Auto-prepend 'v' to version numbers during pixi installation by @m-naumann in [#3000](https://github.com/prefix-dev/pixi/pull/3000) - Parse labels and related errors from build backend by @baszalmstra in [#2952](https://github.com/prefix-dev/pixi/pull/2952) #### Documentation - Enable autocomplete on Zsh by @ywilke in [#3009](https://github.com/prefix-dev/pixi/pull/3009) - Add section on aws codeartifact by @rayduck in [#3020](https://github.com/prefix-dev/pixi/pull/3020) - Add `pixi-diff` documentation by @pavelzw in [#3025](https://github.com/prefix-dev/pixi/pull/3025) - Fix python tutorial by @ruben-arts in [#3035](https://github.com/prefix-dev/pixi/pull/3035) #### Fixed - Always show cursor after control+c by @ruben-arts in [#2635](https://github.com/prefix-dev/pixi/pull/2635) - `mirrors` configuration follows correct priority by @ruben-arts in [#3002](https://github.com/prefix-dev/pixi/pull/3002) - Don't check requires python in satisfiability by @ruben-arts in [#2968](https://github.com/prefix-dev/pixi/pull/2968) - Enforce recompile trampoline by @Hofer-Julian in [#3013](https://github.com/prefix-dev/pixi/pull/3013) - `project platform remove` by @Hofer-Julian in [#3017](https://github.com/prefix-dev/pixi/pull/3017) - Lockfile not invalidated when we remove platforms by @Hofer-Julian in [#3027](https://github.com/prefix-dev/pixi/pull/3027) - Will also update prefix if there are pypi path dependencies by @tdejager in [#3034](https://github.com/prefix-dev/pixi/pull/3034) - Initialize rayon late and use uv from tag by @baszalmstra in [#2957](https://github.com/prefix-dev/pixi/pull/2957) - Change back to multithreaded runtime by @tdejager in [#3041](https://github.com/prefix-dev/pixi/pull/3041) - Logic was backward for creating missing .bashrc by @hjmjohnson in [#3051](https://github.com/prefix-dev/pixi/pull/3051) - Do proper sanity check on add and run by @ruben-arts in [#3054](https://github.com/prefix-dev/pixi/pull/3054) - Add check error message to remove uv dependencies by @Dozie2001 in [#3052](https://github.com/prefix-dev/pixi/pull/3052) #### Refactor - Make diff module public by @pavelzw in [#3010](https://github.com/prefix-dev/pixi/pull/3010) - Enforce no `unwrap` via clippy by @Hofer-Julian in [#3006](https://github.com/prefix-dev/pixi/pull/3006) - Improve AuthenticationStorage, update rattler by @pavelzw in [#2909](https://github.com/prefix-dev/pixi/pull/2909) #### Removed - Remove `description` from `pixi init` template by @Hofer-Julian in [#3012](https://github.com/prefix-dev/pixi/pull/3012) #### New Contributors - @Dozie2001 made their first contribution in [#3052](https://github.com/prefix-dev/pixi/pull/3052) - @hjmjohnson made their first contribution in [#3051](https://github.com/prefix-dev/pixi/pull/3051) - @m-naumann made their first contribution in [#3000](https://github.com/prefix-dev/pixi/pull/3000) - @ChristianRothQC made their first contribution in [#3019](https://github.com/prefix-dev/pixi/pull/3019) - @rayduck made their first contribution in [#3020](https://github.com/prefix-dev/pixi/pull/3020) - @ywilke made their first contribution in [#3009](https://github.com/prefix-dev/pixi/pull/3009) ### [0.40.3] - 2025-01-22 #### ✨ Highlights This release will greatly improve the `git` dependency experience for PyPI packages. #### Added - Add nushell autocompletion for pixi r by @dennis-wey in [#2935](https://github.com/prefix-dev/pixi/pull/2935) #### Changed - Pin backend versions by @tdejager in [#2963](https://github.com/prefix-dev/pixi/pull/2963) #### Documentation - Add `quantity-array` to community by @lucascolley in [#2955](https://github.com/prefix-dev/pixi/pull/2955) - Add multiple environment tutorial by @ruben-arts in [#2949](https://github.com/prefix-dev/pixi/pull/2949) - Use workspace channels for build tutorials by @Hofer-Julian in [#2940](https://github.com/prefix-dev/pixi/pull/2940) - Fix ambiguous version specifiers by @Hofer-Julian in [#2967](https://github.com/prefix-dev/pixi/pull/2967) - Fix broken links to anchors by @Hofer-Julian in [#2941](https://github.com/prefix-dev/pixi/pull/2941) #### Fixed - Fix `branch`, `tag` and `rev` for `pypi-dependencies` by @nichmor in [#2960](https://github.com/prefix-dev/pixi/pull/2960) - `pixi list` should print the git location instead of the wheel by @ruben-arts in [#2962](https://github.com/prefix-dev/pixi/pull/2962) - Improve debuggability of the list output by @ruben-arts in [#2975](https://github.com/prefix-dev/pixi/pull/2975) - Also warn about detached environments on Windows by @Hofer-Julian in [#2985](https://github.com/prefix-dev/pixi/pull/2985) - Fix binaries for linux-aarch64 by @ruben-arts in [#2937](https://github.com/prefix-dev/pixi/pull/2937) #### Refactor - Use destructuring to remove clones in conversion by @KGrewal1 in [#2969](https://github.com/prefix-dev/pixi/pull/2969) ### [0.40.2] - 2025-01-17 #### Added - Add a progress bar for source ( git ) dependencies by @nichmor in [#2898](https://github.com/prefix-dev/pixi/pull/2898) #### Changed - Split into 'source' and 'binary' build types by @tdejager in [#2903](https://github.com/prefix-dev/pixi/pull/2903) #### Documentation - Update index.md - windows install command by @raybellwaves in [#2871](https://github.com/prefix-dev/pixi/pull/2871) - Fix `project_model` module docs by @Hofer-Julian in [#2928](https://github.com/prefix-dev/pixi/pull/2928) - Pixi build variants by @baszalmstra in [#2901](https://github.com/prefix-dev/pixi/pull/2901) #### Fixed - CamelCase project protocol types by @baszalmstra in [#2907](https://github.com/prefix-dev/pixi/pull/2907) - Rewrite prefix guard into async by @nichmor in [#2908](https://github.com/prefix-dev/pixi/pull/2908) - Double_lines in copy of docs by @ruben-arts in [#2913](https://github.com/prefix-dev/pixi/pull/2913) - Stackoverflow when running pixi in debug mode on windows by @baszalmstra in [#2922](https://github.com/prefix-dev/pixi/pull/2922) - `pixi run --help` by @Hofer-Julian in [#2918](https://github.com/prefix-dev/pixi/pull/2918) - Shell hang on progress bar by @baszalmstra in [#2929](https://github.com/prefix-dev/pixi/pull/2929) - Take into account the variants for the source cache by @baszalmstra in [#2877](https://github.com/prefix-dev/pixi/pull/2877) - Pixi init by @Hofer-Julian in [#2930](https://github.com/prefix-dev/pixi/pull/2930) #### New Contributors - @raybellwaves made their first contribution in [#2871](https://github.com/prefix-dev/pixi/pull/2871) ### [0.40.1] - 2025-01-14 #### ✨ Highlights We've **reverted** the breaking change of the `depends_on` field from `0.40.0`, replacing it with a [warning](https://github.com/prefix-dev/pixi/pull/2891). This release also brings a [performance boost](https://github.com/prefix-dev/pixi/pull/2874) to our Windows and Linux-musl builds by using faster allocators. On the ([holoviews](https://github.com/holoviz/holoviews)) project, we measured a significant speedup: ```shell # Linux musl Summary pixi-0.40.1 list --no-install ran 12.65 Β± 0.46 times faster than pixi-0.40.0 list --no-install # Windows pixi-0.40.1 list --no-install ran 1.66 Β± 0.07 times faster than pixi-0.40.0 list --no-install 1.67 Β± 0.09 times faster than pixi-0.39.5 list --no-install 2.10 Β± 0.09 times faster than pixi-0.39.4 list --no-install ``` #### Fixed - Pyproject `entry-points` by @atmorling in [#2886](https://github.com/prefix-dev/pixi/pull/2886) - Print warning when pixi manifest is not parsed in pixi search by @pavelzw in [#2889](https://github.com/prefix-dev/pixi/pull/2889) - Add deprecation notice for `depends_on` by @baszalmstra in [#2891](https://github.com/prefix-dev/pixi/pull/2891) #### Performance - Use faster allocators by @baszalmstra in [#2874](https://github.com/prefix-dev/pixi/pull/2874) #### Refactor - Add `online_tests` feature to control Internet use by @mgorny in [#2881](https://github.com/prefix-dev/pixi/pull/2881) - Simplify repodata_gateway function by @olivier-lacroix in [#1793](https://github.com/prefix-dev/pixi/pull/1793) - Spawn main entrypoint in box by @baszalmstra in [#2892](https://github.com/prefix-dev/pixi/pull/2892) #### New Contributors - @atmorling made their first contribution in [#2886](https://github.com/prefix-dev/pixi/pull/2886) - @mgorny made their first contribution in [#2881](https://github.com/prefix-dev/pixi/pull/2881) ### [0.40.0] - 2025-01-10 #### ✨ Highlights Manifest file parsing has been significantly improved. Errors will now be clearer and more helpful, for example: ```shell Γ— Expected one of 'first-index', 'unsafe-first-match', 'unsafe-best-match' ╭─[pixi.toml:2:27] 1 β”‚ 2 β”‚ index-strategy = "UnsafeFirstMatch" Β· ──────────────── 3 β”‚ ╰──── help: Did you mean 'unsafe-first-match'? ``` #### Breaking Change Alert: The `depends_on` field has been renamed to `depends-on` for better consistency. Using the old format without a dash (depends_on) will now result in an error. The new errors should help you find the location: ```shell Error: Γ— field 'depends_on' is deprecated, 'depends-on' has replaced it ╭─[pixi.toml:22:51] 21 β”‚ install = "cargo install --path . --locked" 22 β”‚ install-as = { cmd = "python scripts/install.py", depends_on = [ Β· ─────┬──── Β· ╰── replace this with 'depends-on' 23 β”‚ "build-release", ╰──── ``` #### Added - Pixi add git source dependency by @nichmor in [#2858](https://github.com/prefix-dev/pixi/pull/2858) #### Documentation - Fix installation docs mistake in index.md by @PanTheDev in [#2869](https://github.com/prefix-dev/pixi/pull/2869) #### Fixed - Create missing global manifest folder with pixi global edit by @zbowling in [#2847](https://github.com/prefix-dev/pixi/pull/2847) - Pixi add creates a project by @nichmor in [#2861](https://github.com/prefix-dev/pixi/pull/2861) - Initialized detached envs with None by @ruben-arts in [#2841](https://github.com/prefix-dev/pixi/pull/2841) #### `pixi build` Preview work - Build backend docs by @tdejager in [#2844](https://github.com/prefix-dev/pixi/pull/2844) - Move pixi build type conversions into its own crate by @tdejager in [#2866](https://github.com/prefix-dev/pixi/pull/2866) - Expose build type v1 function by @tdejager in [#2875](https://github.com/prefix-dev/pixi/pull/2875) - Use toml-span for deserialization by @baszalmstra in [#2718](https://github.com/prefix-dev/pixi/pull/2718) - Expands options for setting pixi-build override options by @tdejager in [#2843](https://github.com/prefix-dev/pixi/pull/2843) - Split capability retrieval from initialize by @tdejager in [#2831](https://github.com/prefix-dev/pixi/pull/2831) - Move package fields under `[package]`. by @baszalmstra in [#2731](https://github.com/prefix-dev/pixi/pull/2731) - Extract pixi manifest info into protocol by @tdejager in [#2850](https://github.com/prefix-dev/pixi/pull/2850) #### New Contributors - @PanTheDev made their first contribution in [#2869](https://github.com/prefix-dev/pixi/pull/2869) ### [0.39.5] - 2025-01-06 #### ✨ Highlights By updating [`resolvo`](https://github.com/mamba-org/resolvo/pull/91) to the latest version we now significantly lower the RAM usage during the solve process. πŸš€ As this improvement removes a huge set of data from the solve step it also speeds it up even more, especially for hard to solve environments. Some numbers from the `resolvo` PR, based on the resolve test dataset: ```text - Average Solve Time: 'pixi v0.39.5' was 1.68 times faster than 'pixi v0.39.4' - Median Solve Time: 'pixi v0.39.5' was 1.33 times faster than 'pixi v0.39.4' - 25th Percentile: 'pixi v0.39.5' was 1.22 times faster than 'pixi v0.39.4' - 75th Percentile: 'pixi v0.39.5' was 2.28 times faster than 'pixi v0.39.4' ``` #### Added - Add cli modifications of the system requirements by @ruben-arts in [#2765](https://github.com/prefix-dev/pixi/pull/2765) - Support `--manifest-path` to project directory by @blmaier in [#2716](https://github.com/prefix-dev/pixi/pull/2716) #### Changed - Make binary, config folder, and lock file names dynamic by @zbowling in [#2775](https://github.com/prefix-dev/pixi/pull/2775) #### Documentation - Add `marray` to community by @lucascolley in [#2774](https://github.com/prefix-dev/pixi/pull/2774) - Simplify nushell completion script by @Hofer-Julian in [#2782](https://github.com/prefix-dev/pixi/pull/2782) - Fix typo in PyCharm integration doc by @stevenschaerer in [#2766](https://github.com/prefix-dev/pixi/pull/2766) - Do not depend on gxx in pixi build docs by @traversaro in [#2815](https://github.com/prefix-dev/pixi/pull/2815) - Fix typo by @pavelzw in [#2833](https://github.com/prefix-dev/pixi/pull/2833) #### Fixed - Move away from lazy_static by @Hofer-Julian in [#2781](https://github.com/prefix-dev/pixi/pull/2781) - Don't modify manifest on failing `pixi add/upgrade` by @ruben-arts in [#2756](https://github.com/prefix-dev/pixi/pull/2756) - Ignore .pixi folder for build by @baszalmstra in [#2801](https://github.com/prefix-dev/pixi/pull/2801) - Use correct directory for build artifact cache by @baszalmstra in [#2830](https://github.com/prefix-dev/pixi/pull/2830) - Detect Freethreading Python by @nichmor in [#2762](https://github.com/prefix-dev/pixi/pull/2762) #### New Contributors - @stevenschaerer made their first contribution in [#2766](https://github.com/prefix-dev/pixi/pull/2766) - @zbowling made their first contribution in [#2775](https://github.com/prefix-dev/pixi/pull/2775) ### [0.39.4] - 2024-12-23 #### ✨ Highlights Last release got an additional speedup for macOS specifically! πŸš€ #### Performance - Speedup environment installation on macOS by @wolfv in [#2754](https://github.com/prefix-dev/pixi/pull/2701) #### Added - Add script to build trampolines by @Hofer-Julian in [#2752](https://github.com/prefix-dev/pixi/pull/2752) #### Changed - Serialize system requirements by @ruben-arts in [#2753](https://github.com/prefix-dev/pixi/pull/2753) #### Documentation - Add pytorch integration guide. by @ruben-arts in [#2711](https://github.com/prefix-dev/pixi/pull/2711) #### Fixed - Rename the ppc binary archive by @ruben-arts in [#2750](https://github.com/prefix-dev/pixi/pull/2750) - Retry on http failures by @Hofer-Julian in [#2755](https://github.com/prefix-dev/pixi/pull/2755) #### `pixi build` Preview work - Update reference for pixi build by @Hofer-Julian in [#2735](https://github.com/prefix-dev/pixi/pull/2735) - Add tutorial for pixi build workspace by @Hofer-Julian in [#2727](https://github.com/prefix-dev/pixi/pull/2727) - Add support for git source dependencies in pixi build by @nichmor in [#2680](https://github.com/prefix-dev/pixi/pull/2680) ### [0.39.3] - 2024-12-18 #### ✨ Highlights This release includes a little Christmas present, the environment installation got a huge speedup! πŸš€ #### Performance - Speedup environment installation by @baszalmstra and @wolfv in [#2701](https://github.com/prefix-dev/pixi/pull/2701) #### Fixed - `pixi global sync` reports after each handled environment by @Hofer-Julian in [#2698](https://github.com/prefix-dev/pixi/pull/2698) - Config search order by @Hofer-Julian in [#2702](https://github.com/prefix-dev/pixi/pull/2702) - Enforce rust-tls for reqwest by @Hofer-Julian in [#2719](https://github.com/prefix-dev/pixi/pull/2719) - Help user with lockfile update error by @ruben-arts in [#2684](https://github.com/prefix-dev/pixi/pull/2684) - Add broken curl version check in install.sh by @thewtex in [#2686](https://github.com/prefix-dev/pixi/pull/2686) - Avoid race condition on bariercell when future is instant by @baszalmstra in [#2736](https://github.com/prefix-dev/pixi/pull/2736) - Log config parsing errors as errors by @Hofer-Julian in [#2739](https://github.com/prefix-dev/pixi/pull/2739) #### `pixi build` Preview work - Introduction to pixi build by @tdejager in [#2685](https://github.com/prefix-dev/pixi/pull/2685) - Add community example to ROS2 tutorial by @Daviesss in [#2713](https://github.com/prefix-dev/pixi/pull/2713) - Add tutorial for Python and pixi-build by @Hofer-Julian in [#2715](https://github.com/prefix-dev/pixi/pull/2715) - C++ package pixi build example by @tdejager in [#2717](https://github.com/prefix-dev/pixi/pull/2717) - Add target to workspace by @wolfv in [#2655](https://github.com/prefix-dev/pixi/pull/2655) - Support editable install for `pixi build` by @Hofer-Julian in [#2661](https://github.com/prefix-dev/pixi/pull/2661) #### New Contributors - @Daviesss made their first contribution in [#2713](https://github.com/prefix-dev/pixi/pull/2713) - @thewtex made their first contribution in [#2686](https://github.com/prefix-dev/pixi/pull/2686) ### [0.39.2] - 2024-12-11 Patch release to fix the binary generation in CI. ### [0.39.1] - 2024-12-09 #### Added - Add proper unit testing for PyPI installation and fix re-installation issues by @tdejager in [#2617](https://github.com/prefix-dev/pixi/pull/2617) - Add detailed json output for task list by @jjjermiah in [#2608](https://github.com/prefix-dev/pixi/pull/2608) - Add `pixi project name` CLI by @LiamConnors in [#2649](https://github.com/prefix-dev/pixi/pull/2649) #### Changed - Use `fs-err` in more places by @Hofer-Julian in [#2636](https://github.com/prefix-dev/pixi/pull/2636) #### Documentation - Remove `tclf` from community.mdπŸ“‘ by @KarelZe in [#2619](https://github.com/prefix-dev/pixi/pull/2619) - Update contributing guide by @LiamConnors in [#2650](https://github.com/prefix-dev/pixi/pull/2650) - Update clean cache CLI doc by @LiamConnors in [#2657](https://github.com/prefix-dev/pixi/pull/2657) #### Fixed - Color formatting detection on stdout by @blmaier in [#2613](https://github.com/prefix-dev/pixi/pull/2613) - Use correct dependency location for `pixi upgrade` by @Hofer-Julian in [#2472](https://github.com/prefix-dev/pixi/pull/2472) - Regression `detached-environments` not used by @ruben-arts in [#2627](https://github.com/prefix-dev/pixi/pull/2627) - Allow configuring pypi insecure host by @zen-xu in [#2521](https://github.com/prefix-dev/pixi/pull/2521)[#2622](https://github.com/prefix-dev/pixi/pull/2622) #### Refactor - Rework CI and use `cargo-dist` for releases by @baszalmstra in [#2566](https://github.com/prefix-dev/pixi/pull/2566) #### `pixi build` Preview work - Refactor to `[build-system.build-backend]` by @baszalmstra in [#2601](https://github.com/prefix-dev/pixi/pull/2601) - Remove ipc override from options and give it manually to test by @wolfv in [#2629](https://github.com/prefix-dev/pixi/pull/2629) - Pixi build trigger rebuild by @Hofer-Julian in [#2641](https://github.com/prefix-dev/pixi/pull/2641) - Add variant config to `[workspace.build-variants]` by @wolfv in [#2634](https://github.com/prefix-dev/pixi/pull/2634) - Add request coalescing for isolated tools by @nichmor in [#2589](https://github.com/prefix-dev/pixi/pull/2589) - Add example using `rich` and `pixi-build-python` and remove flask by @Hofer-Julian in [#2638](https://github.com/prefix-dev/pixi/pull/2638) - (simple) build tool override by @wolfv in [#2620](https://github.com/prefix-dev/pixi/pull/2620) - Add caching of build tool installation by @nichmor in [#2637](https://github.com/prefix-dev/pixi/pull/2637) #### New Contributors - @blmaier made their first contribution in [#2613](https://github.com/prefix-dev/pixi/pull/2613) ### [0.39.0] - 2024-12-02 #### ✨ Highlights - We now have a new `concurrency` configuration in the `pixi.toml` file. This allows you to set the number of concurrent solves or downloads that can be run at the same time. - We changed the way pixi searches for a pixi manifest. Where it was previously first considering the activated `pixi shell`, it will now search first in the current directory and its parent directories. [more info](https://github.com/prefix-dev/pixi/pull/2564) - The lockfile format is changed to make it slightly smaller and support source dependencies. #### Added - Add `concurrency` configuration by @ruben-arts in [#2569](https://github.com/prefix-dev/pixi/pull/2569) #### Changed - Add `XDG_CONFIG_HOME`/`.config` to search of pixi global manifest path by @hoxbro in [#2547](https://github.com/prefix-dev/pixi/pull/2547) - Let `pixi global sync` collect errors rather than returning early by @Hofer-Julian in [#2586](https://github.com/prefix-dev/pixi/pull/2586) - Allow configuring pypi insecure host by @zen-xu in [#2521](https://github.com/prefix-dev/pixi/pull/2521) - Reorder manifest discovery logic by @Hofer-Julian in [#2564](https://github.com/prefix-dev/pixi/pull/2564) #### Documentation - Improve pixi manifest by @Hofer-Julian in [#2596](https://github.com/prefix-dev/pixi/pull/2596) #### Fixed - `pixi global list` failing for empty environments by @Hofer-Julian in [#2571](https://github.com/prefix-dev/pixi/pull/2571) - Macos activation cargo vars by @ruben-arts in [#2578](https://github.com/prefix-dev/pixi/pull/2578) - Trampoline without corresponding json breaking by @Hofer-Julian in [#2576](https://github.com/prefix-dev/pixi/pull/2576) - Ensure pinning strategy is not affected by non-semver packages by @seowalex in [#2580](https://github.com/prefix-dev/pixi/pull/2580) - Pypi installs happening every time by @tdejager in [#2587](https://github.com/prefix-dev/pixi/pull/2587) - `pixi global` report formatting by @Hofer-Julian in [#2595](https://github.com/prefix-dev/pixi/pull/2595) - Improve test speed and support win-arm64 by @baszalmstra in [#2597](https://github.com/prefix-dev/pixi/pull/2597) - Update Task::Alias to return command description by @jjjermiah in [#2607](https://github.com/prefix-dev/pixi/pull/2607) #### Refactor - Split install pypi into module and files by @tdejager in [#2590](https://github.com/prefix-dev/pixi/pull/2590) - PyPI installation traits + deduplication by @tdejager in [#2599](https://github.com/prefix-dev/pixi/pull/2599) #### Pixi build We've merged in the main `pixi build` feature branch. This is a big change but shouldn't have affected any of the current functionality. If you notice any issues, please let us know. It can be turned on by `preview = "pixi-build"` in your `pixi.toml` file. It's under heavy development so expect breaking changes in that feature for now. - Preview of `pixi build` and workspaces by @tdejager in [#2250](https://github.com/prefix-dev/pixi/pull/2250) - Build recipe yaml directly by @wolfv in [#2568](https://github.com/prefix-dev/pixi/pull/2568) #### New Contributors - @seowalex made their first contribution in [#2580](https://github.com/prefix-dev/pixi/pull/2580) ### [0.38.0] - 2024-11-26 #### ✨ Highlights - Specify `pypi-index` per pypi-dependency ```toml [pypi-dependencies] pytorch ={ version = "*", index = "https://download.pytorch.org/whl/cu118" } ``` - `[dependency-groups]` (PEP735) support in `pyproject.toml` ```toml [dependency-groups] test = ["pytest"] docs = ["sphinx"] dev = [{include-group = "test"}, {include-group = "docs"}] [tool.pixi.environments] dev = ["dev"] ``` - Much improved `pixi search` output! #### Added - Add pypi index by @nichmor in [#2416](https://github.com/prefix-dev/pixi/pull/2416) - Implement PEP735 support by @olivier-lacroix in [#2448](https://github.com/prefix-dev/pixi/pull/2448) - Extends manifest to allow for `preview` features by @tdejager in [#2489](https://github.com/prefix-dev/pixi/pull/2489) - Add versions/build list to `pixi search` output by @delsner in [#2440](https://github.com/prefix-dev/pixi/pull/2440) - Expose nested executables in `pixi global` by @bahugo in [#2362](https://github.com/prefix-dev/pixi/pull/2362) #### Fixed - Always print a warning when config is invalid by @Hofer-Julian in [#2508](https://github.com/prefix-dev/pixi/pull/2508) - Incorrectly saving absolute base as path component by @tdejager in [#2501](https://github.com/prefix-dev/pixi/pull/2501) - Keep the case when getting the executable in `pixi global` by @wolfv in [#2528](https://github.com/prefix-dev/pixi/pull/2528) - Install script on `win-arm64` by @baszalmstra in [#2538](https://github.com/prefix-dev/pixi/pull/2538) - Trampoline installation on `pixi global update` by @nichmor in [#2530](https://github.com/prefix-dev/pixi/pull/2530) - Update the `PATH` env var with dynamic elements on `pixi global` by @wolfv in [#2541](https://github.com/prefix-dev/pixi/pull/2541) - Correct `ppc64le` arch by @wolfv in [#2540](https://github.com/prefix-dev/pixi/pull/2540) #### Performance - Experimental environment activation cache by @ruben-arts in [#2367](https://github.com/prefix-dev/pixi/pull/2367) #### Documentation - Update project structure in Python tutorial by @LiamConnors in [#2506](https://github.com/prefix-dev/pixi/pull/2506) - Fix typo in `pixi project export conda-environment` by @nmarticorena in [#2533](https://github.com/prefix-dev/pixi/pull/2533) - Fix wrong use of underscores in `pixi project export` by @traversaro in [#2539](https://github.com/prefix-dev/pixi/pull/2539) - Adapt completion instructions by @Hofer-Julian in [#2561](https://github.com/prefix-dev/pixi/pull/2561) #### New Contributors - @nmarticorena made their first contribution in [#2533](https://github.com/prefix-dev/pixi/pull/2533) - @delsner made their first contribution in [#2440](https://github.com/prefix-dev/pixi/pull/2440) ### [0.37.0] - 2024-11-18 #### ✨ Highlights We now allow the use of `prefix.dev` channels with sharded repodata: Running `pixi search rubin-env` using `hyperfine` on the default versus our channels gives these results: | Cache Status | Channel | Mean [ms] | Relative | | ------------ | ---------------------------------------- | --------- | -------- | | With cache | `https://prefix.dev/conda-forge` | 69.3 | 1.00 | | Without | `https://prefix.dev/conda-forge` | 389.5 | 5.62 | | With cache | `https://conda.anaconda.org/conda-forge` | 1043.3 | 15.06 | | Without | `https://conda.anaconda.org/conda-forge` | 2420.3 | 34.94 | #### Breaking - Make sure that `[activation.env]` are not completely overridden by `[target.` tables, by @hameerabbasi in [#2396](https://github.com/prefix-dev/pixi/pull/2396) #### Changed - Allow using sharded repodata by @baszalmstra in [#2467](https://github.com/prefix-dev/pixi/pull/2467) #### Documentation - Update ros2.md turtlesim section by @nbbrooks in [#2442](https://github.com/prefix-dev/pixi/pull/2442) - Update pycharm.md to show optional installation by @plainerman in [#2487](https://github.com/prefix-dev/pixi/pull/2487) - Fix typo in documentation by @saraedum in [#2496](https://github.com/prefix-dev/pixi/pull/2496) - Update pixi install output by @LiamConnors in [#2495](https://github.com/prefix-dev/pixi/pull/2495) #### Fixed - Incorrect python version was used in some parts of the solve by @tdejager in [#2481](https://github.com/prefix-dev/pixi/pull/2481) - Wrong description on pixi upgrade by @notPlancha in [#2483](https://github.com/prefix-dev/pixi/pull/2483) - Extra test for mismatch in python versions by @tdejager in [#2485](https://github.com/prefix-dev/pixi/pull/2485) - Keep `build` in `pixi upgrade` by @ruben-arts in [#2476](https://github.com/prefix-dev/pixi/pull/2476) #### New Contributors - @saraedum made their first contribution in [#2496](https://github.com/prefix-dev/pixi/pull/2496) - @plainerman made their first contribution in [#2487](https://github.com/prefix-dev/pixi/pull/2487) - @hameerabbasi made their first contribution in [#2396](https://github.com/prefix-dev/pixi/pull/2396) - @nbbrooks made their first contribution in [#2442](https://github.com/prefix-dev/pixi/pull/2442) ### [0.36.0] - 2024-11-07 #### ✨ Highlights - You can now `pixi upgrade` your project dependencies. - We've done a performance improvement on the prefix validation check, thus faster `pixi run` startup times. #### Added - Add powerpc64le target to trampoline by @ruben-arts in [#2419](https://github.com/prefix-dev/pixi/pull/2419) - Add trampoline tests again by @Hofer-Julian in [#2420](https://github.com/prefix-dev/pixi/pull/2420) - Add `pixi upgrade` by @Hofer-Julian in [#2368](https://github.com/prefix-dev/pixi/pull/2368) - Add platform fallback win-64 for win-arm64 by @chawyehsu in [#2427](https://github.com/prefix-dev/pixi/pull/2427) - Add `--prepend` option for `pixi project channel add` by @mrswastik-robot in [#2447](https://github.com/prefix-dev/pixi/pull/2447) #### Documentation - Fix cli basic usage example by @lucascolley in [#2432](https://github.com/prefix-dev/pixi/pull/2432) - Update python tutorial by @LiamConnors in [#2452](https://github.com/prefix-dev/pixi/pull/2452) - Improve `pixi global` docs by @Hofer-Julian in [#2437](https://github.com/prefix-dev/pixi/pull/2437) #### Fixed - Use `--silent` instead of `--no-progress-meter` for old `curl` by @jaimergp in [#2428](https://github.com/prefix-dev/pixi/pull/2428) - Search should return latest package across all platforms by @nichmor in [#2424](https://github.com/prefix-dev/pixi/pull/2424) - Trampoline unwraps by @ruben-arts in [#2422](https://github.com/prefix-dev/pixi/pull/2422) - PyPI Index usage (regression in v0.35.0) by @tdejager in [#2465](https://github.com/prefix-dev/pixi/pull/2465) - PyPI git dependencies (regression in v0.35.0) by @wolfv in [#2438](https://github.com/prefix-dev/pixi/pull/2438) - Tolerate pixi file errors (regression in v0.35.0) by @jvenant in [#2457](https://github.com/prefix-dev/pixi/pull/2457) - Make sure tasks are fetched for best platform by @jjjermiah in [#2446](https://github.com/prefix-dev/pixi/pull/2446) #### Performance - Quick prefix validation check by @ruben-arts in [#2400](https://github.com/prefix-dev/pixi/pull/2400) #### New Contributors - @jvenant made their first contribution in [#2457](https://github.com/prefix-dev/pixi/pull/2457) - @mrswastik-robot made their first contribution in [#2447](https://github.com/prefix-dev/pixi/pull/2447) - @LiamConnors made their first contribution in [#2452](https://github.com/prefix-dev/pixi/pull/2452) ### [0.35.0] - 2024-11-05 #### ✨ Highlights `pixi global` now exposed binaries are not scripts anymore but actual executables. Resulting in significant speedup and better compatibility with other tools. #### Added - Add language packages with minor pinning by default by @ruben-arts in [#2310](https://github.com/prefix-dev/pixi/pull/2310) - Add grouping for exposing and removing by @nichmor in [#2387](https://github.com/prefix-dev/pixi/pull/2387) - Add trampoline for pixi global by @Hofer-Julian and @nichmor in [#2381](https://github.com/prefix-dev/pixi/pull/2381) - Adding SCM option for init command by @alvgaona in [#2342](https://github.com/prefix-dev/pixi/pull/2342) - Create `.pixi/.gitignore` containing `*` by @maresb in [#2361](https://github.com/prefix-dev/pixi/pull/2361) #### Changed - Use the same package cache folder by @nichmor in [#2335](https://github.com/prefix-dev/pixi/pull/2335)zx - Disable progress in non tty by @ruben-arts in [#2308](https://github.com/prefix-dev/pixi/pull/2308) - Improve global install reporting by @Hofer-Julian in [#2395](https://github.com/prefix-dev/pixi/pull/2395) - Suggest fix in platform error message by @maurosilber in [#2404](https://github.com/prefix-dev/pixi/pull/2404) - Upgrading uv to `0.4.30` by @tdejager in [#2372](https://github.com/prefix-dev/pixi/pull/2372) #### Documentation - Add pybind11 example by @alvgaona in [#2324](https://github.com/prefix-dev/pixi/pull/2324) - Replace build with uv in pybind11 example by @alvgaona in [#2341](https://github.com/prefix-dev/pixi/pull/2341) - Fix incorrect statement about env location by @opcode81 in [#2370](https://github.com/prefix-dev/pixi/pull/2370) #### Fixed - Global update reporting by @Hofer-Julian in [#2352](https://github.com/prefix-dev/pixi/pull/2352) - Correctly display unrequested environments on `task list` by @jjjermiah in [#2402](https://github.com/prefix-dev/pixi/pull/2402) #### Refactor - Use built in string methods by @KGrewal1 in [#2348](https://github.com/prefix-dev/pixi/pull/2348) - Reorganize integration tests by @Hofer-Julian in [#2408](https://github.com/prefix-dev/pixi/pull/2408) - Reimplement barrier cell on OnceLock by @KGrewal1 in [#2347](https://github.com/prefix-dev/pixi/pull/2347) #### New Contributors - @maurosilber made their first contribution in [#2404](https://github.com/prefix-dev/pixi/pull/2404) - @opcode81 made their first contribution in [#2370](https://github.com/prefix-dev/pixi/pull/2370) - @alvgaona made their first contribution in [#2342](https://github.com/prefix-dev/pixi/pull/2342) ### [0.34.0] - 2024-10-21 #### ✨ Highlights - `pixi global install` now takes a flag `--with`, inspired by `uv tool install`. If you only want to add dependencies without exposing them, you can now run `pixi global install ipython --with numpy --with matplotlib` - Improved the output of `pixi global` subcommands - Many bug fixes #### Added - Add timeouts by @Hofer-Julian in [#2311](https://github.com/prefix-dev/pixi/pull/2311) #### Changed - Global update should add new executables by @nichmor in [#2298](https://github.com/prefix-dev/pixi/pull/2298) - Add `pixi global install --with` by @Hofer-Julian in [#2332](https://github.com/prefix-dev/pixi/pull/2332) #### Documentation - Document where `pixi-global.toml` can be found by @Hofer-Julian in [#2304](https://github.com/prefix-dev/pixi/pull/2304) - Add ros noetic example by @ruben-arts in [#2271](https://github.com/prefix-dev/pixi/pull/2271) - Add nichita and julian to CITATION.cff by @Hofer-Julian in [#2327](https://github.com/prefix-dev/pixi/pull/2327) - Improve keyring documentation to use pixi global by @olivier-lacroix in [#2318](https://github.com/prefix-dev/pixi/pull/2318) #### Fixed - `pixi global upgrade-all` error message by @Hofer-Julian in [#2296](https://github.com/prefix-dev/pixi/pull/2296) - Select correct run environment by @ruben-arts in [#2301](https://github.com/prefix-dev/pixi/pull/2301) - Adapt channels to work with newest rattler-build version by @Hofer-Julian in [#2306](https://github.com/prefix-dev/pixi/pull/2306) - Hide obsolete commands in help page of `pixi global` by @chawyehsu in [#2320](https://github.com/prefix-dev/pixi/pull/2320) - Typecheck all tests by @Hofer-Julian in [#2328](https://github.com/prefix-dev/pixi/pull/2328) #### Refactor - Improve upload errors by @ruben-arts in [#2303](https://github.com/prefix-dev/pixi/pull/2303) #### New Contributors - @gerlero made their first contribution in [#2300](https://github.com/prefix-dev/pixi/pull/2300) ### [0.33.0] - 2024-10-16 #### ✨ Highlights This is the first release with the new `pixi global` implementation. It's a full reimplementation of `pixi global` where it now uses a manifest file just like `pixi` projects. This way you can declare your environments and save them to a VCS. It also brings features like, adding dependencies to a global environment, and exposing multiple binaries from the same environment that are not part of the main installed packages. Test it out with: ```shell # Normal feature pixi global install ipython # New features pixi global install \ --environment science \ # Defined the environment name --expose scipython=ipython \ # Expose binaries under custom names ipython scipy # Define multiple dependencies for one environment ``` This should result in a manifest in `$HOME/.pixi/manifests/pixi-global.toml`: ```toml version = 1 [envs.ipython] channels = ["conda-forge"] dependencies = { ipython = "*" } exposed = { ipython = "ipython", ipython3 = "ipython3" } [envs.science] channels = ["conda-forge"] dependencies = { ipython = "*", scipy = "*" } exposed = { scipython = "ipython" } ``` #### πŸ“– Documentation Checkout the updated documentation on this new feature: - Main documentation on this tag: https://pixi.sh/v0.33.0/ - Global CLI documentation: https://pixi.sh/v0.33.0/reference/cli/#global - The implementation documentation: https://pixi.sh/v0.33.0/features/global_tools/ - The initial design proposal: https://pixi.sh/v0.33.0/design_proposals/pixi_global_manifest/ ### [0.32.2] - 2024-10-16 #### ✨ Highlights - `pixi self-update` will only work on the binaries from the GitHub releases, avoiding accidentally breaking the installation. - We now support `gcs://` conda registries. - No more broken PowerShell after using `pixi shell`. #### Changed - Add support for `gcs://` conda registries by @clement-chaneching in [#2263](https://github.com/prefix-dev/pixi/pull/2263) #### Documentation - Small fixes in tutorials/python.md by @carschandler in [#2252](https://github.com/prefix-dev/pixi/pull/2252) - Update `pixi list` docs by @Hofer-Julian in [#2269](https://github.com/prefix-dev/pixi/pull/2269) #### Fixed - Bind ctrl c listener so that it doesn't interfere on powershell by @wolfv in [#2260](https://github.com/prefix-dev/pixi/pull/2260) - Explicitly run default environment by @ruben-arts in [#2273](https://github.com/prefix-dev/pixi/pull/2273) - Parse env name on adding by @ruben-arts in [#2279](https://github.com/prefix-dev/pixi/pull/2279) #### Refactor - Make self-update a compile time feature by @freundTech in [#2213](https://github.com/prefix-dev/pixi/pull/2213) #### New Contributors - @clement-chaneching made their first contribution in [#2263](https://github.com/prefix-dev/pixi/pull/2263) - @freundTech made their first contribution in [#2213](https://github.com/prefix-dev/pixi/pull/2213) ### [0.32.1] - 2024-10-08 #### Fixes - Bump Rust version to `1.81` by @wolfv in [#2227](https://github.com/prefix-dev/pixi/pull/2227) #### Documentation - Pixi-pack, docker, devcontainer by @pavelzw in [#2220](https://github.com/prefix-dev/pixi/pull/2220) ### [0.32.0] - 2024-10-08 #### ✨ Highlights The biggest fix in this PR is the move to the latest rattler as it came with some major bug fixes for macOS and Rust 1.81 compatibility. #### Changed - Correctly implement total ordering for dependency provider by @tdejager in [rattler/#892](https://github.com/conda/rattler/pull/892) #### Fixed - Fixed self-clobber issue when up/down grading packages by @wolfv in [rattler/#893](https://github.com/conda/rattler/pull/893) - Check environment name before returning not found print by @ruben-arts in [#2198](https://github.com/prefix-dev/pixi/pull/2198) - Turn off symlink follow for task cache by @ruben-arts in [#2209](https://github.com/prefix-dev/pixi/pull/2209) ### [0.31.0] - 2024-10-03 #### ✨ Highlights Thanks to our maintainer @baszamstra! He sped up the resolver for all cases we could think of in [#2162](https://github.com/prefix-dev/pixi/pull/2162) Check the result of times it takes to solve the environments in our test set: #### Added - Add `nodefaults` to imported conda envs by @ruben-arts in [#2097](https://github.com/prefix-dev/pixi/pull/2097) - Add newline to `.gitignore` by @ruben-arts in [#2095](https://github.com/prefix-dev/pixi/pull/2095) - Add `--no-activation` option to prevent env activation during global install/upgrade by @183amir in [#1980](https://github.com/prefix-dev/pixi/pull/1980) - Add `--priority` arg to `project channel add` by @minrk in [#2086](https://github.com/prefix-dev/pixi/pull/2086) #### Changed - Use pixi spec for conda environment yml by @ruben-arts in [#2096](https://github.com/prefix-dev/pixi/pull/2096) - Update rattler by @nichmor in [#2120](https://github.com/prefix-dev/pixi/pull/2120) - Update README.md by @ruben-arts in [#2129](https://github.com/prefix-dev/pixi/pull/2129) - Follow symlinks while walking files by @0xbe7a in [#2141](https://github.com/prefix-dev/pixi/pull/2141) #### Documentation - Adapt wording in pixi global proposal by @Hofer-Julian in [#2098](https://github.com/prefix-dev/pixi/pull/2098) - Community: add array-api-extra by @lucascolley in [#2107](https://github.com/prefix-dev/pixi/pull/2107) - `pixi global` mention `no-activation` by @Hofer-Julian in [#2109](https://github.com/prefix-dev/pixi/pull/2109) - Add minimal constructor example by @bollwyvl in [#2102](https://github.com/prefix-dev/pixi/pull/2102) - Update global manifest `install` by @Hofer-Julian in [#2128](https://github.com/prefix-dev/pixi/pull/2128) - Add description for `pixi update --json` by @scottamain in [#2160](https://github.com/prefix-dev/pixi/pull/2160) - Fixes backticks for doc strings by @rachfop in [#2174](https://github.com/prefix-dev/pixi/pull/2174) #### Fixed - Sort exported conda explicit spec topologically by @synapticarbors in [#2101](https://github.com/prefix-dev/pixi/pull/2101) - `--import env_file` breaks channel priority by @fecet in [#2113](https://github.com/prefix-dev/pixi/pull/2113) - Allow exact yanked pypi packages by @nichmor in [#2116](https://github.com/prefix-dev/pixi/pull/2116) - Check if files are same in `self-update` by @apoorvkh in [#2132](https://github.com/prefix-dev/pixi/pull/2132) - `get_or_insert_nested_table` by @Hofer-Julian in [#2167](https://github.com/prefix-dev/pixi/pull/2167) - Improve `install.sh` PATH handling and general robustness by @Arcitec in [#2189](https://github.com/prefix-dev/pixi/pull/2189) - Output tasks on `pixi run` without input by @ruben-arts in [#2193](https://github.com/prefix-dev/pixi/pull/2193) #### Performance - Significantly speed up conda resolution by @baszalmstra in [#2162](https://github.com/prefix-dev/pixi/pull/2162) #### New Contributors - @Arcitec made their first contribution in [#2189](https://github.com/prefix-dev/pixi/pull/2189) - @rachfop made their first contribution in [#2174](https://github.com/prefix-dev/pixi/pull/2174) - @scottamain made their first contribution in [#2160](https://github.com/prefix-dev/pixi/pull/2160) - @apoorvkh made their first contribution in [#2132](https://github.com/prefix-dev/pixi/pull/2132) - @0xbe7a made their first contribution in [#2141](https://github.com/prefix-dev/pixi/pull/2141) - @fecet made their first contribution in [#2113](https://github.com/prefix-dev/pixi/pull/2113) - @minrk made their first contribution in [#2086](https://github.com/prefix-dev/pixi/pull/2086) - @183amir made their first contribution in [#1980](https://github.com/prefix-dev/pixi/pull/1980) - @lucascolley made their first contribution in [#2107](https://github.com/prefix-dev/pixi/pull/2107) ### [0.30.0] - 2024-09-19 #### ✨ Highlights I want to thank @synapticarbors and @abkfenris for starting the work on `pixi project export`. Pixi now supports the export of a conda `environment.yml` file and a conda explicit specification file. This is a great addition to the project and will help users to share their projects with other non pixi users. #### Added - Export conda explicit specification file from project by @synapticarbors in [#1873](https://github.com/prefix-dev/pixi/pull/1873) - Add flag to `pixi search` by @Hofer-Julian in [#2018](https://github.com/prefix-dev/pixi/pull/2018) - Adds the ability to set the index strategy by @tdejager in [#1986](https://github.com/prefix-dev/pixi/pull/1986) - Export conda `environment.yml` by @abkfenris in [#2003](https://github.com/prefix-dev/pixi/pull/2003) #### Changed - Improve examples/docker by @jennydaman in [#1965](https://github.com/prefix-dev/pixi/pull/1965) - Minimal pre-commit tasks by @Hofer-Julian in [#1984](https://github.com/prefix-dev/pixi/pull/1984) - Improve error and feedback when target does not exist by @tdejager in [#1961](https://github.com/prefix-dev/pixi/pull/1961) - Move the rectangle using a mouse in SDL by @certik in [#2069](https://github.com/prefix-dev/pixi/pull/2069) #### Documentation - Update cli.md by @xela-95 in [#2047](https://github.com/prefix-dev/pixi/pull/2047) - Update `system-requirements` information by @ruben-arts in [#2079](https://github.com/prefix-dev/pixi/pull/2079) - Append to file syntax in task docs by @nicornk in [#2013](https://github.com/prefix-dev/pixi/pull/2013) - Change documentation of pixi upload to refer to correct API endpoint by @traversaro in [#2074](https://github.com/prefix-dev/pixi/pull/2074) #### Testing - Add downstream nerfstudio test by @tdejager in [#1996](https://github.com/prefix-dev/pixi/pull/1996) - Run pytests in parallel by @tdejager in [#2027](https://github.com/prefix-dev/pixi/pull/2027) - Testing common wheels by @tdejager in [#2031](https://github.com/prefix-dev/pixi/pull/2031) #### Fixed - Lock file is always outdated for pypi path dependencies by @nichmor in [#2039](https://github.com/prefix-dev/pixi/pull/2039) - Fix error message for export conda explicit spec by @synapticarbors in [#2048](https://github.com/prefix-dev/pixi/pull/2048) - Use `conda-pypi-map` for feature channels by @nichmor in [#2038](https://github.com/prefix-dev/pixi/pull/2038) - Constrain feature platforms in schema by @bollwyvl in [#2055](https://github.com/prefix-dev/pixi/pull/2055) - Split tag creation functions by @tdejager in [#2062](https://github.com/prefix-dev/pixi/pull/2062) - Tree print to pipe by @ruben-arts in [#2064](https://github.com/prefix-dev/pixi/pull/2064) - `subdirectory` in pypi url by @ruben-arts in [#2065](https://github.com/prefix-dev/pixi/pull/2065) - Create a GUI application on Windows, not Console by @certik in [#2067](https://github.com/prefix-dev/pixi/pull/2067) - Make dashes underscores in python package names by @ruben-arts in [#2073](https://github.com/prefix-dev/pixi/pull/2073) - Give better errors on broken `pyproject.toml` by @ruben-arts in [#2075](https://github.com/prefix-dev/pixi/pull/2075) #### Refactor - Stop duplicating `strip_channel_alias` from rattler by @Hofer-Julian in [#2017](https://github.com/prefix-dev/pixi/pull/2017) - Follow-up wheels tests by @Hofer-Julian in [#2063](https://github.com/prefix-dev/pixi/pull/2063) - Integration test suite by @Hofer-Julian in [#2081](https://github.com/prefix-dev/pixi/pull/2081) - Remove `psutils` by @Hofer-Julian in [#2083](https://github.com/prefix-dev/pixi/pull/2083) - Add back older caching method by @tdejager in [#2046](https://github.com/prefix-dev/pixi/pull/2046) - Release script by @Hofer-Julian in [#1978](https://github.com/prefix-dev/pixi/pull/1978) - Activation script by @Hofer-Julian in [#2014](https://github.com/prefix-dev/pixi/pull/2014) - Pins python version in add_pypi_functionality by @tdejager in [#2040](https://github.com/prefix-dev/pixi/pull/2040) - Improve the lock_file_usage flags and behavior. by @ruben-arts in [#2078](https://github.com/prefix-dev/pixi/pull/2078) - Move matrix to workflow that it is used in by @tdejager in [#1987](https://github.com/prefix-dev/pixi/pull/1987) - Refactor manifest into more generic approach by @nichmor in [#2015](https://github.com/prefix-dev/pixi/pull/2015) #### New Contributors - @certik made their first contribution in [#2069](https://github.com/prefix-dev/pixi/pull/2069) - @xela-95 made their first contribution in [#2047](https://github.com/prefix-dev/pixi/pull/2047) - @nicornk made their first contribution in [#2013](https://github.com/prefix-dev/pixi/pull/2013) - @jennydaman made their first contribution in [#1965](https://github.com/prefix-dev/pixi/pull/1965) ### [0.29.0] - 2024-09-04 #### ✨ Highlights - Add build-isolation options, for more details check out our [docs](https://pixi.sh/v0.29.0/reference/project_configuration/#no-build-isolation) - Allow to use virtual package overrides from environment variables ([PR](https://github.com/conda/rattler/pull/818)) - Many bug fixes #### Added - Add build-isolation options by @tdejager in [#1909](https://github.com/prefix-dev/pixi/pull/1909) - Add release script by @Hofer-Julian in [#1971](https://github.com/prefix-dev/pixi/pull/1971) #### Changed - Use rustls-tls instead of native-tls per default by @Hofer-Julian in [#1929](https://github.com/prefix-dev/pixi/pull/1929) - Upgrade to uv 0.3.4 by @tdejager in [#1936](https://github.com/prefix-dev/pixi/pull/1936) - Upgrade to uv 0.4.0 by @tdejager in [#1944](https://github.com/prefix-dev/pixi/pull/1944) - Better error for when the target or platform are missing by @tdejager in [#1959](https://github.com/prefix-dev/pixi/pull/1959) - Improve integration tests by @Hofer-Julian in [#1958](https://github.com/prefix-dev/pixi/pull/1958) - Improve release script by @Hofer-Julian in [#1974](https://github.com/prefix-dev/pixi/pull/1974) #### Fixed - Update env variables in installation docs by @lev112 in [#1937](https://github.com/prefix-dev/pixi/pull/1937) - Always overwrite when pixi adding the dependency by @ruben-arts in [#1935](https://github.com/prefix-dev/pixi/pull/1935) - Typo in schema.json by @SobhanMP in [#1948](https://github.com/prefix-dev/pixi/pull/1948) - Using file url as mapping by @nichmor in [#1930](https://github.com/prefix-dev/pixi/pull/1930) - Offline mapping should not request by @nichmor in [#1968](https://github.com/prefix-dev/pixi/pull/1968) - `pixi init` for `pyproject.toml` by @Hofer-Julian in [#1947](https://github.com/prefix-dev/pixi/pull/1947) - Use two in memory indexes, for resolve and builds by @tdejager in [#1969](https://github.com/prefix-dev/pixi/pull/1969) - Minor issues and todos by @KGrewal1 in [#1963](https://github.com/prefix-dev/pixi/pull/1963) #### Refactor - Improve integration tests by @Hofer-Julian in [#1942](https://github.com/prefix-dev/pixi/pull/1942) #### New Contributors - @SobhanMP made their first contribution in [#1948](https://github.com/prefix-dev/pixi/pull/1948) - @lev112 made their first contribution in [#1937](https://github.com/prefix-dev/pixi/pull/1937) ### [0.28.2] - 2024-08-28 #### Changed - Use mold on linux by @Hofer-Julian in [#1914](https://github.com/prefix-dev/pixi/pull/1914) #### Documentation - Fix global manifest by @Hofer-Julian in [#1912](https://github.com/prefix-dev/pixi/pull/1912) - Document azure keyring usage by @tdejager in [#1913](https://github.com/prefix-dev/pixi/pull/1913) #### Fixed - Let `init` add dependencies independent of target and don't install by @ruben-arts in [#1916](https://github.com/prefix-dev/pixi/pull/1916) - Enable use of manylinux wheeltags once again by @tdejager in [#1925](https://github.com/prefix-dev/pixi/pull/1925) - The bigger runner by @ruben-arts in [#1902](https://github.com/prefix-dev/pixi/pull/1902) ### [0.28.1] - 2024-08-26 #### Changed - Uv upgrade to 0.3.2 by @tdejager in [#1900](https://github.com/prefix-dev/pixi/pull/1900) #### Documentation - Add `keyrings.artifacts` to the list of project built with `pixi` by @jslorrma in [#1908](https://github.com/prefix-dev/pixi/pull/1908) #### Fixed - Use default indexes if non where given by the lockfile by @ruben-arts in [#1910](https://github.com/prefix-dev/pixi/pull/1910) #### New Contributors - @jslorrma made their first contribution in [#1908](https://github.com/prefix-dev/pixi/pull/1908) ### [0.28.0] - 2024-08-22 #### ✨ Highlights - **Bug Fixes**: Major fixes in general but especially for PyPI installation issues and better error messaging. - **Compatibility**: Default Linux version downgraded to 4.18 for broader support. - **New Features**: Added INIT_CWD in pixi run, improved logging, and more cache options. #### Added - Add `INIT_CWD` to activated env `pixi run` by @ruben-arts in [#1798](https://github.com/prefix-dev/pixi/pull/1798) - Add context to error when parsing conda-meta files by @baszalmstra in [#1854](https://github.com/prefix-dev/pixi/pull/1854) - Add some logging for when packages are actually overridden by conda by @tdejager in [#1874](https://github.com/prefix-dev/pixi/pull/1874) - Add package when extra is added by @ruben-arts in [#1856](https://github.com/prefix-dev/pixi/pull/1856) #### Changed - Use new gateway to get the repodata for global install by @nichmor in [#1767](https://github.com/prefix-dev/pixi/pull/1767) - Pixi global proposal by @Hofer-Julian in [#1757](https://github.com/prefix-dev/pixi/pull/1757) - Upgrade to new uv 0.2.37 by @tdejager in [#1829](https://github.com/prefix-dev/pixi/pull/1829) - Use new gateway for pixi search by @nichmor in [#1819](https://github.com/prefix-dev/pixi/pull/1819) - Extend pixi clean cache with more cache options by @ruben-arts in [#1872](https://github.com/prefix-dev/pixi/pull/1872) - Downgrade `__linux` default to `4.18` by @ruben-arts in [#1887](https://github.com/prefix-dev/pixi/pull/1887) #### Documentation - Fix instructions for update github actions by @Hofer-Julian in [#1774](https://github.com/prefix-dev/pixi/pull/1774) - Fix fish completion script by @dennis-wey in [#1789](https://github.com/prefix-dev/pixi/pull/1789) - Expands the environment variable examples in the reference section by @travishathaway in [#1779](https://github.com/prefix-dev/pixi/pull/1779) - Community feedback `pixi global` by @Hofer-Julian in [#1800](https://github.com/prefix-dev/pixi/pull/1800) - Additions to the pixi global proposal by @Hofer-Julian in [#1803](https://github.com/prefix-dev/pixi/pull/1803) - Stop using invalid environment name in pixi global proposal by @Hofer-Julian in [#1826](https://github.com/prefix-dev/pixi/pull/1826) - Extend `pixi global` proposal by @Hofer-Julian in [#1861](https://github.com/prefix-dev/pixi/pull/1861) - Make `channels` required in `pixi global` manifest by @Hofer-Julian in [#1868](https://github.com/prefix-dev/pixi/pull/1868) - Fix linux minimum version in project_configuration docs by @traversaro in [#1888](https://github.com/prefix-dev/pixi/pull/1888) #### Fixed - Try to increase `rlimit` by @baszalmstra in [#1766](https://github.com/prefix-dev/pixi/pull/1766) - Add test for invalid environment names by @Hofer-Julian in [#1825](https://github.com/prefix-dev/pixi/pull/1825) - Show global config in info command by @ruben-arts in [#1807](https://github.com/prefix-dev/pixi/pull/1807) - Correct documentation of PIXI_ENVIRONMENT_PLATFORMS by @traversaro in [#1842](https://github.com/prefix-dev/pixi/pull/1842) - Format in docs/features/environment.md by @cdeil in [#1846](https://github.com/prefix-dev/pixi/pull/1846) - Make proper use of `NamedChannelOrUrl` by @ruben-arts in [#1820](https://github.com/prefix-dev/pixi/pull/1820) - Trait impl override by @baszalmstra in [#1848](https://github.com/prefix-dev/pixi/pull/1848) - Tame `pixi search` by @baszalmstra in [#1849](https://github.com/prefix-dev/pixi/pull/1849) - Fix `pixi tree -i` duplicate output by @baszalmstra in [#1847](https://github.com/prefix-dev/pixi/pull/1847) - Improve spec parsing error messages by @baszalmstra in [#1786](https://github.com/prefix-dev/pixi/pull/1786) - Parse matchspec from CLI Lenient by @baszalmstra in [#1852](https://github.com/prefix-dev/pixi/pull/1852) - Improve parsing of pypi-dependencies by @baszalmstra in [#1851](https://github.com/prefix-dev/pixi/pull/1851) - Don't enforce system requirements for task tests by @baszalmstra in [#1855](https://github.com/prefix-dev/pixi/pull/1855) - Satisfy when there are no pypi packages in the lockfile by @ruben-arts in [#1862](https://github.com/prefix-dev/pixi/pull/1862) - Ssh url should not contain colon by @baszalmstra in [#1865](https://github.com/prefix-dev/pixi/pull/1865) - `find-links` with manifest-path by @baszalmstra in [#1864](https://github.com/prefix-dev/pixi/pull/1864) - Increase stack size in debug mode on windows by @baszalmstra in [#1867](https://github.com/prefix-dev/pixi/pull/1867) - Solve-group-envs should reside in `.pixi` folder by @baszalmstra in [#1866](https://github.com/prefix-dev/pixi/pull/1866) - Move package-override logging by @tdejager in [#1883](https://github.com/prefix-dev/pixi/pull/1883) - Pinning logic for minor and major by @baszalmstra in [#1885](https://github.com/prefix-dev/pixi/pull/1885) - Docs manifest tests by @ruben-arts in [#1879](https://github.com/prefix-dev/pixi/pull/1879) #### Refactor - Encapsulate channel resolution logic for CLI by @olivier-lacroix in [#1781](https://github.com/prefix-dev/pixi/pull/1781) - Move to `pub(crate) fn` in order to detect and remove unused functions by @Hofer-Julian in [#1805](https://github.com/prefix-dev/pixi/pull/1805) - Only compile `TaskNode::full_command` for tests by @Hofer-Julian in [#1809](https://github.com/prefix-dev/pixi/pull/1809) - Derive `Default` for more structs by @Hofer-Julian in [#1824](https://github.com/prefix-dev/pixi/pull/1824) - Rename `get_up_to_date_prefix` to `update_prefix` by @Hofer-Julian in [#1837](https://github.com/prefix-dev/pixi/pull/1837) - Make `HasSpecs` implementation more functional by @Hofer-Julian in [#1863](https://github.com/prefix-dev/pixi/pull/1863) #### New Contributors - @cdeil made their first contribution in [#1846](https://github.com/prefix-dev/pixi/pull/1846) ### [0.27.1] - 2024-08-09 #### Documentation - Fix mlx feature in "multiple machines" example by @rgommers in [#1762](https://github.com/prefix-dev/pixi/pull/1762) - Update some of the cli and add osx rosetta mention by @ruben-arts in [#1760](https://github.com/prefix-dev/pixi/pull/1760) - Fix typo by @pavelzw in [#1771](https://github.com/prefix-dev/pixi/pull/1771) #### Fixed - User agent string was wrong by @wolfv in [#1759](https://github.com/prefix-dev/pixi/pull/1759) - Dont accidentally wipe pyproject.toml on `init` by @ruben-arts in [#1775](https://github.com/prefix-dev/pixi/pull/1775) #### Refactor - Add `pixi_spec` crate by @baszalmstra in [#1741](https://github.com/prefix-dev/pixi/pull/1741) #### New Contributors - @rgommers made their first contribution in [#1762](https://github.com/prefix-dev/pixi/pull/1762) ### [0.27.0] - 2024-08-07 #### ✨ Highlights This release contains a lot of refactoring and improvements to the codebase, in preparation for future features and improvements. Including with that we've fixed a ton of bugs. To make sure we're not breaking anything we've added a lot of tests and CI checks. But let us know if you find any issues! As a reminder, you can update pixi using `pixi self-update` and move to a specific version, including backwards, with `pixi self-update --version 0.27.0`. #### Added - Add `pixi run` completion for `fish` shell by @dennis-wey in [#1680](https://github.com/prefix-dev/pixi/pull/1680) #### Changed - Move examples from setuptools to hatchling by @Hofer-Julian in [#1692](https://github.com/prefix-dev/pixi/pull/1692) - Let `pixi init` create hatchling pyproject.toml by @Hofer-Julian in [#1693](https://github.com/prefix-dev/pixi/pull/1693) - Make `[project]` table optional for `pyproject.toml` manifests by @olivier-lacroix in [#1732](https://github.com/prefix-dev/pixi/pull/1732) #### Documentation - Improve the `fish` completions location by @tdejager in [#1647](https://github.com/prefix-dev/pixi/pull/1647) - Explain why we use `hatchling` by @Hofer-Julian - Update install CLI doc now that the `update` command exist by @olivier-lacroix in [#1690](https://github.com/prefix-dev/pixi/pull/1690) - Mention `pixi exec` in GHA docs by @pavelzw in [#1724](https://github.com/prefix-dev/pixi/pull/1724) - Update to correct spelling by @ahnsn in [#1730](https://github.com/prefix-dev/pixi/pull/1730) - Ensure `hatchling` is used everywhere in documentation by @olivier-lacroix in [#1733](https://github.com/prefix-dev/pixi/pull/1733) - Add readme to WASM example by @wolfv in [#1703](https://github.com/prefix-dev/pixi/pull/1703) - Fix typo by @pavelzw in [#1660](https://github.com/prefix-dev/pixi/pull/1660) - Fix typo by @DimitriPapadopoulos in [#1743](https://github.com/prefix-dev/pixi/pull/1743) - Fix typo by @SeaOtocinclus in [#1651](https://github.com/prefix-dev/pixi/pull/1651) #### Testing - Added script and tasks for testing examples by @tdejager in [#1671](https://github.com/prefix-dev/pixi/pull/1671) - Add simple integration tests by @ruben-arts in [#1719](https://github.com/prefix-dev/pixi/pull/1719) #### Fixed - Prepend pixi to path instead of appending by @vigneshmanick in [#1644](https://github.com/prefix-dev/pixi/pull/1644) - Add manifest tests and run them in ci by @ruben-arts in [#1667](https://github.com/prefix-dev/pixi/pull/1667) - Use hashed pypi mapping by @baszalmstra in [#1663](https://github.com/prefix-dev/pixi/pull/1663) - Depend on `pep440_rs` from crates.io and use replace by @baszalmstra in [#1698](https://github.com/prefix-dev/pixi/pull/1698) - `pixi add` with more than just package name and version by @ruben-arts in [#1704](https://github.com/prefix-dev/pixi/pull/1704) - Ignore pypi logic on non pypi projects by @ruben-arts in [#1705](https://github.com/prefix-dev/pixi/pull/1705) - Fix and refactor `--no-lockfile-update` by @ruben-arts in [#1683](https://github.com/prefix-dev/pixi/pull/1683) - Changed example to use hatchling by @tdejager in [#1729](https://github.com/prefix-dev/pixi/pull/1729) - Todo clean up by @KGrewal1 in [#1735](https://github.com/prefix-dev/pixi/pull/1735) - Allow for init to `pixi.toml` when `pyproject.toml` is available. by @ruben-arts in [#1640](https://github.com/prefix-dev/pixi/pull/1640) - Test on `macos-13` by @ruben-arts in [#1739](https://github.com/prefix-dev/pixi/pull/1739) - Make sure pixi vars are available before `activation.env` vars are by @ruben-arts in [#1740](https://github.com/prefix-dev/pixi/pull/1740) - Authenticate exec package download by @olivier-lacroix in [#1751](https://github.com/prefix-dev/pixi/pull/1751) #### Refactor - Extract `pixi_manifest` by @baszalmstra in [#1656](https://github.com/prefix-dev/pixi/pull/1656) - Delay channel config url evaluation by @baszalmstra in [#1662](https://github.com/prefix-dev/pixi/pull/1662) - Split out pty functionality by @tdejager in [#1678](https://github.com/prefix-dev/pixi/pull/1678) - Make project manifest loading DRY and consistent by @olivier-lacroix in [#1688](https://github.com/prefix-dev/pixi/pull/1688) - Refactor channel add and remove CLI commands by @olivier-lacroix in [#1689](https://github.com/prefix-dev/pixi/pull/1689) - Refactor `pixi::consts` and `pixi::config` into separate crates by @tdejager in [#1684](https://github.com/prefix-dev/pixi/pull/1684) - Move dependencies to `pixi_manifest` by @tdejager in [#1700](https://github.com/prefix-dev/pixi/pull/1700) - Moved pypi environment modifiers by @tdejager in [#1699](https://github.com/prefix-dev/pixi/pull/1699) - Split `HasFeatures` by @tdejager in [#1712](https://github.com/prefix-dev/pixi/pull/1712) - Move, splits and renames the `HasFeatures` trait by @tdejager in [#1717](https://github.com/prefix-dev/pixi/pull/1717) - Merge `utils` by @tdejager in [#1718](https://github.com/prefix-dev/pixi/pull/1718) - Move `fancy` to its own crate by @tdejager in [#1722](https://github.com/prefix-dev/pixi/pull/1722) - Move `config` to repodata functions by @tdejager in [#1723](https://github.com/prefix-dev/pixi/pull/1723) - Move `pypi-mapping` to its own crate by @tdejager in [#1725](https://github.com/prefix-dev/pixi/pull/1725) - Split `utils` into 2 crates by @tdejager in [#1736](https://github.com/prefix-dev/pixi/pull/1736) - Add progress bar as a crate by @nichmor in [#1727](https://github.com/prefix-dev/pixi/pull/1727) - Split up `pixi_manifest` lib by @tdejager in [#1661](https://github.com/prefix-dev/pixi/pull/1661) #### New Contributors - @DimitriPapadopoulos made their first contribution in [#1743](https://github.com/prefix-dev/pixi/pull/1743) - @KGrewal1 made their first contribution in [#1735](https://github.com/prefix-dev/pixi/pull/1735) - @ahnsn made their first contribution in [#1730](https://github.com/prefix-dev/pixi/pull/1730) - @dennis-wey made their first contribution in [#1680](https://github.com/prefix-dev/pixi/pull/1680) ### [0.26.1] - 2024-07-22 #### Fixed - Make sure we also build the msi installer by @ruben-arts in [#1645](https://github.com/prefix-dev/pixi/pull/1645) ### [0.26.0] - 2024-07-19 #### ✨ Highlights - Specify how pixi **pins your dependencies** with the `pinning-strategy` in the config. e.g. `semver` -> `>=1.2.3,<2` and `no-pin` -> `*`) [#1516](https://github.com/prefix-dev/pixi/pull/1516) - Specify how pixi **solves multiple channels** with `channel-priority` in the manifest. [#1631](https://github.com/prefix-dev/pixi/pull/1631) #### Added - Add short options to config location flags by @ruben-arts in [#1586](https://github.com/prefix-dev/pixi/pull/1586) - Add a file guard to indicate if an environment is being installed by @baszalmstra in [#1593](https://github.com/prefix-dev/pixi/pull/1593) - Add `pinning-strategy` to the configuration by @ruben-arts in [#1516](https://github.com/prefix-dev/pixi/pull/1516) - Add `channel-priority` to the manifest and solve by @ruben-arts in [#1631](https://github.com/prefix-dev/pixi/pull/1631) - Add `nushell` completion by @Hofer-Julian in [#1599](https://github.com/prefix-dev/pixi/pull/1599) - Add `nushell` completions for `pixi run` by @Hofer-Julian in [#1627](https://github.com/prefix-dev/pixi/pull/1627) - Add completion for `pixi run --environment` for nushell by @Hofer-Julian in [#1636](https://github.com/prefix-dev/pixi/pull/1636) #### Changed - Upgrade uv 0.2.18 by @tdejager in [#1540](https://github.com/prefix-dev/pixi/pull/1540) - Refactor `pyproject.toml` parser by @nichmor in [#1592](https://github.com/prefix-dev/pixi/pull/1592) - Interactive warning for packages in `pixi global install` by @ruben-arts in [#1626](https://github.com/prefix-dev/pixi/pull/1626) #### Documentation - Add WASM example with JupyterLite by @wolfv in [#1623](https://github.com/prefix-dev/pixi/pull/1623) - Added LLM example by @ytjhai in [#1545](https://github.com/prefix-dev/pixi/pull/1545) - Add note to mark directory as excluded in pixi-pycharm by @pavelzw in [#1579](https://github.com/prefix-dev/pixi/pull/1579) - Add changelog to docs by @vigneshmanick in [#1574](https://github.com/prefix-dev/pixi/pull/1574) - Updated the values of the system requirements by @tdejager in [#1575](https://github.com/prefix-dev/pixi/pull/1575) - Tell cargo install which bin to install by @ruben-arts in [#1584](https://github.com/prefix-dev/pixi/pull/1584) - Update conflict docs for `cargo add` by @Hofer-Julian in [#1600](https://github.com/prefix-dev/pixi/pull/1600) - Revert "Update conflict docs for `cargo add` " by @Hofer-Julian in [#1605](https://github.com/prefix-dev/pixi/pull/1605) - Add reference documentation for the exec command by @baszalmstra in [#1587](https://github.com/prefix-dev/pixi/pull/1587) - Add transitioning docs for `poetry` and `conda` by @ruben-arts in [#1624](https://github.com/prefix-dev/pixi/pull/1624) - Add pixi-pack by @pavelzw in [#1629](https://github.com/prefix-dev/pixi/pull/1629) - Use '-' instead of '\_' for package name by @olivier-lacroix in [#1628](https://github.com/prefix-dev/pixi/pull/1628) #### Fixed - Flaky task test by @tdejager in [#1581](https://github.com/prefix-dev/pixi/pull/1581) - Pass command line arguments verbatim by @baszalmstra in [#1582](https://github.com/prefix-dev/pixi/pull/1582) - Run clippy on all targets by @Hofer-Julian in [#1588](https://github.com/prefix-dev/pixi/pull/1588) - Pre-commit install pixi task by @Hofer-Julian in [#1590](https://github.com/prefix-dev/pixi/pull/1590) - Add `clap_complete_nushell` to dependencies by @Hofer-Julian in [#1625](https://github.com/prefix-dev/pixi/pull/1625) - Write to `stdout` for machine readable output by @Hofer-Julian in [#1639](https://github.com/prefix-dev/pixi/pull/1639) #### Refactor - Migrate to workspace by @baszalmstra in [#1597](https://github.com/prefix-dev/pixi/pull/1597) #### Removed - Remove double manifest warning by @tdejager in [#1580](https://github.com/prefix-dev/pixi/pull/1580) #### New Contributors - @ytjhai made their first contribution in [#1545](https://github.com/prefix-dev/pixi/pull/1545) ### [0.25.0] - 2024-07-05 #### ✨ Highlights - `pixi exec` command, execute commands in temporary environments, useful for testing in short-lived sessions. - We've bumped the default system-requirements to higher defaults: glibc (2.17 -> 2.28), osx64 (10.15 -> 13.0), osx-arm64 (11.0 -> 13.0). Let us know if this causes any issues. To keep the previous values please use a `system-requirements` table, this is explained [here](https://pixi.sh/latest/reference/project_configuration/#the-system-requirements-table) #### Changed - Bump system requirements by @wolfv in [#1553](https://github.com/prefix-dev/pixi/pull/1553) - Better error when exec is missing a cmd by @tdejager in [#1565](https://github.com/prefix-dev/pixi/pull/1565) - Make exec use authenticated client by @tdejager in [#1568](https://github.com/prefix-dev/pixi/pull/1568) #### Documentation - Automatic updating using github actions by @pavelzw in [#1456](https://github.com/prefix-dev/pixi/pull/1456) - Describe the --change-ps1 option for pixi shell by @Yura52 in [#1536](https://github.com/prefix-dev/pixi/pull/1536) - Add some other quantco repos by @pavelzw in [#1542](https://github.com/prefix-dev/pixi/pull/1542) - Add example using `geos-rs` by @Hofer-Julian in [#1563](https://github.com/prefix-dev/pixi/pull/1563) #### Fixed - Tiny error in basic_usage.md by @Sjouks in [#1513](https://github.com/prefix-dev/pixi/pull/1513) - Lazy initialize client by @baszalmstra in [#1511](https://github.com/prefix-dev/pixi/pull/1511) - URL typos in rtd examples by @kklein in [#1538](https://github.com/prefix-dev/pixi/pull/1538) - Fix satisfiability for short sha hashes by @tdejager in [#1530](https://github.com/prefix-dev/pixi/pull/1530) - Wrong path passed to dynamic check by @tdejager in [#1552](https://github.com/prefix-dev/pixi/pull/1552) - Don't error if no tasks is available on platform by @hoxbro in [#1550](https://github.com/prefix-dev/pixi/pull/1550) #### Refactor - Add to use update code by @baszalmstra in [#1508](https://github.com/prefix-dev/pixi/pull/1508) #### New Contributors - @kklein made their first contribution in [#1538](https://github.com/prefix-dev/pixi/pull/1538) - @Yura52 made their first contribution in [#1536](https://github.com/prefix-dev/pixi/pull/1536) - @Sjouks made their first contribution in [#1513](https://github.com/prefix-dev/pixi/pull/1513) ### [0.24.2] - 2024-06-14 #### Documentation - Add readthedocs examples by @bollwyvl in [#1423](https://github.com/prefix-dev/pixi/pull/1423) - Fix typo in project_configuration.md by @RaulPL in [#1502](https://github.com/prefix-dev/pixi/pull/1502) #### Fixed - Too much shell variables in activation of `pixi shell` by @ruben-arts in [#1507](https://github.com/prefix-dev/pixi/pull/1507) ### [0.24.1] - 2024-06-12 #### Fixed - Replace http code %2b with + by @ruben-arts in [#1500](https://github.com/prefix-dev/pixi/pull/1500) ### [0.24.0] - 2024-06-12 #### ✨ Highlights - You can now run in a more isolated environment on `unix` machines, using `pixi run --clean-env TASK_NAME`. - You can new easily clean your environment with `pixi clean` or the cache with `pixi clean cache` #### Added - Add `pixi clean` command by @ruben-arts in [#1325](https://github.com/prefix-dev/pixi/pull/1325) - Add `--clean-env` flag to tasks and run command by @ruben-arts in [#1395](https://github.com/prefix-dev/pixi/pull/1395) - Add `description` field to `task` by @jjjermiah in [#1479](https://github.com/prefix-dev/pixi/pull/1479) - Add pixi file to the environment to add pixi specific details by @ruben-arts in [#1495](https://github.com/prefix-dev/pixi/pull/1495) #### Changed - Project environment cli by @baszalmstra in [#1433](https://github.com/prefix-dev/pixi/pull/1433) - Update task list console output by @vigneshmanick in [#1443](https://github.com/prefix-dev/pixi/pull/1443) - Upgrade uv by @tdejager in [#1436](https://github.com/prefix-dev/pixi/pull/1436) - Sort packages in `list_global_packages` by @dhirschfeld in [#1458](https://github.com/prefix-dev/pixi/pull/1458) - Added test for special chars wheel filename by @tdejager in [#1454](https://github.com/prefix-dev/pixi/pull/1454) #### Documentation - Improve multi env tasks documentation by @ruben-arts in [#1494](https://github.com/prefix-dev/pixi/pull/1494) #### Fixed - Use the activated environment when running a task by @tdejager in [#1461](https://github.com/prefix-dev/pixi/pull/1461) - Fix authentication pypi-deps for download from lockfile by @tdejager in [#1460](https://github.com/prefix-dev/pixi/pull/1460) - Display channels correctly in `pixi info` by @ruben-arts in [#1459](https://github.com/prefix-dev/pixi/pull/1459) - Render help for `--frozen` by @ruben-arts in [#1468](https://github.com/prefix-dev/pixi/pull/1468) - Don't record purl for non conda-forge channels by @nichmor in [#1451](https://github.com/prefix-dev/pixi/pull/1451) - Use best_platform to verify the run platform by @ruben-arts in [#1472](https://github.com/prefix-dev/pixi/pull/1472) - Creation of parent dir of symlink by @ruben-arts in [#1483](https://github.com/prefix-dev/pixi/pull/1483) - `pixi install --all` output missing newline by @vigneshmanick in [#1487](https://github.com/prefix-dev/pixi/pull/1487) - Don't error on already existing dependency by @ruben-arts in [#1449](https://github.com/prefix-dev/pixi/pull/1449) - Remove debug true in release by @ruben-arts in [#1477](https://github.com/prefix-dev/pixi/pull/1477) #### New Contributors - @dhirschfeld made their first contribution in [#1458](https://github.com/prefix-dev/pixi/pull/1458) [Full commit history](https://github.com/prefix-dev/pixi/compare/v0.23.0..HEAD) ### [0.23.0] - 2024-05-27 #### ✨ Highlights - This release adds two new commands `pixi config` and `pixi update` - `pixi config` allows you to `edit`, `set`, `unset`, `append`, `prepend` and `list` your local/global or system configuration. - `pixi update` re-solves the full lockfile or use `pixi update PACKAGE` to only update `PACKAGE`, making sure your project is using the latest versions that the manifest allows for. #### Added - Add `pixi config` command by @chawyehsu in [#1339](https://github.com/prefix-dev/pixi/pull/1339) - Add `pixi list --explicit` flag command by @jjjermiah in [#1403](https://github.com/prefix-dev/pixi/pull/1403) - Add `[activation.env]` table for environment variables by @ruben-arts in [#1156](https://github.com/prefix-dev/pixi/pull/1156) - Allow installing multiple envs, including `--all` at once by @tdejager in [#1413](https://github.com/prefix-dev/pixi/pull/1413) - Add `pixi update` command to re-solve the lockfile by @baszalmstra in [#1431](https://github.com/prefix-dev/pixi/pull/1431) (fixes 20 :thumbsup:) - Add `detached-environments` to the config, move environments outside the project folder by @ruben-arts in [#1381](https://github.com/prefix-dev/pixi/pull/1381) (fixes 11 :thumbsup:) #### Changed - Use the gateway to fetch repodata by @baszalmstra in [#1307](https://github.com/prefix-dev/pixi/pull/1307) - Switch to compressed mapping by @nichmor in [#1335](https://github.com/prefix-dev/pixi/pull/1335) - Warn on pypi conda clobbering by @nichmor in [#1353](https://github.com/prefix-dev/pixi/pull/1353) - Align `remove` arguments with `add` by @olivier-lacroix in [#1406](https://github.com/prefix-dev/pixi/pull/1406) - Add backward compat logic for older lock files by @nichmor in [#1425](https://github.com/prefix-dev/pixi/pull/1425) #### Documentation - Fix small screen by removing getting started section. by @ruben-arts in [#1393](https://github.com/prefix-dev/pixi/pull/1393) - Improve caching docs by @ruben-arts in [#1422](https://github.com/prefix-dev/pixi/pull/1422) - Add example, python library using gcp upload by @tdejager in [#1380](https://github.com/prefix-dev/pixi/pull/1380) - Correct typos with `--no-lockfile-update`. by @tobiasraabe in [#1396](https://github.com/prefix-dev/pixi/pull/1396) #### Fixed - Trim channel url when filter packages_for_prefix_mapping by @zen-xu in [#1391](https://github.com/prefix-dev/pixi/pull/1391) - Use the right channels when upgrading global packages by @olivier-lacroix in [#1326](https://github.com/prefix-dev/pixi/pull/1326) - Fish prompt display looks wrong in tide by @tfriedel in [#1424](https://github.com/prefix-dev/pixi/pull/1424) - Use local mapping instead of remote by @nichmor in [#1430](https://github.com/prefix-dev/pixi/pull/1430) #### Refactor - Remove unused fetch_sparse_repodata by @olivier-lacroix in [#1411](https://github.com/prefix-dev/pixi/pull/1411) - Remove project level method that are per environment by @olivier-lacroix in [#1412](https://github.com/prefix-dev/pixi/pull/1412) - Update lockfile functionality for reusability by @baszalmstra in [#1426](https://github.com/prefix-dev/pixi/pull/1426) #### New Contributors - @tfriedel made their first contribution in [#1424](https://github.com/prefix-dev/pixi/pull/1424) - @jjjermiah made their first contribution in [#1403](https://github.com/prefix-dev/pixi/pull/1403) - @tobiasraabe made their first contribution in [#1396](https://github.com/prefix-dev/pixi/pull/1396) [Full commit history](https://github.com/prefix-dev/pixi/compare/v0.22.0..v0.23.0) ### [0.22.0] - 2024-05-13 #### ✨ Highlights - Support for source pypi dependencies through the cli: - `pixi add --pypi 'package @ package.whl'`, perfect for adding just build wheels to your environment in CI. - `pixi add --pypi 'package_from_git @ git+https://github.com/org/package.git'`, to add a package from a git repository. - `pixi add --pypi 'package_from_path @ file:///path/to/package' --editable`, to add a package from a local path. #### Added - Implement more functions for `pixi add --pypi` by @wolfv in [#1244](https://github.com/prefix-dev/pixi/pull/1244) #### Documentation - Update `install` cli doc by @vigneshmanick in [#1336](https://github.com/prefix-dev/pixi/pull/1336) - Replace empty default example with no-default-feature by @beenje in [#1352](https://github.com/prefix-dev/pixi/pull/1352) - Document the add & remove cli behaviour with pyproject.toml manifest by @olivier-lacroix in [#1338](https://github.com/prefix-dev/pixi/pull/1338) - Add environment activation to GitHub actions docs by @pavelzw in [#1371](https://github.com/prefix-dev/pixi/pull/1371) - Clarify in CLI that run can also take commands by @twrightsman in [#1368](https://github.com/prefix-dev/pixi/pull/1368) #### Fixed - Automated update of install script in pixi.sh by @ruben-arts in [#1351](https://github.com/prefix-dev/pixi/pull/1351) - Wrong description on `pixi project help` by @notPlancha in [#1358](https://github.com/prefix-dev/pixi/pull/1358) - Don't need a python interpreter when not having `pypi` dependencies. by @ruben-arts in [#1366](https://github.com/prefix-dev/pixi/pull/1366) - Don't error on not editable not path by @ruben-arts in [#1365](https://github.com/prefix-dev/pixi/pull/1365) - Align shell-hook cli with shell by @ruben-arts in [#1364](https://github.com/prefix-dev/pixi/pull/1364) - Only write prefix file if needed by @ruben-arts in [#1363](https://github.com/prefix-dev/pixi/pull/1363) #### Refactor - Lock-file resolve functionality in separated modules by @tdejager in [#1337](https://github.com/prefix-dev/pixi/pull/1337) - Use generic for RepoDataRecordsByName and PypiRecordsByName by @olivier-lacroix in [#1341](https://github.com/prefix-dev/pixi/pull/1341) #### New Contributors - @twrightsman made their first contribution in [#1368](https://github.com/prefix-dev/pixi/pull/1368) - @notPlancha made their first contribution in [#1358](https://github.com/prefix-dev/pixi/pull/1358) - @vigneshmanick made their first contribution in [#1336](https://github.com/prefix-dev/pixi/pull/1336) [Full commit history](https://github.com/prefix-dev/pixi/compare/v0.21.1..v0.22.0) ### [0.21.1] - 2024-05-07 #### Fixed - Use read timeout, not global timeout by @wolfv in [#1329](https://github.com/prefix-dev/pixi/pull/1329) - Channel priority logic by @ruben-arts in [#1332](https://github.com/prefix-dev/pixi/pull/1332) [Full commit history](https://github.com/prefix-dev/pixi/compare/v0.21.0..v0.21.1) ### [0.21.0] - 2024-05-06 #### ✨ Highlights - This release adds support for configuring PyPI settings globally, to use alternative PyPI indexes and load credentials with keyring. - We now support cross-platform running, for `osx-64` on `osx-arm64` and `wasm` environments. - There is now a `no-default-feature` option to simplify usage of environments. #### Added - Add pypi config for global local config file + keyring support by @wolfv in [#1279](https://github.com/prefix-dev/pixi/pull/1279) - Allow for cross-platform running, for `osx-64` on `osx-arm64` and `wasm` environments by @wolfv in [#1020](https://github.com/prefix-dev/pixi/pull/1020) #### Changed - Add `no-default-feature` option to environments by @olivier-lacroix in [#1092](https://github.com/prefix-dev/pixi/pull/1092) - Add `/etc/pixi/config.toml` to global configuration search paths by @pavelzw in [#1304](https://github.com/prefix-dev/pixi/pull/1304) - Change global config fields to kebab-case by @tdejager in [#1308](https://github.com/prefix-dev/pixi/pull/1308) - Show all available task with `task list` by @Hoxbro in [#1286](https://github.com/prefix-dev/pixi/pull/1286) - Allow to emit activation environment variables as JSON by @borchero in [#1317](https://github.com/prefix-dev/pixi/pull/1317) - Use locked pypi packages as preferences in the pypi solve to get minimally updating lock files by @ruben-arts in [#1320](https://github.com/prefix-dev/pixi/pull/1320) - Allow to upgrade several global packages at once by @olivier-lacroix in [#1324](https://github.com/prefix-dev/pixi/pull/1324) #### Documentation - Typo in tutorials python by @carschandler in [#1297](https://github.com/prefix-dev/pixi/pull/1297) - Python Tutorial: Dependencies, PyPI, Order, Grammar by @JesperDramsch in [#1313](https://github.com/prefix-dev/pixi/pull/1313) #### Fixed - Schema version and add it to tbump by @ruben-arts in [#1284](https://github.com/prefix-dev/pixi/pull/1284) - Make integration test fail in ci and fix ssh issue by @ruben-arts in [#1301](https://github.com/prefix-dev/pixi/pull/1301) - Automate adding install scripts to the docs by @ruben-arts in [#1302](https://github.com/prefix-dev/pixi/pull/1302) - Do not always request for prefix mapping by @nichmor in [#1300](https://github.com/prefix-dev/pixi/pull/1300) - Align CLI aliases and add missing by @ruben-arts in [#1316](https://github.com/prefix-dev/pixi/pull/1316) - Alias `depends_on` to `depends-on` by @ruben-arts in [#1310](https://github.com/prefix-dev/pixi/pull/1310) - Add error if channel or platform doesn't exist on remove by @ruben-arts in [#1315](https://github.com/prefix-dev/pixi/pull/1315) - Allow spec in `pixi q` instead of only name by @ruben-arts in [#1314](https://github.com/prefix-dev/pixi/pull/1314) - Remove dependency on sysroot for linux by @ruben-arts in [#1319](https://github.com/prefix-dev/pixi/pull/1319) - Fix linking symlink issue, by updating to the latest `rattler` by @baszalmstra in [#1327](https://github.com/prefix-dev/pixi/pull/1327) #### Refactor - Use IndexSet instead of Vec for collections of unique elements by @olivier-lacroix in [#1289](https://github.com/prefix-dev/pixi/pull/1289) - Use generics over PyPiDependencies and CondaDependencies by @olivier-lacroix in [#1303](https://github.com/prefix-dev/pixi/pull/1303) #### New Contributors - @borchero made their first contribution in [#1317](https://github.com/prefix-dev/pixi/pull/1317) - @JesperDramsch made their first contribution in [#1313](https://github.com/prefix-dev/pixi/pull/1313) - @Hoxbro made their first contribution in [#1286](https://github.com/prefix-dev/pixi/pull/1286) - @carschandler made their first contribution in [#1297](https://github.com/prefix-dev/pixi/pull/1297) [Full commit history](https://github.com/prefix-dev/pixi/compare/v0.20.1..v0.21.0) ### [0.20.1] - 2024-04-26 #### ✨ Highlights - Big improvements on the pypi-editable installs. #### Fixed - Editable non-satisfiable by @baszalmstra in [#1251](https://github.com/prefix-dev/pixi/pull/1251) - Satisfiability with pypi extras by @baszalmstra in [#1253](https://github.com/prefix-dev/pixi/pull/1253) - Change global install activation script permission from 0o744 -> 0o755 by @zen-xu in [#1250](https://github.com/prefix-dev/pixi/pull/1250) - Avoid creating Empty TOML tables by @olivier-lacroix in [#1270](https://github.com/prefix-dev/pixi/pull/1270) - Uses the special-case uv path handling for both built and source by @tdejager in [#1263](https://github.com/prefix-dev/pixi/pull/1263) - Modify test before attempting to write to .bash_profile in install.sh by @bruchim-cisco in [#1267](https://github.com/prefix-dev/pixi/pull/1267) - Parse properly 'default' as environment Cli argument by @olivier-lacroix in [#1247](https://github.com/prefix-dev/pixi/pull/1247) - Apply `schema.json` normalization, add to docs by @bollwyvl in [#1265](https://github.com/prefix-dev/pixi/pull/1265) - Improve absolute path satisfiability by @tdejager in [#1252](https://github.com/prefix-dev/pixi/pull/1252) - Improve parse deno error and make task a required field in the cli by @ruben-arts in [#1260](https://github.com/prefix-dev/pixi/pull/1260) #### New Contributors - @bollwyvl made their first contribution in [#1265](https://github.com/prefix-dev/pixi/pull/1265) - @bruchim-cisco made their first contribution in [#1267](https://github.com/prefix-dev/pixi/pull/1267) - @zen-xu made their first contribution in [#1250](https://github.com/prefix-dev/pixi/pull/1250) [Full commit history](https://github.com/prefix-dev/pixi/compare/v0.20.0..v0.20.1) ### [0.20.0] - 2024-04-19 #### ✨ Highlights - We now support `env` variables in the `task` definition, these can also be used as default values for parameters in your task which you can overwrite with your shell's env variables. e.g. `task = { cmd = "task to run", env = { VAR="value1", PATH="my/path:$PATH" } }` - We made a big effort on fixing issues and improving documentation! #### Added - Add `env` to the tasks to specify tasks specific environment variables by @wolfv in https://github.com/prefix-dev/pixi/pull/972 #### Changed - Add `--pyproject` option to `pixi init` with a pyproject.toml by @olivier-lacroix in [#1188](https://github.com/prefix-dev/pixi/pull/1188) - Upgrade to new uv version 0.1.32 by @tdejager in [#1208](https://github.com/prefix-dev/pixi/pull/1208) #### Documentation - Document `pixi.lock` by @ruben-arts in [#1209](https://github.com/prefix-dev/pixi/pull/1209) - Document channel `priority` definition by @ruben-arts in [#1234](https://github.com/prefix-dev/pixi/pull/1234) - Add rust tutorial including openssl example by @ruben-arts in [#1155](https://github.com/prefix-dev/pixi/pull/1155) - Add python tutorial to documentation by @tdejager in [#1179](https://github.com/prefix-dev/pixi/pull/1179) - Add JupyterLab integration docs by @renan-r-santos in [#1147](https://github.com/prefix-dev/pixi/pull/1147) - Add Windows support for PyCharm integration by @pavelzw in [#1192](https://github.com/prefix-dev/pixi/pull/1192) - Setup_pixi for local pixi installation by @ytausch in [#1181](https://github.com/prefix-dev/pixi/pull/1181) - Update pypi docs by @Hofer-Julian in [#1215](https://github.com/prefix-dev/pixi/pull/1215) - Fix order of `--no-deps` when pip installing in editable mode by @glemaitre in [#1220](https://github.com/prefix-dev/pixi/pull/1220) - Fix frozen documentation by @ruben-arts in [#1167](https://github.com/prefix-dev/pixi/pull/1167) #### Fixed - Small typo in list cli by @tdejager in [#1169](https://github.com/prefix-dev/pixi/pull/1169) - Issue with invalid solve group by @baszalmstra in [#1190](https://github.com/prefix-dev/pixi/pull/1190) - Improve error on parsing lockfile by @ruben-arts in [#1180](https://github.com/prefix-dev/pixi/pull/1180) - Replace `_` with `-` when creating environments from features by @wolfv in [#1203](https://github.com/prefix-dev/pixi/pull/1203) - Prevent duplicate direct dependencies in tree by @abkfenris in [#1184](https://github.com/prefix-dev/pixi/pull/1184) - Use project root directory instead of task.working_directory for base dir when hashing by @wolfv in [#1202](https://github.com/prefix-dev/pixi/pull/1202) - Do not leak env vars from bat scripts in cmd.exe by @wolfv in [#1205](https://github.com/prefix-dev/pixi/pull/1205) - Make file globbing behave more as expected by @wolfv in [#1204](https://github.com/prefix-dev/pixi/pull/1204) - Fix for using file::// in pyproject.toml dependencies by @tdejager in [#1196](https://github.com/prefix-dev/pixi/pull/1196) - Improve pypi version conversion in pyproject.toml dependencies by @wolfv in [#1201](https://github.com/prefix-dev/pixi/pull/1201) - Update to the latest rattler by @wolfv in [#1235](https://github.com/prefix-dev/pixi/pull/1235) #### **BREAKING** - `task = { cmd = "task to run", cwd = "folder", inputs = "input.txt", output = "output.txt"}` Where `input.txt` and `output.txt` where previously in `folder` they are now relative the project root. This changed in: [#1202](https://github.com/prefix-dev/pixi/pull/1202) - `task = { cmd = "task to run", inputs = "input.txt"}` previously searched for all `input.txt` files now only for the ones in the project root. This changed in: [#1204](https://github.com/prefix-dev/pixi/pull/1204) #### New Contributors - @glemaitre made their first contribution in [#1220](https://github.com/prefix-dev/pixi/pull/1220) [Full commit history](https://github.com/prefix-dev/pixi/compare/v0.19.1..v0.20.0) ### [0.19.1] - 2024-04-11 #### ✨ Highlights This fixes the issue where pixi would generate broken environments/lockfiles when a mapping for a brand-new version of a package is missing. #### Changed - Add fallback mechanism for missing mapping by @nichmor in [#1166](https://github.com/prefix-dev/pixi/pull/1166) [Full commit history](https://github.com/prefix-dev/pixi/compare/v0.19.0..v0.19.1) ### [0.19.0] - 2024-04-10 #### ✨ Highlights - This release adds a new `pixi tree` command to show the dependency tree of the project. - Pixi now persists the manifest and environment when activating a shell, so you can use pixi as if you are in that folder while in the shell. #### Added - `pixi tree` command to show dependency tree by @abkfenris in [#1069](https://github.com/prefix-dev/pixi/pull/1069) - Persistent shell manifests by @abkfenris in [#1080](https://github.com/prefix-dev/pixi/pull/1080) - Add to pypi in feature (`pixi add --feature test --pypi package`) by @ruben-arts in [#1135](https://github.com/prefix-dev/pixi/pull/1135) - Use new mapping by @nichmor in [#888](https://github.com/prefix-dev/pixi/pull/888) - `--no-progress` to disable all progress bars by @baszalmstra in [#1105](https://github.com/prefix-dev/pixi/pull/1105) - Create a table if channel is specified (`pixi add conda-forge::rattler-build`) by @baszalmstra in [#1079](https://github.com/prefix-dev/pixi/pull/1079) #### Changed - Add the project itself as an editable dependency by @olivier-lacroix in [#1084](https://github.com/prefix-dev/pixi/pull/1084) - Get `tool.pixi.project.name` from `project.name` by @olivier-lacroix in [#1112](https://github.com/prefix-dev/pixi/pull/1112) - Create `features` and `environments` from extras by @olivier-lacroix in [#1077](https://github.com/prefix-dev/pixi/pull/1077) - Pypi supports come out of Beta by @olivier-lacroix in [#1120](https://github.com/prefix-dev/pixi/pull/1120) - Enable to force `PIXI_ARCH` for pixi installation by @beenje in [#1129](https://github.com/prefix-dev/pixi/pull/1129) - Improve tool.pixi.project detection logic by @olivier-lacroix in [#1127](https://github.com/prefix-dev/pixi/pull/1127) - Add purls for packages if adding pypi dependencies by @nichmor in [#1148](https://github.com/prefix-dev/pixi/pull/1148) - Add env name if not default to `tree` and `list` commands by @ruben-arts in [#1145](https://github.com/prefix-dev/pixi/pull/1145) #### Documentation - Add MODFLOW 6 to community docs by @Hofer-Julian in [#1125](https://github.com/prefix-dev/pixi/pull/1125) - Addition of ros2 tutorial by @ruben-arts in [#1116](https://github.com/prefix-dev/pixi/pull/1116) - Improve install script docs by @ruben-arts in [#1136](https://github.com/prefix-dev/pixi/pull/1136) - More structured table of content by @tdejager in [#1142](https://github.com/prefix-dev/pixi/pull/1142) #### Fixed - Amend syntax in `conda-meta/history` to prevent `conda.history.History.parse()` error by @jaimergp in [#1117](https://github.com/prefix-dev/pixi/pull/1117) - Fix docker example and include `pyproject.toml` by @tdejager in [#1121](https://github.com/prefix-dev/pixi/pull/1121) #### New Contributors - @abkfenris made their first contribution in [#1069](https://github.com/prefix-dev/pixi/pull/1069) - @beenje made their first contribution in [#1129](https://github.com/prefix-dev/pixi/pull/1129) - @jaimergp made their first contribution in [#1117](https://github.com/prefix-dev/pixi/pull/1117) [Full commit history](https://github.com/prefix-dev/pixi/compare/v0.18.0..v0.19.0) ### [0.18.0] - 2024-04-02 #### ✨ Highlights - This release adds support for `pyproject.toml`, now pixi reads from the `[tool.pixi]` table. - We now support editable PyPI dependencies, and PyPI source dependencies, including `git`, `path`, and `url` dependencies. > [!TIP] These new features are part of the ongoing effort to make pixi more flexible, powerful, and comfortable for the python users. They are still in progress so expect more improvements on these features soon, so please report any issues you encounter and follow our next releases! #### Added - Support for `pyproject.toml` by @olivier-lacroix in [#999](https://github.com/prefix-dev/pixi/pull/999) - Support for PyPI source dependencies by @tdejager in [#985](https://github.com/prefix-dev/pixi/pull/985) - Support for editable PyPI dependencies by @tdejager in [#1044](https://github.com/prefix-dev/pixi/pull/1044) #### Changed - `XDG_CONFIG_HOME` and `XDG_CACHE_HOME` compliance by @chawyehsu in [#1050](https://github.com/prefix-dev/pixi/pull/1050) - Build pixi for windows arm by @baszalmstra in [#1053](https://github.com/prefix-dev/pixi/pull/1053) - Platform literals by @baszalmstra in [#1054](https://github.com/prefix-dev/pixi/pull/1054) - Cli docs: --user is actually --username - Fixed error in auth example (CLI docs) by @ytausch in [#1076](https://github.com/prefix-dev/pixi/pull/1076) #### Documentation - Add lockfile update description in preparation for pixi update by @ruben-arts in [#1073](https://github.com/prefix-dev/pixi/pull/1073) - `zsh` may be used for installation on macOS by @pya in [#1091](https://github.com/prefix-dev/pixi/pull/1091) - Fix typo in `pixi auth` documentation by @ytausch in [#1076](https://github.com/prefix-dev/pixi/pull/1076) - Add `rstudio` to the IDE integration docs by @wolfv in [#1144](https://github.com/prefix-dev/pixi/pull/1144) #### Fixed - Test failure on riscv64 by @hack3ric in [#1045](https://github.com/prefix-dev/pixi/pull/1045) - Validation test was testing on a wrong pixi.toml by @ruben-arts in [#1056](https://github.com/prefix-dev/pixi/pull/1056) - Pixi list shows path and editable by @baszalmstra in [#1100](https://github.com/prefix-dev/pixi/pull/1100) - Docs ci by @ruben-arts in [#1074](https://github.com/prefix-dev/pixi/pull/1074) - Add error for unsupported pypi dependencies by @baszalmstra in [#1052](https://github.com/prefix-dev/pixi/pull/1052) - Interactively delete environment when it was relocated by @baszalmstra in [#1102](https://github.com/prefix-dev/pixi/pull/1102) - Allow solving for different platforms by @baszalmstra in [#1101](https://github.com/prefix-dev/pixi/pull/1101) - Don't allow extra keys in pypi requirements by @baszalmstra in [#1104](https://github.com/prefix-dev/pixi/pull/1104) - Solve when moving dependency from conda to pypi by @baszalmstra in [#1099](https://github.com/prefix-dev/pixi/pull/1099) #### New Contributors - @pya made their first contribution in [#1091](https://github.com/prefix-dev/pixi/pull/1091) - @ytausch made their first contribution in [#1076](https://github.com/prefix-dev/pixi/pull/1076) - @hack3ric made their first contribution in [#1045](https://github.com/prefix-dev/pixi/pull/1045) - @olivier-lacroix made their first contribution in [#999](https://github.com/prefix-dev/pixi/pull/999) - @henryiii made their first contribution in [#1063](https://github.com/prefix-dev/pixi/pull/1063) [Full commit history](https://github.com/prefix-dev/pixi/compare/v0.17.1..v0.18.0) ### [0.17.1] - 2024-03-21 #### ✨ Highlights A quick bug-fix release for `pixi list`. #### Documentation - Fix typo by @pavelzw in [#1028](https://github.com/prefix-dev/pixi/pull/1028) #### Fixed - Remove the need for a python interpreter in `pixi list` by @baszalmstra in [#1033](https://github.com/prefix-dev/pixi/pull/1033) ### [0.17.0] - 2024-03-19 #### ✨ Highlights - This release greatly improves `pixi global` commands, thanks to @chawyehsu! - We now support global (or local) configuration for pixi's own behavior, including mirrors, and OCI registries. - We support channel mirrors for corporate environments! - Faster `task` execution thanks to caching πŸš€ Tasks that already executed successfully can be skipped based on the hash of the `inputs` and `outputs`. - PyCharm and GitHub Actions integration thanks to @pavelzw – read more about it in the docs! #### Added - Add citation file by @ruben-arts in [#908](https://github.com/prefix-dev/pixi/pull/908) - Add a pixi badge by @ruben-arts in [#961](https://github.com/prefix-dev/pixi/pull/961) - Add deserialization of pypi source dependencies from toml by @ruben-arts and @wolf in [#895](https://github.com/prefix-dev/pixi/pull/895) [#984](https://github.com/prefix-dev/pixi/pull/984) - Implement mirror and OCI settings by @wolfv in [#988](https://github.com/prefix-dev/pixi/pull/988) - Implement `inputs` and `outputs` hash based task skipping by @wolfv in [#933](https://github.com/prefix-dev/pixi/pull/933) #### Changed - Refined global upgrade commands by @chawyehsu in [#948](https://github.com/prefix-dev/pixi/pull/948) - Global upgrade supports matchspec by @chawyehsu in [#962](https://github.com/prefix-dev/pixi/pull/962) - Improve `pixi search` with platform selection and making limit optional by @wolfv in [#979](https://github.com/prefix-dev/pixi/pull/979) - Implement global config options by @wolfv in [#960](https://github.com/prefix-dev/pixi/pull/960) [#1015](https://github.com/prefix-dev/pixi/pull/1015) [#1019](https://github.com/prefix-dev/pixi/pull/1019) - Update auth to use rattler cli by @kassoulait by @ruben-arts in [#986](https://github.com/prefix-dev/pixi/pull/986) #### Documentation - Remove cache: true from setup-pixi by @pavelzw in [#950](https://github.com/prefix-dev/pixi/pull/950) - Add GitHub Actions documentation by @pavelzw in [#955](https://github.com/prefix-dev/pixi/pull/955) - Add PyCharm documentation by @pavelzw in [#974](https://github.com/prefix-dev/pixi/pull/974) - Mention `watch_file` in direnv usage by @pavelzw in [#983](https://github.com/prefix-dev/pixi/pull/983) - Add tip to help users when no PROFILE file exists by @ruben-arts in [#991](https://github.com/prefix-dev/pixi/pull/991) - Move yaml comments into mkdocs annotations by @pavelzw in [#1003](https://github.com/prefix-dev/pixi/pull/1003) - Fix --env and extend actions examples by @ruben-arts in [#1005](https://github.com/prefix-dev/pixi/pull/1005) - Add Wflow to projects built with pixi by @Hofer-Julian in [#1006](https://github.com/prefix-dev/pixi/pull/1006) - Removed `linenums` to avoid buggy visualization by @ruben-arts in [#1002](https://github.com/prefix-dev/pixi/pull/1002) - Fix typos by @pavelzw in [#1016](https://github.com/prefix-dev/pixi/pull/1016) #### Fixed - Pypi dependencies not being removed by @tdejager in [#952](https://github.com/prefix-dev/pixi/pull/952) - Permissions for lint pr by @ruben-arts in [#852](https://github.com/prefix-dev/pixi/pull/852) - Install Windows executable with `install.sh` in Git Bash by @jdblischak in [#966](https://github.com/prefix-dev/pixi/pull/966) - Proper scanning of the conda-meta folder for `json` entries by @wolfv in [#971](https://github.com/prefix-dev/pixi/pull/971) - Global shim scripts for Windows by @wolfv in [#975](https://github.com/prefix-dev/pixi/pull/975) - Correct fish prompt by @wolfv in [#981](https://github.com/prefix-dev/pixi/pull/981) - Prefix_file rename by @ruben-arts in [#959](https://github.com/prefix-dev/pixi/pull/959) - Conda transitive dependencies of pypi packages are properly extracted by @baszalmstra in [#967](https://github.com/prefix-dev/pixi/pull/967) - Make tests more deterministic and use single * for glob expansion by @wolfv in [#987](https://github.com/prefix-dev/pixi/pull/987) - Create conda-meta/history file by @pavelzw in [#995](https://github.com/prefix-dev/pixi/pull/995) - Pypi dependency parsing was too lenient by @wolfv in [#984](https://github.com/prefix-dev/pixi/pull/984) - Add reactivation of the environment in pixi shell by @wolfv in [#982](https://github.com/prefix-dev/pixi/pull/982) - Add `tool` to strict json schema by @ruben-arts in [#969](https://github.com/prefix-dev/pixi/pull/969) #### New Contributors - @jdblischak made their first contribution in [#966](https://github.com/prefix-dev/pixi/pull/966) - @kassoulait made their first contribution in [#986](https://github.com/prefix-dev/pixi/pull/986) [Full commit history](https://github.com/prefix-dev/pixi/compare/v0.16.1..v0.17.0) ### [0.16.1] - 2024-03-11 #### Fixed - Parse lockfile matchspecs lenient, fixing bug introduced in `0.16.0` by @ruben-arts in [#951](https://github.com/prefix-dev/pixi/pull/951) [Full commit history](https://github.com/prefix-dev/pixi/compare/v0.16.0..v0.16.1) ### [0.16.0] - 2024-03-09 #### ✨ Highlights - This release removes [`rip`](https://github.com/prefix-dev/rip) and add [`uv`](https://github.com/astral-sh/uv) as the PyPI resolver and installer. #### Added - Add tcsh install support by @obust in [#898](https://github.com/prefix-dev/pixi/pull/898) - Add user agent to pixi http client by @baszalmstra in [#892](https://github.com/prefix-dev/pixi/pull/892) - Add a schema for the pixi.toml by @ruben-arts in [#936](https://github.com/prefix-dev/pixi/pull/936) #### Changed - Switch from rip to uv by @tdejager in [#863](https://github.com/prefix-dev/pixi/pull/863) - Move uv options into context by @tdejager in [#911](https://github.com/prefix-dev/pixi/pull/911) - Add Deltares projects to Community.md by @Hofer-Julian in [#920](https://github.com/prefix-dev/pixi/pull/920) - Upgrade to uv 0.1.16, updated for changes in the API by @tdejager in [#935](https://github.com/prefix-dev/pixi/pull/935) #### Fixed - Made the uv re-install logic a bit more clear by @tdejager in [#894](https://github.com/prefix-dev/pixi/pull/894) - Avoid duplicate pip dependency while importing environment.yaml by @sumanth-manchala in [#890](https://github.com/prefix-dev/pixi/pull/890) - Handle custom channels when importing from env yaml by @sumanth-manchala in [#901](https://github.com/prefix-dev/pixi/pull/901) - Pip editable installs getting uninstalled by @renan-r-santos in [#902](https://github.com/prefix-dev/pixi/pull/902) - Highlight pypi deps in pixi list by @sumanth-manchala in [#907](https://github.com/prefix-dev/pixi/pull/907) - Default to the default environment if possible by @ruben-arts in [#921](https://github.com/prefix-dev/pixi/pull/921) - Switching channels by @baszalmstra in [#923](https://github.com/prefix-dev/pixi/pull/923) - Use correct name of the channel on adding by @ruben-arts in [#928](https://github.com/prefix-dev/pixi/pull/928) - Turn back on jlap for faster repodata fetching by @ruben-arts in [#937](https://github.com/prefix-dev/pixi/pull/937) - Remove dists site-packages's when python interpreter changes by @tdejager in [#896](https://github.com/prefix-dev/pixi/pull/896) #### New Contributors - @obust made their first contribution in [#898](https://github.com/prefix-dev/pixi/pull/898) - @renan-r-santos made their first contribution in [#902](https://github.com/prefix-dev/pixi/pull/902) [Full Commit history](https://github.com/prefix-dev/pixi/compare/v0.15.2..v0.16.0) ### [0.15.2] - 2024-02-29 #### Changed - Add more info to a failure of activation by @ruben-arts in [#873](https://github.com/prefix-dev/pixi/pull/873) #### Fixed - Improve global list UX when there is no global env dir created by @sumanth-manchala in [#865](https://github.com/prefix-dev/pixi/pull/865) - Update rattler to `v0.19.0` by @AliPiccioniQC in [#885](https://github.com/prefix-dev/pixi/pull/885) - Error on `pixi run` if platform is not supported by @ruben-arts in [#878](https://github.com/prefix-dev/pixi/pull/878) #### New Contributors - @sumanth-manchala made their first contribution in [#865](https://github.com/prefix-dev/pixi/pull/865) - @AliPiccioniQC made their first contribution in [#885](https://github.com/prefix-dev/pixi/pull/885) [Full commit history](https://github.com/prefix-dev/pixi/compare/v0.15.1..v0.15.2) ### [0.15.1] - 2024-02-26 #### Added - Add prefix to project info json output by @baszalmstra in [#859](https://github.com/prefix-dev/pixi/pull/859) #### Changed - New `pixi global list` display format by @chawyehsu in [#723](https://github.com/prefix-dev/pixi/pull/723) - Add direnv usage by @pavelzw in [#845](https://github.com/prefix-dev/pixi/pull/845) - Add docker example by @pavelzw in [#846](https://github.com/prefix-dev/pixi/pull/846) - Install/remove multiple packages globally by @chawyehsu in [#854](https://github.com/prefix-dev/pixi/pull/854) #### Fixed - Prefix file in `init --import` by @ruben-arts in [#855](https://github.com/prefix-dev/pixi/pull/855) - Environment and feature names in pixi info --json by @baszalmstra in [#857](https://github.com/prefix-dev/pixi/pull/857) [Full commit history](https://github.com/prefix-dev/pixi/compare/v0.15.0..v0.15.1) ### [0.15.0] - 2024-02-23 #### ✨ Highlights - `[pypi-dependencies]` now get build in the created environment so it uses the conda installed build tools. - `pixi init --import env.yml` to import an existing conda environment file. - `[target.unix.dependencies]` to specify dependencies for unix systems instead of per platform. > [!WARNING] This versions build failed, use `v0.15.1` #### Added - pass environment variables during pypi resolution and install ([#818](https://github.com/prefix-dev/pixi/pull/818)) - skip micromamba style selector lines and warn about them ([#830](https://github.com/prefix-dev/pixi/pull/830)) - add import yml flag ([#792](https://github.com/prefix-dev/pixi/pull/792)) - check duplicate dependencies ([#717](https://github.com/prefix-dev/pixi/pull/717)) - *(ci)* check conventional PR title ([#820](https://github.com/prefix-dev/pixi/pull/820)) - add `--feature` to `pixi add` ([#803](https://github.com/prefix-dev/pixi/pull/803)) - add windows, macos, linux and unix to targets ([#832](https://github.com/prefix-dev/pixi/pull/832)) #### Fixed - cache and retry pypi name mapping ([#839](https://github.com/prefix-dev/pixi/pull/839)) - check duplicates while adding dependencies ([#829](https://github.com/prefix-dev/pixi/pull/829)) - logic `PIXI_NO_PATH_UPDATE` variable ([#822](https://github.com/prefix-dev/pixi/pull/822)) #### Other - add `mike` to the documentation and update looks ([#809](https://github.com/prefix-dev/pixi/pull/809)) - add instructions for installing on Alpine Linux ([#828](https://github.com/prefix-dev/pixi/pull/828)) - more error reporting in `self-update` ([#823](https://github.com/prefix-dev/pixi/pull/823)) - disabled `jlap` for now ([#836](https://github.com/prefix-dev/pixi/pull/823)) [Full commit history](https://github.com/prefix-dev/pixi/compare/v0.14.0..v0.15.0) ### [0.14.0] - 2024-02-15 #### ✨ Highlights Now, `solve-groups` can be used in `[environments]` to ensure dependency alignment across different environments without simultaneous installation. This feature is particularly beneficial for managing identical dependencies in `test` and `production` environments. Example configuration: ```toml [environments] test = { features = ["prod", "test"], solve-groups = ["group1"] } prod = { features = ["prod"], solve-groups = ["group1"] } ``` This setup simplifies managing dependencies that must be consistent across `test` and `production`. #### Added - Add index field to pypi requirements by @vlad-ivanov-name in [#784](https://github.com/prefix-dev/pixi/pull/784) - Add `-f`/`--feature` to the `pixi project platform` command by @ruben-arts in [#785](https://github.com/prefix-dev/pixi/pull/785) - Warn user when unused features are defined by @ruben-arts in [#762](https://github.com/prefix-dev/pixi/pull/762) - Disambiguate tasks interactive by @baszalmstra in [#766](https://github.com/prefix-dev/pixi/pull/766) - Solve groups for conda by @baszalmstra in [#783](https://github.com/prefix-dev/pixi/pull/783) - Pypi solve groups by @baszalmstra in [#802](https://github.com/prefix-dev/pixi/pull/802) - Enable reflinks by @baszalmstra in [#729](https://github.com/prefix-dev/pixi/pull/729) #### Changed - Add environment name to the progress by @ruben-arts in [#788](https://github.com/prefix-dev/pixi/pull/788) - Set color scheme by @ruben-arts in [#773](https://github.com/prefix-dev/pixi/pull/773) - Update lock on `pixi list` by @ruben-arts in [#775](https://github.com/prefix-dev/pixi/pull/775) - Use default env if task available in it. by @ruben-arts in [#772](https://github.com/prefix-dev/pixi/pull/772) - Color environment name in install step by @ruben-arts in [#795](https://github.com/prefix-dev/pixi/pull/795) #### Fixed - Running cuda env and using those tasks. by @ruben-arts in [#764](https://github.com/prefix-dev/pixi/pull/764) - Make svg a gif by @ruben-arts in [#782](https://github.com/prefix-dev/pixi/pull/782) - Fmt by @ruben-arts - Check for correct platform in task env creation by @ruben-arts in [#759](https://github.com/prefix-dev/pixi/pull/759) - Remove using source name by @ruben-arts in [#765](https://github.com/prefix-dev/pixi/pull/765) - Auto-guessing of the shell in the `shell-hook` by @ruben-arts in https://github.com/prefix-dev/pixi/pull/811 - `sdist` with direct references by @nichmor in https://github.com/prefix-dev/pixi/pull/813 #### Miscellaneous - Add slim-trees to community projects by @pavelzw in [#760](https://github.com/prefix-dev/pixi/pull/760) - Add test to default env in polarify example - Add multiple machine example by @ruben-arts in [#757](https://github.com/prefix-dev/pixi/pull/757) - Add more documentation on `environments` by @ruben-arts in [#790](https://github.com/prefix-dev/pixi/pull/790) - Update rip and rattler by @wolfv in [#798](https://github.com/prefix-dev/pixi/pull/798) - Rattler 0.18.0 by @baszalmstra in [#805](https://github.com/prefix-dev/pixi/pull/805) - Rip 0.8.0 by @nichmor in [#806](https://github.com/prefix-dev/pixi/pull/806) - Fix authentication path by @pavelzw in [#796](https://github.com/prefix-dev/pixi/pull/796) - Initial addition of integration test by @ruben-arts in https://github.com/prefix-dev/pixi/pull/804 #### New Contributors - @vlad-ivanov-name made their first contribution in [#784](https://github.com/prefix-dev/pixi/pull/784) - @nichmor made their first contribution in [#806](https://github.com/prefix-dev/pixi/pull/806) [Full commit history](https://github.com/prefix-dev/pixi/compare/v0.13.0..v0.14.0) ### [0.13.0] - 2024-02-01 #### ✨ Highlights This release is pretty crazy in amount of features! The major ones are: - We added support for multiple environments. :tada: Checkout the [documentation](https://pixi.sh/configuration/#the-feature-and-environments-tables) - We added support for `sdist` installation, which greatly improves the amount of packages that can be installed from PyPI. :rocket: > [!IMPORTANT] > > Renaming of `PIXI_PACKAGE_*` variables: > > ```text > PIXI_PACKAGE_ROOT -> PIXI_PROJECT_ROOT > PIXI_PACKAGE_NAME -> PIXI_PROJECT_NAME > PIXI_PACKAGE_MANIFEST -> PIXI_PROJECT_MANIFEST > PIXI_PACKAGE_VERSION -> PIXI_PROJECT_VERSION > PIXI_PACKAGE_PLATFORMS -> PIXI_ENVIRONMENT_PLATFORMS > ``` > > Check documentation here: https://pixi.sh/environment/ > > [!IMPORTANT] > > The `.pixi/env/` folder has been moved to accommodate multiple environments. If you only have one environment it is now named `.pixi/envs/default`. #### Added - Add support for multiple environment: - Update to rattler lock v4 by @baszalmstra in [#698](https://github.com/prefix-dev/pixi/pull/698) - Multi-env installation and usage by @baszalmstra in [#721](https://github.com/prefix-dev/pixi/pull/721) - Update all environments in the lock-file when requesting an environment by @baszalmstra in [#711](https://github.com/prefix-dev/pixi/pull/711) - Run tasks in the env they are defined by @baszalmstra in [#731](https://github.com/prefix-dev/pixi/pull/731) - `polarify` use-case as an example by @ruben-arts in [#735](https://github.com/prefix-dev/pixi/pull/735) - Make environment name parsing strict by @ruben-arts in [#673](https://github.com/prefix-dev/pixi/pull/673) - Use named environments (only "default" for now) by @ruben-arts in [#674](https://github.com/prefix-dev/pixi/pull/674) - Use task graph instead of traversal by @baszalmstra in [#725](https://github.com/prefix-dev/pixi/pull/725) - Multi env documentation by @ruben-arts in [#703](https://github.com/prefix-dev/pixi/pull/703) - `pixi info -e/--environment` option by @ruben-arts in [#676](https://github.com/prefix-dev/pixi/pull/676) - `pixi channel add -f/--feature` option by @ruben-arts in [#700](https://github.com/prefix-dev/pixi/pull/700) - `pixi channel remove -f/--feature` option by @ruben-arts in [#706](https://github.com/prefix-dev/pixi/pull/706) - `pixi remove -f/--feature` option by @ruben-arts in [#680](https://github.com/prefix-dev/pixi/pull/680) - `pixi task list -e/--environment` option by @ruben-arts in [#694](https://github.com/prefix-dev/pixi/pull/694) - `pixi task remove -f/--feature` option by @ruben-arts in [#694](https://github.com/prefix-dev/pixi/pull/694) - `pixi install -e/--environment` option by @ruben-arts in [#722](https://github.com/prefix-dev/pixi/pull/722) - Support for sdists in `pypi-dependencies` by @tdejager in [#664](https://github.com/prefix-dev/pixi/pull/664) - Add pre-release support to `pypi-dependencies` by @tdejager in [#716](https://github.com/prefix-dev/pixi/pull/716) - Support adding dependencies for project's unsupported platforms by @orhun in [#668](https://github.com/prefix-dev/pixi/pull/668) - Add `pixi list` command by @hadim in [#665](https://github.com/prefix-dev/pixi/pull/665) - Add `pixi shell-hook` command by @orhun in [#672](https://github.com/prefix-dev/pixi/pull/672)[#679](https://github.com/prefix-dev/pixi/pull/679) [#684](https://github.com/prefix-dev/pixi/pull/684) - Use env variable to configure locked, frozen and color by @hadim in [#726](https://github.com/prefix-dev/pixi/pull/726) - `pixi self-update` by @hadim in [#675](https://github.com/prefix-dev/pixi/pull/675) - Add `PIXI_NO_PATH_UPDATE` for PATH update suppression by @chawyehsu in [#692](https://github.com/prefix-dev/pixi/pull/692) - Set the cache directory by @ruben-arts in [#683](https://github.com/prefix-dev/pixi/pull/683) #### Changed - Use consistent naming for tests module by @orhun in [#678](https://github.com/prefix-dev/pixi/pull/678) - Install pixi and add to the path in docker example by @ruben-arts in [#743](https://github.com/prefix-dev/pixi/pull/743) - Simplify the deserializer of `PyPiRequirement` by @orhun in [#744](https://github.com/prefix-dev/pixi/pull/744) - Use `tabwriter` instead of `comfy_table` by @baszalmstra in [#745](https://github.com/prefix-dev/pixi/pull/745) - Document environment variables by @ruben-arts in [#746](https://github.com/prefix-dev/pixi/pull/746) #### Fixed - Quote part of the task that has brackets (`[ or ]`) by @JafarAbdi in [#677](https://github.com/prefix-dev/pixi/pull/677) - Package clobber and `__pycache__` removal issues by @wolfv in [#573](https://github.com/prefix-dev/pixi/pull/573) - Non-global reqwest client by @tdejager in [#693](https://github.com/prefix-dev/pixi/pull/693) - Fix broken pipe error during search by @orhun in [#699](https://github.com/prefix-dev/pixi/pull/699) - Make `pixi search` result correct by @chawyehsu in [#713](https://github.com/prefix-dev/pixi/pull/713) - Allow the tasks for all platforms to be shown in `pixi info` by @ruben-arts in [#728](https://github.com/prefix-dev/pixi/pull/728) - Flaky tests while installing pypi dependencies by @baszalmstra in [#732](https://github.com/prefix-dev/pixi/pull/732) - Linux install script by @mariusvniekerk in [#737](https://github.com/prefix-dev/pixi/pull/737) - Download wheels in parallel to avoid deadlock by @baszalmstra in [#752](https://github.com/prefix-dev/pixi/pull/752) #### New Contributors - @JafarAbdi made their first contribution in [#677](https://github.com/prefix-dev/pixi/pull/677) - @mariusvniekerk made their first contribution in [#737](https://github.com/prefix-dev/pixi/pull/737) [Full commit history](https://github.com/prefix-dev/pixi/compare/v0.12.0..v0.13.0) ### [0.12.0] - 2024-01-15 #### ✨ Highlights - Some great community contributions, `pixi global upgrade`, `pixi project version` commands, a `PIXI_HOME` variable. - A ton of refactor work to prepare for the [multi-environment](https://pixi.sh/design_proposals/multi_environment_proposal/) feature. - Note that there are no extra environments created yet, but you can just specify them in the `pixi.toml` file already. - Next we'll build the actual environments. #### Added - Add `global upgrade` command to pixi by @trueleo in [#614](https://github.com/prefix-dev/pixi/pull/614) - Add configurable `PIXI_HOME` by @chawyehsu in [#627](https://github.com/prefix-dev/pixi/pull/627) - Add `--pypi` option to `pixi remove` by @marcelotrevisani in https://github.com/prefix-dev/pixi/pull/602 - PrioritizedChannels to specify channel priority by @ruben-arts in https://github.com/prefix-dev/pixi/pull/658 - Add `project version {major,minor,patch}` CLIs by @hadim in https://github.com/prefix-dev/pixi/pull/633 #### Changed - Refactored project model using targets, features and environments by @baszalmstra in https://github.com/prefix-dev/pixi/pull/616 - Move code from `Project` to `Environment` by @baszalmstra in [#630](https://github.com/prefix-dev/pixi/pull/630) - Refactored `system-requirements` from Environment by @baszalmstra in [#632](https://github.com/prefix-dev/pixi/pull/632) - Extract `activation.scripts` into Environment by @baszalmstra in [#659](https://github.com/prefix-dev/pixi/pull/659) - Extract `pypi-dependencies` from Environment by @baszalmstra in https://github.com/prefix-dev/pixi/pull/656 - De-serialization of `features` and `environments` by @ruben-arts in https://github.com/prefix-dev/pixi/pull/636 #### Fixed - Make install.sh also work with wget if curl is not available by @wolfv in [#644](https://github.com/prefix-dev/pixi/pull/644) - Use source build for rattler by @ruben-arts - Check for pypi-dependencies before amending the pypi purls by @ruben-arts in [#661](https://github.com/prefix-dev/pixi/pull/661) - Don't allow the use of reflinks by @ruben-arts in [#662](https://github.com/prefix-dev/pixi/pull/662) #### Removed - Remove windows and unix system requirements by @baszalmstra in [#635](https://github.com/prefix-dev/pixi/pull/635) #### Documentation - Document the channel logic by @ruben-arts in https://github.com/prefix-dev/pixi/pull/610 - Update the instructions for installing on Arch Linux by @orhun in https://github.com/prefix-dev/pixi/pull/653 - Update Community.md by @KarelZe in https://github.com/prefix-dev/pixi/pull/654 - Replace contributions.md with contributing.md and make it more standardized by @ruben-arts in https://github.com/prefix-dev/pixi/pull/649 - Remove `windows` and `unix` system requirements by @baszalmstra in https://github.com/prefix-dev/pixi/pull/635 - Add `CODE_OF_CONDUCT.md` by @ruben-arts in https://github.com/prefix-dev/pixi/pull/648 - Removed remaining .ps1 references by @bahugo in https://github.com/prefix-dev/pixi/pull/643 #### New Contributors - @marcelotrevisani made their first contribution in https://github.com/prefix-dev/pixi/pull/602 - @trueleo made their first contribution in https://github.com/prefix-dev/pixi/pull/614 - @bahugo made their first contribution in https://github.com/prefix-dev/pixi/pull/643 - @KarelZe made their first contribution in https://github.com/prefix-dev/pixi/pull/654 **Full Changelog**: https://github.com/prefix-dev/pixi/compare/v0.11.0...v0.12.0 ### [0.11.1] - 2024-01-06 #### Fixed - Upgrading rattler to fix `pixi auth` in [#642](https://github.com/prefix-dev/pixi/pull/642) ### [0.11.0] - 2024-01-05 #### ✨ Highlights - Lots of important and preparations for the pypi `sdist` and multi environment feature - Lots of new contributors that help `pixi` improve! #### Added - Add new commands for `pixi project {version|channel|platform|description}` by @hadim in [#579](https://github.com/prefix-dev/pixi/pull/579) - Add dependabot.yml by @pavelzw in [#606](https://github.com/prefix-dev/pixi/pull/606) #### Changed - `winget-releaser` gets correct identifier by @ruben-arts in [#561](https://github.com/prefix-dev/pixi/pull/561) - Task run code by @baszalmstra in [#556](https://github.com/prefix-dev/pixi/pull/556) - No ps1 in activation scripts by @ruben-arts in [#563](https://github.com/prefix-dev/pixi/pull/563) - Changed some names for clarity by @tdejager in [#568](https://github.com/prefix-dev/pixi/pull/568) - Change font and make it dark mode by @ruben-arts in [#576](https://github.com/prefix-dev/pixi/pull/576) - Moved pypi installation into its own module by @tdejager in [#589](https://github.com/prefix-dev/pixi/pull/589) - Move alpha to beta feature and toggle it off with env var by @ruben-arts in [#604](https://github.com/prefix-dev/pixi/pull/604) - Improve UX activation scripts by @ruben-arts in [#560](https://github.com/prefix-dev/pixi/pull/560) - Add sanity check by @tdejager in [#569](https://github.com/prefix-dev/pixi/pull/569) - Refactor manifest by @ruben-arts in [#572](https://github.com/prefix-dev/pixi/pull/572) - Improve search by @Johnwillliam in [#578](https://github.com/prefix-dev/pixi/pull/578) - Split pypi and conda solve steps by @tdejager in [#601](https://github.com/prefix-dev/pixi/pull/601) #### Fixed - Save file after lockfile is correctly updated by @ruben-arts in [#555](https://github.com/prefix-dev/pixi/pull/555) - Limit the number of concurrent solves by @baszalmstra in [#571](https://github.com/prefix-dev/pixi/pull/571) - Use project virtual packages in add command by @msegado in [#609](https://github.com/prefix-dev/pixi/pull/609) - Improved mapped dependency by @ruben-arts in [#574](https://github.com/prefix-dev/pixi/pull/574) #### Documentation - Change font and make it dark mode by @ruben-arts in [#576](https://github.com/prefix-dev/pixi/pull/576) - typo: no ps1 in activation scripts by @ruben-arts in [#563](https://github.com/prefix-dev/pixi/pull/563) - Document adding CUDA to `system-requirements` by @ruben-arts in [#595](https://github.com/prefix-dev/pixi/pull/595) - Multi env proposal documentation by @ruben-arts in [#584](https://github.com/prefix-dev/pixi/pull/584) - Fix multiple typos in configuration.md by @SeaOtocinclus in [#608](https://github.com/prefix-dev/pixi/pull/608) - Add multiple machines from one project example by @pavelzw in [#605](https://github.com/prefix-dev/pixi/pull/605) #### New Contributors - @hadim made their first contribution in [#579](https://github.com/prefix-dev/pixi/pull/579) - @msegado made their first contribution in [#609](https://github.com/prefix-dev/pixi/pull/609) - @Johnwillliam made their first contribution in [#578](https://github.com/prefix-dev/pixi/pull/578) - @SeaOtocinclus made their first contribution in [#608](https://github.com/prefix-dev/pixi/pull/608) **Full Changelog**: https://github.com/prefix-dev/pixi/compare/v0.10.0...v0.11.0 ### [0.10.0] - 2023-12-8 #### Highlights - Better `pypi-dependencies` support, now install even more of the pypi packages. - `pixi add --pypi` command to add a pypi package to your project. #### Added - Use range (`>=1.2.3, <1.3`) when adding requirement, instead of `1.2.3.*` by @baszalmstra in https://github.com/prefix-dev/pixi/pull/536 - Update `rip` to fix by @tdejager in https://github.com/prefix-dev/pixi/pull/543 - Better Bytecode compilation (`.pyc`) support by @baszalmstra - Recognize `.data` directory `headers` by @baszalmstra - Also print arguments given to a pixi task by @ruben-arts in https://github.com/prefix-dev/pixi/pull/545 - Add `pixi add --pypi` command by @ruben-arts in https://github.com/prefix-dev/pixi/pull/539 #### Fixed - space in global install path by @ruben-arts in https://github.com/prefix-dev/pixi/pull/513 - Glibc version/family parsing by @baszalmstra in https://github.com/prefix-dev/pixi/pull/535 - Use `build` and `host` specs while getting the best version by @ruben-arts in https://github.com/prefix-dev/pixi/pull/538 #### Miscellaneous - docs: add update manual by @ruben-arts in https://github.com/prefix-dev/pixi/pull/521 - add lightgbm demo by @partrita in https://github.com/prefix-dev/pixi/pull/492 - Update documentation link by @williamjamir in https://github.com/prefix-dev/pixi/pull/525 - Update Community.md by @jiaxiyang in https://github.com/prefix-dev/pixi/pull/527 - Add `winget` releaser by @ruben-arts in https://github.com/prefix-dev/pixi/pull/547 - Custom `rerun-sdk` example, force driven graph of `pixi.lock` by @ruben-arts in https://github.com/prefix-dev/pixi/pull/548 - Better document pypi part by @ruben-arts in https://github.com/prefix-dev/pixi/pull/546 #### New Contributors - @partrita made their first contribution in https://github.com/prefix-dev/pixi/pull/492 - @williamjamir made their first contribution in https://github.com/prefix-dev/pixi/pull/525 - @jiaxiyang made their first contribution in https://github.com/prefix-dev/pixi/pull/527 **Full Changelog**: https://github.com/prefix-dev/pixi/compare/v0.9.1...v0.10.0 ### [0.9.1] - 2023-11-29 #### Highlights - PyPI's `scripts` are now fixed. For example: https://github.com/prefix-dev/pixi/issues/516 #### Fixed - Remove attr (unused) and update all dependencies by @wolfv in https://github.com/prefix-dev/pixi/pull/510 - Remove empty folders on python uninstall by @baszalmstra in https://github.com/prefix-dev/pixi/pull/512 - Bump `rip` to add scripts by @baszalmstra in https://github.com/prefix-dev/pixi/pull/517 **Full Changelog**: https://github.com/prefix-dev/pixi/compare/v0.9.0...v0.9.1 ### [0.9.0] - 2023-11-28 #### Highlights - You can now run `pixi remove`, `pixi rm` to remove a package from the environment - Fix `pip install -e` issue that was created by release `v0.8.0` : https://github.com/prefix-dev/pixi/issues/507 #### Added - `pixi remove` command by @Wackyator in https://github.com/prefix-dev/pixi/pull/483 #### Fixed - Install entrypoints for `[pypi-dependencies]` @baszalmstra in https://github.com/prefix-dev/pixi/pull/508 - Only uninstall pixi installed packages by @baszalmstra in https://github.com/prefix-dev/pixi/pull/509 **Full Changelog**: https://github.com/prefix-dev/pixi/compare/v0.8.0...v0.9.0 ### [0.8.0] - 2023-11-27 #### Highlights - πŸŽ‰πŸ`[pypi-dependencies]` ALPHA RELEASEπŸπŸŽ‰, you can now add PyPI dependencies to your pixi project. - UX of `pixi run` has been improved with better errors and showing what task is run. > [!NOTE] `[pypi-dependencies]` support is still incomplete, missing functionality is listed here: https://github.com/orgs/prefix-dev/projects/6. Our intent is not to have 100% feature parity with `pip`, our goal is that you only need `pixi` for both conda and pypi packages alike. #### Added - Bump `rattler` @ruben-arts in https://github.com/prefix-dev/pixi/pull/496 - Implement lock-file satisfiability with `pypi-dependencies` by @baszalmstra in https://github.com/prefix-dev/pixi/pull/494 - List pixi tasks when `command not found` is returned by @ruben-arts in https://github.com/prefix-dev/pixi/pull/488 - Show which command is run as a pixi task by @ruben-arts in https://github.com/prefix-dev/pixi/pull/491 && https://github.com/prefix-dev/pixi/pull/493 - Add progress info to conda install by @baszalmstra in https://github.com/prefix-dev/pixi/pull/470 - Install pypi dependencies (alpha) by @baszalmstra in https://github.com/prefix-dev/pixi/pull/452 #### Fixed - Add install scripts to `pixi.sh` by @ruben-arts in https://github.com/prefix-dev/pixi/pull/458 && https://github.com/prefix-dev/pixi/pull/459 && https://github.com/prefix-dev/pixi/pull/460 - Fix `RECORD not found` issue by @baszalmstra in https://github.com/prefix-dev/pixi/pull/495 - Actually add to the `.gitignore` and give better errors by @ruben-arts in https://github.com/prefix-dev/pixi/pull/490 - Support macOS for `pypi-dependencies` by @baszalmstra in https://github.com/prefix-dev/pixi/pull/478 - Custom `pypi-dependencies` type by @ruben-arts in https://github.com/prefix-dev/pixi/pull/471 - `pypi-dependencies` parsing errors by @ruben-arts in https://github.com/prefix-dev/pixi/pull/479 - Progress issues by @baszalmstra in https://github.com/prefix-dev/pixi/pull/4 #### Miscellaneous - Example: `ctypes` by @liquidcarbon in https://github.com/prefix-dev/pixi/pull/441 - Mention the AUR package by @orhun in https://github.com/prefix-dev/pixi/pull/464 - Update `rerun` example by @ruben-arts in https://github.com/prefix-dev/pixi/pull/489 - Document `pypi-dependencies` by @ruben-arts in https://github.com/prefix-dev/pixi/pull/481 - Ignore docs paths on rust workflow by @ruben-arts in https://github.com/prefix-dev/pixi/pull/482 - Fix flaky tests, run serially by @baszalmstra in https://github.com/prefix-dev/pixi/pull/477 #### New Contributors - @liquidcarbon made their first contribution in https://github.com/prefix-dev/pixi/pull/441 - @orhun made their first contribution in https://github.com/prefix-dev/pixi/pull/464 **Full Changelog**: https://github.com/prefix-dev/pixi/compare/v0.7.0...v0.8.0 ### [0.7.0] - 2023-11-14 #### Highlights - Channel priority: `channels = ["conda-forge", "pytorch"]` All packages found in conda-forge will not be taken from pytorch. - Channel specific dependencies: `pytorch = { version="*", channel="pytorch"}` - Autocompletion on `pixi run ` - Moved all pixi documentation into this repo, try it with `pixi run docs`! - Lots of new contributors! #### Added - Bump rattler to its newest version by @ruben-arts in https://github.com/prefix-dev/pixi/pull/395 * Some notable changes: * Add channel priority (If a package is found in the first listed channel it will not be looked for in the other channels). * Fix JLAP using wrong hash. * Lockfile forward compatibility error. - Add nushell support by @wolfv in https://github.com/prefix-dev/pixi/pull/360 - Autocomplete tasks on `pixi run` for `bash` and `zsh` by @ruben-arts in https://github.com/prefix-dev/pixi/pull/390 - Add prefix location file to avoid copy error by @ruben-arts in https://github.com/prefix-dev/pixi/pull/422 - Channel specific dependencies `python = { version = "*" channel="conda-forge" }` by @ruben-arts in https://github.com/prefix-dev/pixi/pull/439 #### Changed - `project.version` as optional field in the `pixi.toml` by @ruben-arts in https://github.com/prefix-dev/pixi/pull/400 #### Fixed - Deny unknown fields in `pixi.toml` to help users find errors by @ruben-arts in https://github.com/prefix-dev/pixi/pull/396 - `install.sh` to create dot file if not present by @humphd in https://github.com/prefix-dev/pixi/pull/408 - Ensure order of repodata fetches by @baszalmstra in https://github.com/prefix-dev/pixi/pull/405 - Strip Linux binaries by @baszalmstra in https://github.com/prefix-dev/pixi/pull/414 - Sort `task list` by @ruben-arts in https://github.com/prefix-dev/pixi/pull/431 - Fix `global install` path on windows by @ruben-arts in https://github.com/prefix-dev/pixi/pull/449 - Let `PIXI_BIN_PATH` use backslashes by @Hofer-Julian in https://github.com/prefix-dev/pixi/pull/442 - Print more informative error if created file is empty by @traversaro in https://github.com/prefix-dev/pixi/pull/447 #### Docs - Move to `mkdocs` with all documentation by @ruben-arts in https://github.com/prefix-dev/pixi/pull/435 - Fix typing errors by @FarukhS52 in https://github.com/prefix-dev/pixi/pull/426 - Add social cards to the pages by @ruben-arts in https://github.com/prefix-dev/pixi/pull/445 - Enhance README.md: Added Table of Contents, Grammar Improvements by @adarsh-jha-dev in https://github.com/prefix-dev/pixi/pull/421 - Adding conda-auth to community examples by @travishathaway in https://github.com/prefix-dev/pixi/pull/433 - Minor grammar correction by @tylere in https://github.com/prefix-dev/pixi/pull/406 - Make capitalization of tab titles consistent by @tylere in https://github.com/prefix-dev/pixi/pull/407 #### New Contributors - @tylere made their first contribution in https://github.com/prefix-dev/pixi/pull/406 - @humphd made their first contribution in https://github.com/prefix-dev/pixi/pull/408 - @adarsh-jha-dev made their first contribution in https://github.com/prefix-dev/pixi/pull/421 - @FarukhS52 made their first contribution in https://github.com/prefix-dev/pixi/pull/426 - @travishathaway made their first contribution in https://github.com/prefix-dev/pixi/pull/433 - @traversaro made their first contribution in https://github.com/prefix-dev/pixi/pull/447 **Full Changelog**: https://github.com/prefix-dev/pixi/compare/v0.6.0...v0.7.0 ### [0.6.0] - 2023-10-17 #### Highlights This release fixes some bugs and adds the `--cwd` option to the tasks. #### Fixed - Improve shell prompts by @ruben-arts in https://github.com/prefix-dev/pixi/pull/385 https://github.com/prefix-dev/pixi/pull/388 - Change `--frozen` logic to error when there is no lockfile by @ruben-arts in https://github.com/prefix-dev/pixi/pull/373 - Don't remove the '.11' from 'python3.11' binary file name by @ruben-arts in https://github.com/prefix-dev/pixi/pull/366 #### Changed - Update `rerun` example to v0.9.1 by @ruben-arts in https://github.com/prefix-dev/pixi/pull/389 #### Added - Add the current working directory (`--cwd`) in `pixi tasks` by @ruben-arts in https://github.com/prefix-dev/pixi/pull/380 **Full Changelog**: https://github.com/prefix-dev/pixi/compare/v0.5.0...v0.6.0 ### [0.5.0] - 2023-10-03 #### Highlights We rebuilt `pixi shell`, fixing the fact that your `rc` file would overrule the environment activation. #### Fixed - Change how `shell` works and make activation more robust by @wolfv in https://github.com/prefix-dev/pixi/pull/316 - Documentation: use quotes in cli by @pavelzw in https://github.com/prefix-dev/pixi/pull/367 #### Added - Create or append to the `.gitignore` and `.gitattributes` files by @ruben-arts in https://github.com/prefix-dev/pixi/pull/359 - Add `--locked` and `--frozen` to getting an up-to-date prefix by @ruben-arts in https://github.com/prefix-dev/pixi/pull/363 - Documentation: improvement/update by @ruben-arts in https://github.com/prefix-dev/pixi/pull/355 - Example: how to build a docker image using `pixi` by @ruben-arts in https://github.com/prefix-dev/pixi/pull/353 & https://github.com/prefix-dev/pixi/pull/365 - Update to the newest rattler by @baszalmstra in https://github.com/prefix-dev/pixi/pull/361 - Periodic `cargo upgrade --all --incompatible` by @wolfv in https://github.com/prefix-dev/pixi/pull/358 **Full Changelog**: https://github.com/prefix-dev/pixi/compare/v0.4.0...v0.5.0 ### [0.4.0] - 2023-09-22 #### Highlights This release adds the start of a new cli command `pixi project` which will allow users to interact with the project configuration from the command line. #### Fixed - Align with latest rattler version `0.9.0` by @ruben-arts in https://github.com/prefix-dev/pixi/pull/350 #### Added - Add codespell (config, workflow) to catch typos + catch and fix some of those by @yarikoptic in https://github.com/prefix-dev/pixi/pull/329 - remove atty and use stdlib by @wolfv in https://github.com/prefix-dev/pixi/pull/337 - `xtsci-dist` to Community.md by @HaoZeke in https://github.com/prefix-dev/pixi/pull/339 - `ribasim` to Community.md by @Hofer-Julian in https://github.com/prefix-dev/pixi/pull/340 - `LFortran` to Community.md by @wolfv in https://github.com/prefix-dev/pixi/pull/341 - Give tip to resolve virtual package issue by @ruben-arts in https://github.com/prefix-dev/pixi/pull/348 - `pixi project channel add` subcommand by @baszalmstra and @ruben-arts in https://github.com/prefix-dev/pixi/pull/347 #### New Contributors - @yarikoptic made their first contribution in https://github.com/prefix-dev/pixi/pull/329 - @HaoZeke made their first contribution in https://github.com/prefix-dev/pixi/pull/339 **Full Changelog**: https://github.com/prefix-dev/pixi/compare/v0.3.0...v0.4.0 ### [0.3.0] - 2023-09-11 #### Highlights This releases fixes a lot of issues encountered by the community as well as some awesome community contributions like the addition of `pixi global list` and `pixi global remove`. #### Fixed - Properly detect Cuda on linux using our build binaries, by @baszalmstra ([#290](https://github.com/mamba-org/rattler/pull/290)) - Package names are now case-insensitive, by @baszalmstra ([#285](https://github.com/mamba-org/rattler/pull/285)) - Issue with starts-with and compatibility operator, by @tdejager ([#296](https://github.com/mamba-org/rattler/pull/296)) - Lock files are now consistently sorted, by @baszalmstra ([#295](https://github.com/mamba-org/rattler/pull/295) & [#307](https://github.com/prefix-dev/pixi/pull/307)) - Improved xonsh detection and powershell env-var escaping, by @wolfv ([#307](https://github.com/mamba-org/rattler/pull/307)) - `system-requirements` are properly filtered by platform, by @ruben-arts ([#299](https://github.com/prefix-dev/pixi/pull/299)) - Powershell completion install script, by @chawyehsu ([#325](https://github.com/prefix-dev/pixi/pull/325)) - Simplified and improved shell quoting, by @baszalmstra ([#313](https://github.com/prefix-dev/pixi/pull/313)) - Issue where platform specific subdirs were required, by @baszalmstra ([#333](https://github.com/prefix-dev/pixi/pull/333)) - `thread 'tokio-runtime-worker' has overflowed its stack` issue, by @baszalmstra ([#28](https://github.com/idubrov/json-patch/pull/28)) #### Added - Certificates from the OS certificate store are now used, by @baszalmstra ([#310](https://github.com/prefix-dev/pixi/pull/310)) - `pixi global list` and `pixi global remove` commands, by @cjfuller ([#318](https://github.com/prefix-dev/pixi/pull/318)) #### Changed - `--manifest-path` must point to a `pixi.toml` file, by @baszalmstra ([#324](https://github.com/prefix-dev/pixi/pull/324)) ### [0.2.0] - 2023-08-22 #### Highlights - Added `pixi search` command to search for packages, by @Wackyator. ([#244](https://github.com/prefix-dev/pixi/pull/244)) - Added target specific tasks, eg. `[target.win-64.tasks]`, by @ruben-arts. ([#269](https://github.com/prefix-dev/pixi/pull/269)) - Flaky install caused by the download of packages, by @baszalmstra. ([#281](https://github.com/prefix-dev/pixi/pull/281)) #### Fixed - Install instructions, by @baszalmstra. ([#258](https://github.com/prefix-dev/pixi/pull/258)) - Typo in getting started, by @RaulPL. ([#266](https://github.com/prefix-dev/pixi/pull/266)) - Don't execute alias tasks, by @baszalmstra. ([#274](https://github.com/prefix-dev/pixi/pull/274)) #### Added - Rerun example, by @ruben-arts. ([#236](https://github.com/prefix-dev/pixi/pull/236)) - Reduction of pixi's binary size, by @baszalmstra ([#256](https://github.com/prefix-dev/pixi/pull/256)) - Updated pixi banner, including webp file for faster loading, by @baszalmstra. ([#257](https://github.com/prefix-dev/pixi/pull/257)) - Set linguist attributes for `pixi.lock` automatically, by @spenserblack. ([#265](https://github.com/prefix-dev/pixi/pull/265)) - Contribution manual for pixi, by @ruben-arts. ([#268](https://github.com/prefix-dev/pixi/pull/268)) - GitHub issue templates, by @ruben-arts. ([#271](https://github.com/prefix-dev/pixi/pull/271)) - Links to prefix.dev in readme, by @tdejager. ([#279](https://github.com/prefix-dev/pixi/pull/279)) ### [0.1.0] - 2023-08-11 As this is our first [Semantic Versioning](https://semver.org) release, we'll change from the prototype to the developing phase, as semver describes. A 0.x release could be anything from a new major feature to a breaking change where the 0.0.x releases will be bugfixes or small improvements. #### Highlights - Update to the latest [rattler](https://github.com/mamba-org/rattler/releases/tag/v0.7.0) version, by @baszalmstra. ([#249](https://github.com/prefix-dev/pixi/pull/249)) #### Fixed - Only add shebang to activation scripts on `unix` platforms, by @baszalmstra. ([#250](https://github.com/prefix-dev/pixi/pull/250)) - Use official crates.io releases for all dependencies, by @baszalmstra. ([#252](https://github.com/prefix-dev/pixi/pull/252)) ### [0.0.8] - 2023-08-01 #### Highlights - Much better error printing using `miette`, by @baszalmstra. ([#211](https://github.com/prefix-dev/pixi/pull/211)) - You can now use pixi on `aarch64-linux`, by @pavelzw. ([#233](https://github.com/prefix-dev/pixi/pull/233)) - Use the Rust port of `libsolv` as the default solver, by @ruben-arts. ([#209](https://github.com/prefix-dev/pixi/pull/209)) #### Added - Add mention to `condax` in the docs, by @maresb. ([#207](https://github.com/prefix-dev/pixi/pull/207)) - Add `brew` installation instructions, by @wolfv. ([#208](https://github.com/prefix-dev/pixi/pull/208)) - Add `activation.scripts` to the `pixi.toml` to configure environment activation, by @ruben-arts. ([#217](https://github.com/prefix-dev/pixi/pull/217)) - Add `pixi upload` command to upload packages to `prefix.dev`, by @wolfv. ([#127](https://github.com/prefix-dev/pixi/pull/127)) - Add more metadata fields to the `pixi.toml`, by @wolfv. ([#218](https://github.com/prefix-dev/pixi/pull/218)) - Add `pixi task list` to show all tasks in the project, by @tdejager. ([#228](https://github.com/prefix-dev/pixi/pull/228)) - Add `--color` to configure the colors in the output, by @baszalmstra. ([#243](https://github.com/prefix-dev/pixi/pull/243)) - Examples, [ROS2 Nav2](https://github.com/prefix-dev/pixi/tree/main/examples/ros2-nav2), [JupyterLab](https://github.com/prefix-dev/pixi/tree/main/examples/jupyterlab) and [QGIS](https://github.com/prefix-dev/pixi/tree/main/examples/qgis), by @ruben-arts. #### Fixed - Add trailing newline to `pixi.toml` and `.gitignore`, by @pavelzw. ([#216](https://github.com/prefix-dev/pixi/pull/216)) - Deny unknown fields and rename license-file in `pixi.toml`, by @wolfv. ([#220](https://github.com/prefix-dev/pixi/pull/220)) - Overwrite `PS1` variable when going into a `pixi shell`, by @ruben-arts. ([#201](https://github.com/prefix-dev/pixi/pull/201)) #### Changed - Install environment when adding a dependency using `pixi add`, by @baszalmstra. ([#213](https://github.com/prefix-dev/pixi/pull/213)) - Improve and speedup CI, by @baszalmstra. ([#241](https://github.com/prefix-dev/pixi/pull/241)) ### [0.0.7] - 2023-07-11 #### Highlights - Transitioned the `run` subcommand to use the `deno_task_shell` for improved cross-platform functionality. More details in the [Deno Task Runner documentation](https://deno.land/manual@v1.35.0/tools/task_runner#task-runner). - Added an `info` subcommand to retrieve system-specific information understood by `pixi`. #### BREAKING CHANGES - `[commands]` in the `pixi.toml` is now called `[tasks]`. ([#177](https://github.com/prefix-dev/pixi/pull/177)) #### Added - The `pixi info` command to get more system information by @wolfv in ([#158](https://github.com/prefix-dev/pixi/pull/158)) - Documentation on how to use the cli by @ruben-arts in ([#160](https://github.com/prefix-dev/pixi/pull/160)) - Use the `deno_task_shell` to execute commands in `pixi run` by @baszalmstra in ([#173](https://github.com/prefix-dev/pixi/pull/173)) - Use new solver backend from rattler by @baszalmstra in ([#178](https://github.com/prefix-dev/pixi/pull/178)) - The `pixi command` command to the cli by @tdejager in ([#177](https://github.com/prefix-dev/pixi/pull/177)) - Documentation on how to use the `pixi auth` command by @wolfv in ([#183](https://github.com/prefix-dev/pixi/pull/183)) - Use the newest rattler 0.6.0 by @baszalmstra in ([#185](https://github.com/prefix-dev/pixi/pull/185)) - Build with pixi section to the documentation by @tdejager in ([#196](https://github.com/prefix-dev/pixi/pull/196)) #### Fixed - Running tasks sequentially when using `depends_on` by @tdejager in ([#161](https://github.com/prefix-dev/pixi/pull/161)) - Don't add `PATH` variable where it is already set by @baszalmstra in ([#169](https://github.com/prefix-dev/pixi/pull/169)) - Fix README by @Hofer-Julian in ([#182](https://github.com/prefix-dev/pixi/pull/182)) - Fix Ctrl+C signal in `pixi run` by @tdejager in ([#190](https://github.com/prefix-dev/pixi/pull/190)) - Add the correct license information to the lockfiles by @wolfv in ([#191](https://github.com/prefix-dev/pixi/pull/191)) ### [0.0.6] - 2023-06-30 #### Highlights Improving the reliability is important to us, so we added an integration testing framework, we can now test as close as possible to the CLI level using `cargo`. #### Added - An integration test harness, to test as close as possible to the user experience but in rust. ([#138](https://github.com/prefix-dev/pixi/pull/138), [#140](https://github.com/prefix-dev/pixi/pull/140), [#156](https://github.com/prefix-dev/pixi/pull/156)) - Add different levels of dependencies in preparation for `pixi build`, allowing `host-` and `build-` `dependencies` ([#149](https://github.com/prefix-dev/pixi/pull/149)) #### Fixed - Use correct folder name on pixi init ([#144](https://github.com/prefix-dev/pixi/pull/144)) - Fix windows cli installer ([#152](https://github.com/prefix-dev/pixi/pull/152)) - Fix global install path variable ([#147](https://github.com/prefix-dev/pixi/pull/147)) - Fix macOS binary notarization ([#153](https://github.com/prefix-dev/pixi/pull/153)) ### [0.0.5] - 2023-06-26 Fixing Windows installer build in CI. ([#145](https://github.com/prefix-dev/pixi/pull/145)) ### [0.0.4] - 2023-06-26 #### Highlights A new command, `auth` which can be used to authenticate the host of the package channels. A new command, `shell` which can be used to start a shell in the pixi environment of a project. A refactor of the `install` command which is changed to `global install` and the `install` command now installs a pixi project if you run it in the directory. Platform specific dependencies using `[target.linux-64.dependencies]` instead of `[dependencies]` in the `pixi.toml` Lots and lots of fixes and improvements to make it easier for this user, where bumping to the new version of [`rattler`](https://github.com/mamba-org/rattler/releases/tag/v0.4.0) helped a lot. #### Added - Platform specific dependencies and helpful error reporting on `pixi.toml` issues([#111](https://github.com/prefix-dev/pixi/pull/111)) - Windows installer, which is very useful for users that want to start using pixi on windows. ([#114](https://github.com/prefix-dev/pixi/pull/114)) - `shell` command to use the pixi environment without `pixi run`. ([#116](https://github.com/prefix-dev/pixi/pull/116)) - Verbosity options using `-v, -vv, -vvv` ([#118](https://github.com/prefix-dev/pixi/pull/118)) - `auth` command to be able to login or logout of a host like `repo.prefix.dev` if you're using private channels. ([#120](https://github.com/prefix-dev/pixi/pull/120)) - New examples: CPP sdl: [#121](https://github.com/prefix-dev/pixi/pull/121), Opencv camera calibration [#125](https://github.com/prefix-dev/pixi/pull/125) - Apple binary signing and notarization. ([#137](https://github.com/prefix-dev/pixi/pull/137)) #### Changed - `pixi install` moved to `pixi global install` and `pixi install` became the installation of a project using the `pixi.toml` ([#124](https://github.com/prefix-dev/pixi/pull/124)) #### Fixed - `pixi run` uses default shell ([#119](https://github.com/prefix-dev/pixi/pull/119)) - `pixi add` command is fixed. ([#132](https://github.com/prefix-dev/pixi/pull/132)) - Community issues fixed: [#70](https://github.com/prefix-dev/pixi/issues/70), [#72](https://github.com/prefix-dev/pixi/issues/72), [#90](https://github.com/prefix-dev/pixi/issues/90), [#92](https://github.com/prefix-dev/pixi/issues/92), [#94](https://github.com/prefix-dev/pixi/issues/94), [#96](https://github.com/prefix-dev/pixi/issues/96) When you want to show your users and contributors that they can use Pixi in your repo, you can use the following badge: ```text [![Pixi Badge](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/prefix-dev/pixi/main/assets/badge/v0.json)](https://pixi.sh) ``` Customize your badge To further customize the look and feel of your badge, you can add `&style=` at the end of the URL. See [the documentation on shields.io](https://shields.io/badges/endpoint-badge) for more info. ## Built using Pixi - Deltares: - [Ribasim](https://github.com/Deltares/Ribasim): Water resources model - [Ribasim-NL](https://github.com/Deltares/Ribasim-NL): Ribasim water resources modeling in the Netherlands - [iMOD Python](https://github.com/Deltares/imod-python): Make massive MODFLOW models - [iMOD Coupler](https://github.com/Deltares/imod_coupler): Application for coupling hydrological kernels - [iMOD Documentation](https://github.com/Deltares/iMOD-Documentation): Documentation of the iMOD suite. - [Xugrid](https://github.com/Deltares/xugrid): Xarray and unstructured grids - [Numba celltree](https://github.com/Deltares/numba_celltree): Celltree data structure for searching for points, lines, boxes, and cells (convex polygons) in a two dimensional unstructured mesh. - [QGIS-Tim](https://github.com/Deltares/QGIS-Tim): QGIS plugin and utilities for TimML multi-layer analytic element model - [Pandamesh](https://github.com/Deltares/pandamesh): From geodataframe to mesh - [Wflow](https://github.com/Deltares/Wflow.jl): Hydrological modeling framework - [HydroMT](https://github.com/Deltares/hydromt): Automated and reproducible model building and analysis - [HydroMT SFINCS](https://github.com/Deltares/hydromt_sfincs): SFINCS plugin for HydroMT - [PyFlwDir](https://github.com/Deltares/pyflwdir): Fast methods to work with hydro- and topography data in pure Python. - USGS: - [MODFLOW 6](https://github.com/MODFLOW-USGS/modflow6): USGS modular hydrological model - QuantCo: - [glum](https://github.com/quantco/glum): High performance Python GLMs with all the features! - [tabmat](https://github.com/quantco/tabmat): Efficient matrix representations for working with tabular data - [pixi-pack](https://github.com/quantco/pixi-pack): A tool to pack and unpack conda environments created with pixi - [polarify](https://github.com/quantco/polarify): Simplifying conditional Polars Expressions with Python 🐍 πŸ»β€β„οΈ - [copier-template-python-open-source](https://github.com/quantco/copier-template-python-open-source): Copier template for python projects using pixi - [datajudge](https://github.com/quantco/datajudge): Assessing whether data from database complies with reference information - [ndonnx](https://github.com/quantco/ndonnx): ONNX-backed array library that is compliant with the Array API standard - [multiregex](https://github.com/quantco/multiregex): Quickly match many regexes against a string - [slim-trees](https://github.com/quantco/slim-trees): Pickle your ML models more efficiently for deployment πŸš€ - [sqlcompyre](https://github.com/quantco/sqlcompyre): Compare SQL tables and databases - [metalearners](https://github.com/quantco/metalearners): MetaLearners for CATE estimation - [tabulardelta](https://github.com/quantco/tabulardelta): Simplify table comparisons - [pydiverse.pipedag](https://github.com/pydiverse/pydiverse.pipedag): A library for data pipeline orchestration optimizing high development iteration speed - [pydiverse.transform](https://github.com/pydiverse/pydiverse.transform): Pipe based dataframe manipulation library that can also transform data on SQL databases - [pixi-pycharm](https://github.com/pavelzw/pixi-pycharm): Conda shim for PyCharm that proxies pixi - [pixi-diff-to-markdown](https://github.com/pavelzw/pixi-diff-to-markdown): Generate markdown summaries from Pixi update - [jiaxiyang/cpp_project_guideline](https://github.com/jiaxiyang/cpp_project_guideline): Guide the way beginners make their c++ projects. - [hex-inc/vegafusion](https://github.com/hex-inc/vegafusion): Serverside scaling of Vega and Altair visualizations in Rust, Python, WASM, and Java - [pablovela5620/arxiv-researcher](https://github.com/pablovela5620/arxiv-researcher): Summarize PDF's and Arixv papers with Langchain and Nougat πŸ¦‰ - [HaoZeke/xtsci-dist](https://github.com/HaoZeke/xtsci-dist): Incremental `scipy` port using `xtensor` - [jslorrma/keyrings.artifacts](https://github.com/jslorrma/keyrings.artifacts): Keyring backend that provides authentication for publishing or consuming Python packages to or from Azure Artifacts feeds within Azure DevOps - [LFortran](https://github.com/lfortran/lfortran): A modern cross-platform Fortran compiler - [Rerun](https://www.rerun.io/): Rerun is an SDK for building time aware visualizations of multimodal data. - [conda-auth](https://github.com/conda-incubator/conda-auth): a conda plugin providing more secure authentication support to conda. - [py-rattler](https://github.com/conda/rattler/tree/main/py-rattler): Build your own conda environment manager using the python wrapper of our Rattler backend. - [array-api-extra](https://github.com/data-apis/array-api-extra): Extra array functions built on top of the Python array API standard. - [marray](https://github.com/mdhaber/marray): Masked versions of Python array API standard compatible arrays. - [quantity-array](https://github.com/quantity-dev/quantity-array): Quantities with Python array API standard arrays. - [Bodo](https://github.com/bodo-ai/bodo): High-Performance Python Compute Engine for Data and AI. - [metrology-apis](https://github.com/quantity-dev/metrology-apis): Standardised Metrology APIs in Python. - [xsf](https://github.com/scipy/xsf): Special function implementations. - [pyfixest](https://github.com/py-econometrics/pyfixest): Fast High-Dimensional Fixed Effects Regression in Python following fixest-syntax. - [geovista](https://github.com/bjlittle/geovista): Cartographic rendering and mesh analytics powered by [PyVista](https://github.com/pyvista/pyvista) 🌍 - [SciPy](https://github.com/scipy/scipy): Fundamental algorithms for scientific computing in Python. - [Snakedown](https://github.com/savente93/snakedown) A fast and intuitive python API reference generator so you can host your docs with your favourite static site generator. - [Parcels](https://github.com/Parcels-code/parcels): A customisable Lagrangian simulation framework. - [Xarray](https://github.com/pydata/xarray): N-D labeled arrays and datasets in Python. ## What is the difference with `conda`, `mamba`, `poetry`, `pip` | Tool | Installs Python | Builds packages | Runs predefined tasks | Has lock files builtin | Fast | Use without python | | ------ | --------------- | --------------- | --------------------- | ---------------------- | ---- | ----------------------------------------------------------------------- | | Conda | βœ… | ❌ | ❌ | ❌ | ❌ | ❌ | | Mamba | βœ… | ❌ | ❌ | ❌ | βœ… | [βœ…](https://mamba.readthedocs.io/en/latest/user_guide/micromamba.html) | | Pip | ❌ | βœ… | ❌ | ❌ | ❌ | ❌ | | Pixi | βœ… | 🚧 | βœ… | βœ… | βœ… | βœ… | | Poetry | ❌ | βœ… | ❌ | βœ… | ❌ | ❌ | ## Why the name `pixi` Starting with the name `prefix` we iterated until we had a name that was easy to pronounce, spell and remember. There also wasn't a CLI tool yet using that name. Unlike `px`, `pex`, `pax`, etc. When in code mode we spell it like this `pixi`, otherwise we always start with an uppercase letter: Pixi. We think the name sparks curiosity and fun, if you don't agree, I'm sorry, but you can always alias it to whatever you like. ```shell alias not_pixi="pixi" ``` PowerShell: ```powershell New-Alias -Name not_pixi -Value pixi ``` ## Where is `pixi build` **TL;DR**: It's coming we promise! `pixi build` is going to be the subcommand that can generate a conda package out of a Pixi workspace. This requires a solid build tool which we're creating with [`rattler-build`](https://github.com/prefix-dev/rattler-build) which will be used as a library in pixi. This is a guide for distribution maintainers wanting to package Pixi for a different package manager. Users of Pixi can ignore this page. ## Building Pixi is written in Rust and compiled using Cargo, which are needed as compile-time dependencies. At runtime Pixi needs no dependencies in other than the runtime it was compiled against (`libc`, ...). To build Pixi run ```shell cargo build --locked --profile dist ``` Instead of using the predefined `dist` profile, which is optimized for binary size, you can also pass other options to let cargo optimize the binary for other metrics. ### Build-time Options Pixi provides some compile-time options, which can influence the build #### TLS By default, Pixi is built with Rustls TLS implementation. You can compile Pixi using the platform native TLS implementation using by adding `--no-default-features --feature native-tls` to the build command. Note that this might add additional runtime dependencies, such as OpenSSL on Linux. #### Self-Update Pixi has a self-update functionality. When Pixi is installed using another package manager one usually doesn't want pixi to try to update itself and instead let it be updated by the package manager. For this reason the self-update feature is disabled by default. It can be enabled by adding `--feature self_update` to the build command. When the self-update feature is disabled and a user tries to run `pixi self-update` an error message is displayed. This message can be customized by setting the `PIXI_SELF_UPDATE_DISABLED_MESSAGE` environment variable at build time to point the user to the package manager they should be using to update pixi. ```shell PIXI_SELF_UPDATE_DISABLED_MESSAGE="`self-update` has been disabled for this build. Run `brew upgrade pixi` instead" cargo build --locked --profile dist ``` #### Custom version You can specify a custom version string to be used in the `--version` output by setting the `PIXI_VERSION` environment variable during the build. ```shell PIXI_VERSION="HEAD-123456" cargo build --locked --profile dist ``` ## Shell completion After building Pixi you can generate shell autocompletion scripts by running ```shell pixi completion --shell ``` and saving the output to a file. Currently supported shells are `bash`, `elvish`, `fish`, `nushell`, `powershell` and `zsh`. We created `pixi` because we want to have a cargo/npm/yarn like package management experience for conda. We really love what the conda packaging ecosystem achieves, but we think that the user experience can be improved a lot. Modern package managers like `cargo` have shown us, how great a package manager can be. We want to bring that experience to the conda ecosystem. ## Pixi values We want to make Pixi a great experience for everyone, so we have a few values that we want to uphold: 1. **Fast**. We want to have a fast package manager, that is able to solve the environment in a few seconds. 1. **User Friendly**. We want to have a package manager that puts user friendliness on the front-line. Providing easy, accessible and intuitive commands. That have the element of *least surprise*. 1. **Isolated Environment**. We want to have isolated environments, that are reproducible and easy to share. Ideally, it should run on all common platforms. The Conda packaging system provides an excellent base for this. 1. **Single Tool**. We want to integrate most common uses when working on a development workspace with Pixi, so it should support at least dependency management, command management, building and uploading packages. You should not need to reach to another external tool for this. 1. **Fun**. It should be fun to use Pixi and not cause frustrations, you should not need to think about it a lot and it should generally just get out of your way. ## Conda We are building on top of the conda packaging ecosystem, this means that we have a huge number of packages available for different platforms on [conda-forge](https://conda-forge.org/). We believe the conda packaging ecosystem provides a solid base to manage your dependencies. Conda-forge is community maintained and very open to contributions. It is widely used in data science and scientific computing, robotics and other fields. And has a proven track record. More info: [Conda & Pypi](../../concepts/conda_pypi/) ## Target languages Essentially, we are language agnostics, we are targeting any language that can be installed with conda. Including: C++, Python, Rust, Zig etc. But we do believe the python ecosystem can benefit from a good package manager that is based on conda. So we are trying to provide an alternative to existing solutions there. We also think we can provide a good solution for C++ projects, as there are a lot of libraries available on conda-forge today. Pixi also truly shines when using it for multi-language projects e.g. a mix of C++ and Python, because we provide a nice way to build everything up to and including system level packages.