pixi add

Add dependencies to your pixi workspace

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

See Also

• pixi remove - Remove dependencies
• pixi install - Install dependencies
• pixi update - Update dependencies
• pixi upgrade - Upgrade dependencies