pixi

Pixi — エージェント向けの再現可能な環境とタスク

Pixi を使用して、conda および PyPI の依存関係、多言語環境、ワークスペースのタスクを管理します。現在の目的に合わせて手順を選び、その段階で必要なワークフローとリファレンスのセクションだけを読み込みます。

現在のワークフローのみを読み込む

リンクはユーザーのワークスペースではなく、このスキルのディレクトリを基準に解決してください。タスクが次の段階に進んだら、別のワークフローを読み込みます。

現在の目的	読む項目	範囲
ワークスペースを初期化またはインポートする	初期化	マニフェスト形式、チャンネル、プラットフォーム、既存の Python プロジェクト
パッケージを追加、削除、更新、またはアップグレードする	依存関係	Conda／PyPI の指定、機能の所有権、ロックポリシー
機能と環境を組み合わせる	環境	デフォルト機能、分離された環境、ソルブグループ
コードを実行する、またはタスクを管理する	実行	プロジェクトの実行、タスク定義、一時的な実行
パッケージを調べる、またはトラブルシューティングする	調査	診断、逆依存関係、対象を絞った修復
グローバル CLI ツールをインストールまたは管理する	グローバル	分離されたグローバルツール、公開、更新、アンインストール

段階的に読み込む例：

• 既存のスクリプトを実行する： run を読みます。パッケージの変更が必要な場合に限り、dependencies も読み込みます。
• 名前付き環境にパッケージを追加する： dependencies を読みます。その機能の構成変更が必要な場合は、environments も読み込みます。
• 失敗を調査する： inspect を読みます。診断で必要と判断された場合に限り、再インストールまたは更新を行います。

共通ルール

• 設定を変更する前に、既存のマニフェストと関連するプロジェクトの指示を読みます。タスクで変更が必要な場合を除き、形式、チャンネル、対応プラットフォーム、ツールチェーンを維持してください。別のワークスペースが選択される可能性がある場合は、--manifest-path を使用します。
• 依存関係は Pixi を通じて宣言します。Pixi 環境内で pip、conda、mamba を使って宣言されていないインストールを行うのではなく、pixi add または pixi add --pypi を使用してください。
• 依存関係は機能が所有し、環境は機能を組み合わせます。 追加／削除には --feature を、実行／インストール／一覧表示には --environment を使用します。複数の環境で共有されている機能を変更する前に、その構成を確認してください。
• プロジェクトのコマンドには pixi run を優先してください。必要に応じて選択した環境をインストール／同期するため、通常は別途インストールする必要はありません。ワークスペースに依存しない一時的なセットアップを意図している場合に限り、pixi exec を使用します。
• Pixi は pixi.lock を生成します。手作業で編集しないでください。再現可能なアプリケーション／研究用ワークスペースにするため、マニフェストとロックファイルを一緒にバージョン管理します。依存関係を変更した後は、両方の差分を確認してください。
• ロックの動作は意図的に選択してください。通常の実行では古いロックが更新される場合があります。--locked はマニフェストとの一致を要求し、--frozen は一致を確認せずにロックを使用します。locked と frozen を併用しないでください。
• 人が読みやすい出力を優先し、プログラムで解析する必要がある場合は JSON を使用します。広範囲の更新、キャッシュの消去、再インストールを行う前に、選択した環境を診断してください。
• 例は Pixi 0.71.1 で確認済みです。バージョン固有のオプションを確認するには、pixi --version と、インストールされているコマンドの --help を使用してください。

よくある使い方ガイド（少数例）

example- または example_ で始まる名前は、パッケージ、機能、環境、パスの架空のプレースホルダーです。ワークスペースのマニフェストを読んだ後、実際の名前に置き換えてください。

1. 既存のプロジェクトコードを直接実行する

ユーザー：「既存の example-analysis 環境でテストを実行してください。」

応答：「プロジェクトの環境を直接使います。必要に応じて run が準備するため、通常は別途インストールする必要はありません。」

pixi run -e example-analysis python -m unittest discover -s tests -p 'test_*.py' -v

理由： run は実行可能ファイルだけでなく、タスクも受け付けます。外側のシェルで展開されないよう、テストパターンを引用符で囲みます。インストール自体が確認対象の手順である場合は、明示的にインストールを行います。

2. パッケージソースの不一致を解決する

ユーザー: 「conda チャンネルには example-package 1.2.3 の候補がありません。example-analysis でこのバージョンを使ってください。」

応答: 「PyPI で要求されたバージョンが提供されているかを確認し、この依存関係を持つフィーチャーを特定して、その conda 宣言を置き換えます。ここでは、example-tools フィーチャーが example-analysis 環境に属しています。」

pixi remove --feature example-tools example-package
pixi add --feature example-tools --pypi 'example-package==1.2.3'
pixi run -e example-analysis python -c 'from importlib.metadata import version; print(version("example-package"))'
git diff -- pixi.toml pixi.lock

理由: 候補が見つからない場合は、パッケージの入手可能性、ソース、制約を確認する必要があります。検証済みのソースを選び、変更内容を確認してください。

3. 名前付きの編集可能な要件を宣言する

ユーザー: 「ローカルの example-local-package チェックアウトを、example-analysis の編集可能な依存関係として使ってください。」

応答: 「その環境で使われているフィーチャーである example-tools に、名前付きのローカル要件を追加します。」

pixi add --feature example-tools --pypi --editable 'example-local-package @ ./packages/example-local-package'
pixi run -e example-analysis python -c 'import example_local_package; print(example_local_package.__file__)'

理由: ローカルの PyPI 要件では、@ の前にパッケージ名が必要です。add はフィーチャーを選択し、run は環境を選択します。ディストリビューション名とインポート名は、ローカルパッケージのメタデータとソースから取得されます。

4. 分離されたワークスペースを明示的に選択する

ユーザー: 「メインプロジェクトの依存関係を変更せずに、既存の一時ワークスペースで比較を実行してください。」

応答: 「そのマニフェストを明示的に選択して、インタープリターを確認します。」

pixi run --manifest-path temp/example-comparison/pixi.toml python -c 'import sys; print(sys.executable)'

理由: マニフェストを明示的に選択すると、コマンドの対象を意図したワークスペースに限定できます。環境が切り離されている場合も含め、報告されたインタープリターのパスを使用してください。通常の run では、選択したワークスペースのロックとインストールが更新される場合があります。

5. ロックを維持するか、マニフェストとの一致を要求する

ユーザー: 「既存のロックを更新せずに、検証を実行してください。」

応答: 「ロックを維持するには frozen を使います。マニフェストとの一致も必要な場合は、代わりに locked を使ってください。」

pixi run --frozen -e example-analysis python scripts/example_validate.py

理由: locked はマニフェストとロックの一致を確認し、frozen はその確認を行わず既存のロックを使用します。選択した環境でパッケージが必要な場合は、どちらを使ってもインストールされることがあります。

6. 1 回限りの依存関係には exec を意図的に使う

ユーザー: 「この 1 回限りのヘルパーを、プロジェクトに追加せずに example-helper-package とともに実行してください。」

応答: 「Python とヘルパーの依存関係を含む、別の一時環境を使います。」

pixi exec --spec python --spec example-helper-package -- python scripts/example_helper.py

理由: exec はプロジェクトのロックとは独立して、一時的な依存関係を提供します。保守対象のプロジェクトコードでは、依存関係をフィーチャーに宣言し、run を使ってください。ヘルパーが発生させる例外は、アプリケーションエラーとして診断してください。

依存関係の変更が連鎖して失敗した場合

先行する add がすでに成功している可能性があります。&& は変更をロールバックしません。再試行する前に git diff -- pixi.toml pixi.lock を確認してください。解決不能な依存関係と、インストールの失敗、実行したスクリプトが発生させた例外を区別してください。pixi lock の成功で確定するのはロックの状態であり、環境がインストール済みであることではありません。

確認しておくとよいコマンドのヘルプ

使い慣れないオプションを選ぶときは、インストール済みコマンドのヘルプを実行してください。ネストされたコマンドでは、使用するサブコマンドのヘルプを表示してください。

判断	ヘルプコマンド
ワークスペースを初期化またはインポートする	pixi init --help、pixi import --help
依存関係のソースとフィーチャーを選ぶ	pixi add --help、pixi remove --help
プロジェクトのコードを実行する	pixi run --help
依存関係をインストールまたは解決する	pixi install --help、pixi lock --help
バージョンまたは要件を更新する	pixi update --help、pixi upgrade --help
環境を構成する	pixi workspace environment add --help
タスクを定義する	pixi task add --help
ツールを 1 回限りで実行する	pixi exec --help
環境を修復またはクリーンアップする	pixi reinstall --help、pixi clean --help
グローバルツールを管理する	pixi global --help を実行し、続けて該当するサブコマンドのヘルプを確認する

公式リファレンスドキュメント

読みやすいトピック名、ローカルスナップショット、上流のソースを確認するには、まずリファレンスマップをご覧ください。未変更の公式ドキュメントであるllms.txtには、より広範なドキュメントのインデックスが記載されています。

必要に応じて、スキーマの詳細についてはマニフェスト、機能の構成についてはマルチ環境、再現性についてはロックファイル、依存関係の混在についてはconda/PyPI、高度なタスクの動作についてはタスクをご覧ください。

あまり一般的でないコマンドについては、pixi <command> --helpを実行してください。ビルド、公開、認証、エディター、CI の手順は公式の llms.txt にまとめられています。タスクに必要な場合は、該当するページをご確認ください。