pixi

Pixi ヘルパー

Python プロジェクト向けの高速な conda ベースのパッケージマネージャー、Pixi の使い方を熟知したガイダンスです。

目的

開発者が Pixi を効果的に使用して、conda／PyPI の依存関係を管理し、分離された環境でコマンドを実行し、複数環境のプロジェクトを設定できるよう支援します。

使用する場面

• pixi.toml または pixi.lock ファイルを扱うとき
• パッケージをインストールまたは管理するとき
• pixi 環境でコマンドやタスクを実行するとき
• 開発環境／本番環境を設定するとき
• pixi の設定エラーをデバッグするとき

---

コマンド早見表

基本コマンド

# Initialize & install
pixi init [project-name]
pixi install                         # install default environment
pixi install -e dev                  # install dev environment

# Add dependencies
pixi add python=3.11 pytorch pandas  # conda packages
pixi add --pypi transformers         # PyPI packages
pixi add --feature dev pytest ruff   # to dev feature

# Run commands
pixi run python script.py            # use default env
pixi run -e dev pytest               # use dev env
pixi shell                           # interactive shell
pixi shell -e dev                    # dev shell

# Tasks
pixi task add lint "ruff check ."
pixi task list
pixi run lint

# Production
pixi run --frozen --no-install train.py

主なフラグ

• -e <env>：特定の環境を使用します
• --frozen：ロックファイルを更新しません（再現性を確保します）
• --no-install：インストールを省略します
• --feature <name>：特定の feature を対象にします

---

基本概念

ワークスペース

次の項目を含むディレクトリです。

• pixi.toml：設定ファイル（コミットしてください）
• pixi.lock：ロックファイル（コミットしてください）
• .pixi/：環境キャッシュ（コミットしないでください）

環境

名前付きの依存関係セットです。選択するには -e フラグを使用します。

pixi run python script.py       # default
pixi run -e dev pytest           # dev
pixi run -e prod train.py        # prod

Feature

環境に組み合わせて使う、再利用可能な依存関係のグループです。

タスク

pixi.toml で定義されたコマンドです。pixi run <task-name> で実行します。

---

コマンドの使い分け

目的別のコマンド

目的	コマンド
初回セットアップ	pixi install
パッケージの追加	pixi add <pkg>
コマンドを1つ実行	pixi run <cmd>
対話的な作業	pixi shell
タスクを実行	pixi run <task>
本番環境	pixi run --frozen --no-install

依存関係の追加

まずは conda を優先してください（互換性が高く、高速です）。

pixi add numpy pytorch

必要に応じて PyPI を使用してください。

pixi add --pypi transformers

なぜ conda を優先するのですか？ Pixi は、まず conda の依存関係を解決し、その後に PyPI の依存関係を解決します。

---

pixi.toml の設定

プロジェクトのメタデータ

[project]
name = "my-project"
channels = ["conda-forge", "pytorch"]  # order matters
platforms = ["linux-64", "osx-arm64"]

依存関係

[dependencies]
python = ">=3.10"
numpy = "*"
pytorch = ">=2.0,<3"

[pypi-dependencies]
transformers = "*"
my-pkg = { path = "./local", editable = true }

タスク

シンプルなタスク：

[tasks]
test = "pytest tests/"

環境変数を使用する場合：

[tasks.train]
cmd = "python train.py"
env = { CUDA_VISIBLE_DEVICES = "0,1" }

依存関係がある場合：

[tasks]
clean = "rm -rf __pycache__"
test = { cmd = "pytest", depends-on = ["clean"] }

複数行の場合：

[tasks.submit]
cmd = """
python train.py \
  --config config.yaml \
  --output results/
"""

Feature

[feature.dev.dependencies]
pytest = "*"
ruff = "*"

[feature.cuda.dependencies]
pytorch-cuda = "12.1"

[environments]
default = []
dev = ["dev"]
gpu = ["cuda"]
dev-gpu = ["dev", "cuda"]

環境のアクティベーション

[activation.env]
CUDA_HOME = "/usr/local/cuda"
PROJECT_ROOT = "$PIXI_PROJECT_ROOT"

---

よくあるワークフロー

お使いのパターン（susser-tod）

開発時のテスト：

pixi run -e dev pytest ./tests

型チェック：

pixi run typecheck

プロファイリング：

pixi run -e dev nsys profile python train.py

---

トラブルシューティング

1. パッケージが見つからない

確認事項：

1. channels = [...] にチャンネルが指定されていますか？
2. パッケージ名は正しいですか？次を試してください：pixi search <pkg>
3. PyPI を試してください：pixi add --pypi <pkg>

2. 環境がアクティベートされない

❌ 誤り：python script.py（pixi を介さない python） ✅ 正しい：pixi run python script.py

4. ロックファイルの競合

マージ競合が発生した後：

pixi install              # regenerate lock
# or
rm pixi.lock && pixi install

5. 環境変数が設定されない

[activation.env] の変数が機能するのは、次の場合のみです。

• pixi run <cmd>
• pixi shell の実行中

pixi の外で python を直接実行した場合は機能しません。

6. 依存関係のバージョン競合

環境を分離するには solve-group を使用します。

[environments]
default = { solve-group = "group1" }
dev = { features = ["dev"], solve-group = "group1" }  # shared
prod = { solve-group = "group2" }                     # isolated

---

ベストプラクティス

依存関係

✅ まずは conda を使い、必要に応じて PyPI を使用します ✅ 重要なバージョンは固定します：pytorch = "2.1.*" ✅ バージョン制約を指定します：python = ">=3.10,<3.12" ❌ 同じパッケージに conda と PyPI を混在させないでください

ロックファイル

✅ pixi.lock をコミットします ✅ CI／本番環境では --frozen を使用します

環境

✅ feature を使って依存関係を整理します ✅ 可能な場合は solve-group を共有します ✅ 環境は2～4個が理想です

---

参考資料

• pixi.toml スキーマの詳細：REFERENCE.md を参照してください
• 公式ドキュメント：https://pixi.sh/latest/
• pixi.toml 仕様：https://pixi.sh/latest/reference/pixi_toml/

---

Pixi の実践的なガイダンスです。プロジェクト固有のパターンについては、CLAUDE.md を確認してください。