Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/prefix-dev/pixi/llms.txt

Use this file to discover all available pages before exploring further.

The pixi global add command adds dependencies to an existing global environment and updates the global manifest.

​
Usage

pixi global add [OPTIONS] --environment <ENV> <PACKAGE>...

​
Arguments

​
PACKAGE
string
required
Package specification to add to the global environment. Can be:
  • Package name: python
  • Version constraint: python=3.11.*
  • MatchSpec: python>=3.11,<3.12
Multiple packages can be specified.
pixi global add --environment python311 numpy pandas
pixi global add --environment tools ruff black

​
Options

​
Environment Selection

​
--environment
string
required
Specifies the environment that dependencies should be added to.Short flag: -eThe environment must already exist. Use pixi global install to create new environments.
pixi global add --environment myenv numpy
pixi global add -e python311 scipy
If the environment doesn’t exist, you’ll receive an error:Environment xyz doesn't exist. You can create a new environment with 'pixi global install'.

​
Expose Executables

​
--expose
string
Add one or more mappings describing which executables are exposed.Format: exposed_name=executable_name or just executable_name (which becomes executable_name=executable_name).Can be specified multiple times.
pixi global add --environment python311 python --expose python3.11=python
pixi global add -e tools pytest --expose pytest
pixi global add -e myenv mypackage --expose tool1=bin1 --expose tool2=bin2

​
Behavior

​
Adding Dependencies

When you add dependencies to a global environment:
  1. Dependencies are added to the global manifest
  2. The environment is synced (packages are installed)
  3. Executables are exposed based on --expose flags
  4. Completions are updated (on Unix systems)

​
Package Installation

The command installs or upgrades packages:
  • New packages: Installed with their dependencies
  • Existing packages: Upgraded to meet the new specification
  • Dependencies: Automatically resolved and installed

​
Executable Exposure

Exposed executables are made available system-wide:
  • On Unix: Symlinked to ~/.pixi/bin/
  • On Windows: Added to PATH through shims

​
Examples

​
Add Single Package

pixi global add --environment python311 numpy
Adds numpy to the python311 environment.

​
Add Multiple Packages

pixi global add --environment data-tools pandas matplotlib seaborn
Adds multiple data science packages at once.

​
Add with Version Constraint

pixi global add --environment myenv "python=3.11.*"
pixi global add -e tools "ruff>=0.1.0,<0.2"
Adds packages with specific version constraints.

​
Add and Expose Executables

pixi global add --environment python311 python --expose python3.11=python --expose python3=python
Adds Python and exposes it as both python3.11 and python3.

​
Add with Simple Exposure

pixi global add --environment tools pytest --expose pytest
Exposes pytest using its default name.

​
Add Multiple Packages with Exposure

pixi global add --environment myenv pytest pytest-cov --expose pytest=pytest
Adds pytest and pytest-cov, exposing only the pytest executable.

​
Common Use Cases

​
Add Tools to Existing Environment

# Create environment with Python
pixi global install --environment dev python=3.11

# Add development tools
pixi global add --environment dev black ruff mypy
pixi global add --environment dev pytest pytest-cov --expose pytest

​
Upgrade Package Version

# Upgrade to newer version
pixi global add --environment tools "ruff>=0.2.0"
This updates the constraint and upgrades the package if needed.

​
Add Package with Multiple Exposed Names

pixi global add --environment python311 python \
  --expose python3.11=python \
  --expose python3=python \
  --expose python=python
Exposes Python under multiple aliases.

​
Error Handling

​
Environment Doesn’t Exist

Error: Environment xyz doesn't exist Solution: Create the environment first: 
pixi global install --environment xyz python
pixi global add --environment xyz numpy

​
Package Not Found

Error: package 'numpyy' not found Solution: Check package name: 
pixi search numpy
pixi global add --environment myenv numpy

​
Version Conflict

Error: cannot satisfy version constraint Solution: Adjust version constraints or check compatibility: 
# Relax constraints
pixi global add --environment myenv "numpy>=1.20"

​
Reversion on Error

If the add operation fails, pixi automatically reverts the environment to its previous state.

​
State Changes Reported

After a successful add, pixi reports:
  • Packages added with versions
  • Executables exposed
  • Completions updated
Example output: 
✅ Added numpy 1.26.0 to environment myenv
✅ Exposed python3.11 -> python
✅ Updated completions

​
global add vs global install

  • pixi global install: Creates a new environment or reinstalls existing one
  • pixi global add: Adds dependencies to an existing environment

​
global add vs add

  • pixi add: Adds dependencies to workspace project
  • pixi global add: Adds dependencies to global environment (user-level)

​
Global Manifest Location

The global manifest is stored at:
  • Unix: ~/.pixi/manifests/pixi-global.toml
  • Windows: %USERPROFILE%\.pixi\manifests\pixi-global.toml

​
Config Options

​
--tls-no-verify
boolean
Disable TLS certificate verification.
​
--auth-file
string
Path to authentication file.
pixi global add --environment myenv numpy --tls-no-verify

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us