pixi add - Pixi

The pixi add command adds dependencies to your workspace manifest and updates the lock file.

Usage

pixi add [OPTIONS] <SPEC>...

Arguments

SPEC

string

required

The dependency to add. Can be:

Package name: numpy
Conda MatchSpec: python=3.11.*, numpy>=1.20,<2.0
PyPI requirement: requests==2.28.0 (with --pypi)
Version spec: python=3.11, numpy>=1.20

Multiple packages can be specified.

Basic Options

PyPI Dependencies

--pypi

boolean

default:"false"

Add as a PyPI dependency instead of conda. Conflicts with --host and --build.

pixi add --pypi requests flask
pixi add --pypi "boto3>=1.26"

Platform-Specific Dependencies

--platform

string

Platform for which the dependency should be added. Can be specified multiple times.Short flag: -p

pixi add python --platform linux-64 --platform osx-arm64
pixi add cuda --platform linux-64

Feature-Specific Dependencies

--feature

string

default:"default"

Feature to add the dependency to.Short flag: -f

pixi add numpy --feature ml
pixi add pytest --feature test

Editable PyPI Packages

--editable

boolean

default:"false"

Install PyPI package in editable mode. Requires --pypi.

pixi add --pypi --editable ./local-package
pixi add --pypi --editable "mypackage @ file:///absolute/path"

Dependency Type Options

These options are hidden by default but available for advanced use cases.

--host

boolean

default:"false"

Add as a host dependency. Conflicts with --build and --pypi.

--build

boolean

default:"false"

Add as a build dependency. Conflicts with --host and --pypi.

pixi add cmake --build
pixi add python --host

Git Dependencies

Git Repository

--git

string

Git repository URL for the dependency.Short flag: -g

pixi add --git https://github.com/user/repo mypackage

Git Reference

--branch

string

Git branch to use. Requires --git.

--tag

string

Git tag to use. Requires --git.

--rev

string

Git revision (commit SHA) to use. Requires --git.

pixi add --git https://github.com/user/repo --branch main mypackage
pixi add --git https://github.com/user/repo --tag v1.0.0 mypackage
pixi add --git https://github.com/user/repo --rev abc123 mypackage

Only one of --branch, --tag, or --rev can be specified.

Git Subdirectory

--subdir

string

Subdirectory of the git repository. Requires --git.Short flag: -s

pixi add --git https://github.com/user/monorepo --subdir packages/mylib mylib

Update Options

Skip Installation

--no-install

boolean

default:"false"

Don’t install the environment, only update the lock file.

pixi add numpy --no-install

Lock File Usage

--frozen

boolean

default:"false"

Install as defined in the lock file without updating it.Env: PIXI_FROZEN

--locked

boolean

default:"false"

Check if lock file is up-to-date, abort if not.Env: PIXI_LOCKED

pixi add numpy --frozen
pixi add numpy --locked

Examples

Basic Package Addition

Add the latest version:

pixi add python

Resulting pixi.toml:

[dependencies]
python = ">=3.12.3,<3.13"

Specific Version

pixi add python=3.11

Resulting pixi.toml:

[dependencies]
python = "3.11.*"

Version Range

pixi add "numpy>=1.20,<2.0"

Resulting pixi.toml:

[dependencies]
numpy = ">=1.20,<2.0"

Multiple Packages

pixi add python pytest numpy pandas

PyPI Packages

pixi add --pypi requests flask

Resulting pixi.toml:

[pypi-dependencies]
requests = "*"
flask = "*"

PyPI with Version

pixi add --pypi "requests==2.28.0"

Resulting pyproject.toml (if using pyproject format):

[project]
dependencies = [
  "requests==2.28.0",
]

Platform-Specific Package

pixi add cuda --platform linux-64

Resulting pixi.toml:

[target.linux-64.dependencies]
cuda = ">=12.0.0,<13"

Feature-Specific Packages

pixi add pytest pytest-cov --feature test

Resulting pixi.toml:

[feature.test.dependencies]
pytest = ">=8.0.0,<9"
pytest-cov = ">=4.0.0,<5"

Git Repository

pixi add --git https://github.com/mamba-org/rattler rattler-py

Resulting pixi.toml:

[dependencies]
rattler-py = { git = "https://github.com/mamba-org/rattler" }

Git with Branch

pixi add --git https://github.com/user/repo --branch develop mypackage

Resulting pixi.toml:

[dependencies]
mypackage = { git = "https://github.com/user/repo", branch = "develop" }

Editable Local Package

pixi add --pypi --editable ./my-package

Resulting pixi.toml:

[pypi-dependencies]
my-package = { path = "./my-package", editable = true }

Pinning Strategy

The pinning strategy determines how version constraints are added. Configure globally:

~/.pixi/config.toml

pinning-strategy = "semver"  # default

Or via CLI:

pixi add python --pinning-strategy exact-version

Strategy Options

Strategy	Example Input	Resulting Constraint
`no-pin`	`numpy`	`*`
`semver`	`numpy=1.26.0`	`>=1.26.0,<2` (or `>=1.26.0,<1.27` for v0)
`exact-version`	`numpy=1.26.0`	`==1.26.0`
`major`	`numpy=1.26.0`	`>=1.26.0,<2`
`minor`	`numpy=1.26.0`	`>=1.26.0,<1.27`
`latest-up`	`numpy=1.26.0`	`>=1.26.0`

Non-SemVer Packages

These packages default to minor pinning:

Python
Rust
Julia
GCC, GXX, GFortran
NodeJS, Deno
R, R-Base
Perl

PyProject.toml Behavior

When using pyproject.toml format:

Default Feature

pixi add --pypi boto3

Adds to native project.dependencies:

[project]
dependencies = [
  "boto3",
]

Named Feature

pixi add --pypi boto3 --feature aws

Adds to dependency-groups:

[dependency-groups]
aws = [
  "boto3",
]

Platform or Editable

With --platform or --editable, adds to pixi tables:

pixi add --pypi boto3 --platform linux-64

[tool.pixi.target.linux-64.pypi-dependencies]
boto3 = "*"

Combining Options

Platform + Feature

pixi add cuda --platform linux-64 --feature gpu

Multiple Platforms

pixi add python --platform linux-64 --platform osx-arm64 --platform win-64

PyPI + Feature

pixi add --pypi pytest --feature test
pixi add --pypi black --feature lint

Global Options

--manifest-path

string

Path to pixi.toml, pyproject.toml, or workspace directory.Short flag: -m

pixi add numpy --manifest-path /path/to/project

Config Options

These options override global configuration:

--pinning-strategy <STRATEGY>: Set pinning strategy
--tls-no-verify: Disable TLS verification
--auth-file <FILE>: Path to authentication file
--pypi-keyring-provider <PROVIDER>: Keyring provider for PyPI

Troubleshooting

Package Not Found

Error: package 'numpyy' not found Solution: Check package name spelling:

pixi search numpy
pixi add numpy

Version Conflict

Error: cannot satisfy version constraint Solution: Relax version constraints or check compatibility:

# Instead of
pixi add "numpy==1.20.0"

# Try
pixi add "numpy>=1.20"

Platform Not Supported

Error: package not available for platform Solution: Check package availability or use different package:

pixi search numpy --platform osx-arm64

PyPI and Conda Conflict

Error: cannot mix --pypi with --host or --build Solution: Separate commands:

pixi add numpy              # Conda
pixi add --pypi requests    # PyPI

Workspace Commands

Environment Commands

Global Commands

Build Commands

Other Commands

Documentation Index

​Usage

​Arguments

​Basic Options

​PyPI Dependencies

​Platform-Specific Dependencies

​Feature-Specific Dependencies

​Editable PyPI Packages

​Dependency Type Options

​Git Dependencies

​Git Repository

​Git Reference

​Git Subdirectory

​Update Options

​Skip Installation

​Lock File Usage

​Examples

​Basic Package Addition

​Specific Version

​Version Range

​Multiple Packages

​PyPI Packages

​PyPI with Version

​Platform-Specific Package

​Feature-Specific Packages

​Git Repository

​Git with Branch

​Editable Local Package

​Pinning Strategy

​Strategy Options

​Non-SemVer Packages

​PyProject.toml Behavior

​Default Feature

​Named Feature

​Platform or Editable

​Combining Options

​Platform + Feature

​Multiple Platforms

​PyPI + Feature

​Global Options

​Config Options

​Troubleshooting

​Package Not Found

​Version Conflict

​Platform Not Supported

​PyPI and Conda Conflict

​See Also

Build docs developers (and LLMs) love

Usage

Arguments

Basic Options

PyPI Dependencies

Platform-Specific Dependencies

Feature-Specific Dependencies

Editable PyPI Packages

Dependency Type Options

Git Dependencies

Git Repository

Git Reference

Git Subdirectory

Update Options

Skip Installation

Lock File Usage

Examples

Basic Package Addition

Specific Version

Version Range

Multiple Packages

PyPI Packages

PyPI with Version

Platform-Specific Package

Feature-Specific Packages

Git Repository

Git with Branch

Editable Local Package

Pinning Strategy

Strategy Options

Non-SemVer Packages

PyProject.toml Behavior

Default Feature

Named Feature

Platform or Editable

Combining Options

Platform + Feature

Multiple Platforms

PyPI + Feature

Global Options

Config Options

Troubleshooting

Package Not Found

Version Conflict

Platform Not Supported

PyPI and Conda Conflict

See Also