How to Use Pixi: The Beginner's Guide (First Init, the Workspace Lesson, First Environment, and the Global-Install Arc)

CodexFuse Team · 2026-11-02T02:05:04.413Z · 10 min read

Learn how to use Pixi, prefix.dev’s package manager for conda-ecosystem projects: install it, init your first workspace, and mix conda and PyPI in one locked environment.

What Is Pixi, Exactly?

Pixi is a package manager and environment manager for developers, built by prefix.dev and written in Rust. If you are learning how to use Pixi, start with the mental model its makers use: Pixi is project-first environments — one manifest (pixi.toml), one lockfile (pixi.lock), and the conda-forge AND PyPI ecosystems living together in the same environment. Say it once and keep it: one project, one file, reproducible everywhere.

One disambiguation up front, because bare search results mix them together: this is not the Pixi beauty brand and not Pixi.js, the 2D rendering library. Those own the bare word "pixi" on the web. This pixi package manager tutorial is about the command-line tool from prefix.dev that replaces the old conda dance of conda create, conda activate, and environments that quietly rot when you look away.

The payoff is concrete if you ship Python: conda packages (numpy, GDAL, CUDA toolkits) and PyPI packages (httpx, ruff, anything pip would give you) resolve in one unified solve into one locked environment that lives inside your project folder. A pixi Python environment holds both ecosystems at once — not in some global ~/miniconda3/envs directory you have to babysit. If you already pin your tools with something like the Mise beginner guide workflows describe — mise pins tool versions, Pixi resolves a whole project's dependency graph — this is the other half of that story, drawn once, never rivals.

How Do You Install Pixi?

You install Pixi with one official command, and the current release as of this writing is v0.83.0, published 2026-10-22 per the prefix-dev/pixi releases page. Pick the route that matches your machine:

curl -fsSL https://pixi.sh/install.sh | bash

iwr -useb https://pixi.sh/install.ps1 | iex

winget install prefix-dev.pixi

brew install pixi

Verify with pixi --version, then enable shell completion — pixi completion --shell bash (bash, zsh, fish, elvish, and PowerShell variants are documented on the getting-started page). Updating is the same story: rerun the install script, or brew upgrade pixi if you went the Homebrew route; pin a version by exporting PIXI_VERSION=vX.Y.Z before rerunning the script. Skip the install advice in old blog posts: the 2023-era guides that tell you to conda install pixi or use pixi create and pixi activate describe commands that no longer exist.

How Do You Start a Pixi Workspace?

You start with pixi init, which creates a project directory and a minimal pixi.toml manifest — Pixi now calls these workspaces, not projects. Run pixi init my-app, step inside, and open the manifest. A fresh one looks like this:

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

[dependencies]
python = "3.12.*"

[tasks]
hello = "python hello.py"

Three keys do the heavy lifting: channels (where conda packages come from — conda-forge is the default), platforms (which OS/arch combos get locked; auto-detected if you omit them), and [dependencies] (your conda packages). Two more tables you will meet quickly: [tasks], your scripts, and [pypi-dependencies], your PyPI packages — but they only appear once you add something. Two flags worth knowing at init time: -c/--channel to add channels up front (repeatable), and -i/--import environment.yml to import an old conda environment file — Pixi ships a documented conda-migration path for exactly this reason.

One freshness note for 2026: older docs and tutorials show a [project] table at the top of pixi.toml. That table is now stale — the current manifest uses [workspace], and Pixi's own init docs call the flow "Making a Pixi workspace." Write new manifests with [workspace] and ignore anything that still shows [project].

Pixi also drops a .gitignore covering the environment directory, because the actual installed environment lives in .pixi/envs/ inside your project — versioned manifest in, physical environment out. That is the whole per-project promise: no global env namespace, no conda activate, nothing leaking between projects.

How Do Pixi's Conda and PyPI Packages Work Together?

This is the lesson the whole tool exists for, so say it once: pixi add installs from conda-forge and pixi add --pypi installs from PyPI — two channels, one environment, one unified dependency solve. Pixi embeds the uv library to do the PyPI half of the resolution and merges it into the same pixi.lock as the conda half.

A worked example — a Python data project needing both ecosystems:

cd my-app
pixi add python "numpy>=2"
pixi add --pypi httpx
pixi install

Each add auto-solves, writes pixi.lock, and installs. The manifest now holds python and numpy under [dependencies] (conda) and httpx under [pypi-dependencies] (PyPI). The pixi lockfile pins every transitive dependency to exact versions across every platform in platforms — and it must be committed to git alongside pixi.toml, say it once: that pair is what makes "works on my machine" provable on anyone else's.

Before Pixi, the same setup meant conda create, then pip inside the conda env, then a silent war between conda's solver and pip's installer over who owned numpy. Here the two resolvers talk to each other inside one solve. That is not a metaphor — it is the literal architecture on the getting-started page.

Should You Use pixi run or pixi shell?

One sentence each, say it once: pixi run <cmd> runs a single command inside the activated environment; pixi shell spawns a new interactive shell with the environment activated. pixi run python hello.py is how CI and scripts do it; pixi shell is how you poke around by hand.

The third member of the trio is tasks — Pixi's replacement for the ad-hoc shell scripts every repo accumulates. Add one with pixi task add test pytest, and it lands in [tasks] as a plain entry you can run with pixi run test. The rich form supports cmd, cwd, depends-on, plus per-feature and per-platform overrides, so a single pixi run lint can mean "run ruff on Linux, run ruff via a different binary on Windows" without anyone memorizing the matrix.

How Do You Install Tools Globally with Pixi?

Not every tool belongs to a project. pixi global install handles that lane: each package lands in its own isolated environment, and only its binary is exposed to your PATH — think pipx or condax, minus the version conflicts. pixi global install ruff gives you ruff everywhere without ever touching a project env; pixi global install starship rattler-build installs two tools at once; --with adds extra packages into the same isolated env (pixi global install ipython --with numpy --with scipy).

The global manifest lives at ~/.pixi/manifests/pixi-global.toml, and --expose renames or selects which binaries get linked, --environment groups several packages into one named global env, and --platform targets a specific platform. The lane line to draw once: this is the same job the Homebrew beginner guide workflows describe — brew installs system tools globally, Pixi global installs versioned tools in isolation so they never fight each other.

How Does Pixi Compare to Conda, uv, and Mise?

Every comparison here is drawn once, and none of these get their own rival page — one page per intent, this one. The field has a clear answer for "conda alternative 2026," and Pixi's own docs frame it the same way:

If you containerize the result, the Docker beginner guide covers the next step — and what Docker actually is explains why a locked environment and a container image are solving the same reproducibility problem at different layers.

Sources

Facts in this pixi tutorial were verified from sources fetched on 2026-11-02: the Pixi getting-started documentation at pixi.prefix.dev (official install command curl -fsSL https://pixi.sh/install.sh | bash, ~/.pixi/bin location, PATH behavior, completion, PIXI_VERSION pinning, the [workspace] manifest format, pixi add vs --pypi, the embedded uv resolver claim, pixi global install flags, and the switching_from/conda migration page); the prefix-dev/pixi GitHub releases page (v0.83.0, released 2026-10-22); and the prefix-dev/setup-pixi GitHub releases page (setup-pixi v0.11.3, released 2026-11-01 — the docs' @v0.5.1 workflow example is behind, use v0.11.3: uses: prefix-dev/[email protected]).

Frequently Asked Questions

Is Pixi a replacement for conda?

Pixi is the conda ecosystem's modernization, not a fork of it: same channels (conda-forge), same packages, a documented migration page, and pixi init --import environment.yml for existing envs. What changes is the workflow — per-project environments in .pixi/, a fast Rust rattler solver, lockfiles, tasks, and PyPI packages in the same solve. If "conda alternative 2026" is what brought you here, this is the answer the field has converged on.

What is the difference between pixi add and pixi add --pypi?

Plain pixi add installs conda packages into [dependencies]; pixi add --pypi installs from PyPI into [pypi-dependencies]. Both land in one environment and one pixi.lock via a unified solve (Pixi embeds the uv library for the PyPI half). Rule of thumb: if conda-forge has it, pixi add; if only PyPI has it, add --pypi.

Should I commit the pixi lockfile to git?

Yes — always. Commit pixi.toml AND pixi.lock. The manifest says what you want; the lockfile pins exact versions across every platform in platforms, which is what makes the environment reproducible on a teammate's machine or in CI. Pixi's own pixi init writes a .gitignore that excludes the physical environment but keeps the lockfile.

Can Pixi replace pip and virtualenv?

For project environments, yes — pixi shell and pixi run do the job of activating a virtualenv, and pixi add --pypi covers PyPI packages. The difference is scope: virtualenv only isolates Python; Pixi also installs the non-Python system libraries (compilers, GDAL, CUDA) that pip cannot provide, all locked in one file.

Does Pixi work on Windows?

Yes — platforms supports win-64 alongside linux-64 and osx-arm64, installation is via the PowerShell one-liner or winget (winget install prefix-dev.pixi), and the lockfile can pin all three platforms at once so one pixi.toml serves the whole team.