# How to migrate from conda to pixi

This guide converts a conda project (defined by an `environment.yml`) into a [pixi](https://pydevtools.com/handbook/reference/pixi.md) project. The result: project-local environments, an automatic lockfile, a built-in task runner, and access to the same [conda-forge](https://pydevtools.com/handbook/reference/conda-forge.md) packages.

## Prerequisites

- pixi installed ([installation instructions](https://pixi.sh/latest/getting_started/))
- An `environment.yml` file from an existing conda project
- Familiarity with conda workflows (see [Take Over an Existing Conda Environment](https://pydevtools.com/handbook/tutorial/take-over-an-existing-conda-environment.md) if you're new to conda)

## Import into pixi

From the directory containing your `environment.yml`:

```console
$ pixi init --import environment.yml
✔ Created /path/to/analysis/pixi.toml
```

If you see `Error: × pixi.toml already exists`, the directory is already a pixi project. Move to a fresh directory or delete the existing `pixi.toml`. If you see `failed to open file 'environment.yml'`, run the command from the directory that contains the file.

`pixi init` also writes a `.gitignore` (with `.pixi/*` excluded) and a `.gitattributes` (so `pixi.lock` diffs render sensibly). The lockfile itself is generated by `pixi install` below.

## Review the generated pixi.toml

Open `pixi.toml`. For a typical scientific Python `environment.yml` (conda-forge channel, a few pinned packages, one `pip:` entry), the result looks like:

```toml {filename="pixi.toml"}
[workspace]
name = "analysis"
channels = ["conda-forge"]
platforms = ["osx-arm64"]

[dependencies]
python = "3.12.*"
pandas = "2.2.*"
matplotlib = "3.9.*"
scikit-learn = "1.5.*"
jupyter = "*"

[pypi-dependencies]
seaborn = "*"
```

Packages from the `pip:` section in `environment.yml` land under `[pypi-dependencies]` and install from PyPI automatically. The `platforms` field reflects only your current machine; add others if your team uses different operating systems (e.g., `platforms = ["osx-arm64", "linux-64"]`).

## Verify the environment

Install and test that everything works:

```console
$ pixi install
✔ The default environment has been installed.
$ pixi run python -c "import pandas; import sklearn; print('All imports OK')"
All imports OK
```

If you see `Error: × could not find pixi.toml or pyproject.toml`, you ran `pixi install` from outside the project. `cd` into the directory that contains `pixi.toml` and try again.

## Replace conda habits

The workflow mapping from conda to pixi:

| Conda command | Pixi equivalent | Notes |
|---|---|---|
| `conda activate analysis` | `pixi shell` | Spawns a subshell with the environment active |
| `conda install scipy` | `pixi add scipy` | Adds to `pixi.toml` and updates the lockfile |
| `pip install some-pkg` | `pixi add --pypi some-pkg` | Tracked in `[pypi-dependencies]` |
| `conda env export` | (automatic) | `pixi.lock` is always up to date |
| `conda env create -f ...` | `pixi install` | Recreates from `pixi.toml` + `pixi.lock` |
| `conda list` | `pixi list` | Shows installed packages |

## Move Makefile targets into tasks

If your conda project used a Makefile or shell scripts for common operations, move them into `pixi.toml`:

```toml {filename="pixi.toml"}
[tasks]
analyze = "python analyze.py"
test = "pytest"
notebook = "jupyter lab"
```

Run them with `pixi run analyze`, `pixi run test`, etc.

## Commit pixi.toml and pixi.lock

```bash
git add pixi.toml pixi.lock
```

Commit `pixi.lock` — that's how teammates get the same resolved environment when they run `pixi install`. Confirm `.pixi/` is in `.gitignore`; `pixi init --import` already added it.

## Remove the old conda environment

Once the pixi project is working:

```bash
conda deactivate
conda env remove -n analysis
```

Keep the `environment.yml` for a transition period if other team members haven't switched yet.

## Learn more

- [When Should I Choose pixi Over uv?](https://pydevtools.com/handbook/explanation/when-should-i-choose-pixi-over-uv.md) for picking the right tool
- [uv vs pixi vs conda for Scientific Python](https://pydevtools.com/handbook/explanation/uv-vs-pixi-vs-conda-for-scientific-python.md) for a fuller comparison
- [Create Your First Python Project with pixi](https://pydevtools.com/handbook/tutorial/create-your-first-python-project-with-pixi.md) for pixi fundamentals
- [Set Up a GPU Data Science Project with pixi](https://pydevtools.com/handbook/tutorial/set-up-a-gpu-data-science-project-with-pixi.md) for PyTorch and CUDA workflows
- [pixi reference](https://pydevtools.com/handbook/reference/pixi.md) for the full feature set