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 upgrade command upgrades dependencies by loosening version constraints in the manifest, then updating the lock file.

​
Usage

pixi upgrade [OPTIONS] [PACKAGES]...

​
Overview

The pixi upgrade command:
  1. Loosens version constraints in the manifest
  2. Updates the lock file with newer versions
  3. Modifies pixi.toml or pyproject.toml
  4. Installs upgraded environments (unless --no-install)
Unlike pixi update, pixi upgrade modifies your manifest file. Always review changes before committing.

​
Upgrade vs Update

Featurepixi upgradepixi update
Modifies manifest✓ Yes✗ No
Loosens constraints✓ Yes✗ No
Updates lock file✓ Yes✓ Yes
Can do major version bumps✓ Yes✗ No
Safe for automation⚠ Caution✓ Yes
# Update: Respects manifest constraints
pixi update numpy  # 1.26.0 → 1.26.4 (within >=1.20,<2.0)

# Upgrade: Loosens constraints
pixi upgrade numpy  # 1.26.4 → 2.0.0 (updates manifest to >=2.0,<3)

​
Arguments

​
PACKAGES
string
Specific package(s) to upgrade. If not provided, all packages are upgraded.
pixi upgrade              # Upgrade all packages
pixi upgrade numpy        # Upgrade only numpy
pixi upgrade numpy pandas # Upgrade numpy and pandas

​
Options

​
Feature Filter

​
--feature
string
Upgrade packages in specific feature. If not specified, all features are upgraded.Short flag: -f
pixi upgrade --feature test
pixi upgrade -f dev

​
Package Exclusion

​
--exclude
string
Exclude specific package(s) from upgrade. Can be specified multiple times. Conflicts with positional packages.
pixi upgrade --exclude python
pixi upgrade --exclude python --exclude cuda

​
Installation Control

​
--no-install
boolean
default:"false"
Update manifest and lock file without installing.
pixi upgrade --no-install
pixi install  # Install later
​
--dry-run
boolean
default:"false"
Show what would be upgraded without making changes.Short flag: -n
pixi upgrade --dry-run

​
Lock File Usage

​
--frozen
boolean
default:"false"
Don’t update the lock file.Env: PIXI_FROZEN
​
--locked
boolean
default:"false"
Require lock file to be up-to-date.Env: PIXI_LOCKED
Using --frozen or --locked with pixi upgrade will not make changes or display results. Use --dry-run instead.

​
Output Format

​
--json
boolean
default:"false"
Output changes in JSON format.
pixi upgrade --json > changes.json

​
Examples

​
Upgrade All Packages

pixi upgrade
Before pixi.toml: 
[dependencies]
python = "3.11.*"
numpy = ">=1.20,<2.0"
pandas = ">=1.5,<2.0"
Output: 
✓ Upgraded 2 packages:
  • numpy: 1.26.4 → 2.0.0
  • pandas: 1.5.3 → 2.2.0
After pixi.toml: 
[dependencies]
python = "3.11.*"
numpy = ">=2.0.0,<3"
pandas = ">=2.2.0,<3"

​
Upgrade Specific Package

pixi upgrade numpy
Before: 
[dependencies]
numpy = ">=1.20,<2.0"
Output: 
✓ Upgraded numpy: 1.26.4 → 2.0.0
After: 
[dependencies]
numpy = ">=2.0.0,<3"

​
Upgrade Multiple Packages

pixi upgrade numpy pandas
Output: 
✓ Upgraded 2 packages:
  • numpy: 1.26.4 → 2.0.0
  • pandas: 1.5.3 → 2.2.0

​
Upgrade with Exclusions

pixi upgrade --exclude python --exclude cuda
Upgrades all packages except python and cuda.

​
Upgrade Specific Feature

pixi upgrade --feature test
Before: 
[feature.test.dependencies]
pytest = ">=7.0,<8"
pytest-cov = ">=4.0,<5"
Output: 
✓ Upgraded test feature:
  • pytest: 7.4.0 → 8.0.0
  • pytest-cov: 4.1.0 → 5.0.0
After: 
[feature.test.dependencies]
pytest = ">=8.0.0,<9"
pytest-cov = ">=5.0.0,<6"

​
Dry Run

Preview changes without modifying files: 
pixi upgrade --dry-run
Output: 
Would upgrade 3 packages:
  • numpy: 1.26.4 → 2.0.0
  • pandas: 1.5.3 → 2.2.0
  • scipy: 1.11.0 → 1.13.0

No files would be modified

​
JSON Output

pixi upgrade --json
Output: 
{
  "version": "1",
  "environments": {
    "default": {
      "linux-64": {
        "updated": [
          {
            "name": "numpy",
            "before": "1.26.4",
            "after": "2.0.0"
          }
        ]
      }
    }
  }
}

​
No Upgrades Available

pixi upgrade
Output: 
✓ All packages are already up-to-date

​
Upgrade Behavior

​
Version Specification Types

​
Detailed Version Spec

Before: 
[dependencies]
numpy = { version = ">=1.20,<2.0", channel = "conda-forge" }
After upgrade: 
[dependencies]
numpy = { version = ">=2.0.0,<3", channel = "conda-forge" }
Only version is updated, other fields preserved.

​
Simple Version Spec

Before: 
[dependencies]
numpy = ">=1.20,<2.0"
After upgrade: 
[dependencies]
numpy = ">=2.0.0,<3"

​
Non-Version Specs

These are not upgraded: 
[dependencies]
mypackage = { git = "https://github.com/user/repo" }
anotherpackage = { url = "https://example.com/package.tar.bz2" }
localpackage = { path = "./local" }
Output: 
✓ All packages are already up-to-date

​
PyProject.toml Handling

For pyproject.toml projects, pixi checks for python in tool.pixi.dependencies: 
[project]
dependencies = [
  "numpy>=1.20",
]

[tool.pixi.dependencies]
# python NOT specified here

pixi upgrade python
Output: 
✓ All packages are already up-to-date
Python is not upgraded because it’s not in tool.pixi.dependencies.

​
Platform-Specific Upgrades

For platform-specific dependencies: 
[target.linux-64.dependencies]
cuda = ">=11.8,<12"

[target.osx-arm64.dependencies]
metal = "*"

pixi upgrade
Both cuda (linux-64) and metal (osx-arm64) are upgraded. After: 
[target.linux-64.dependencies]
cuda = ">=12.0.0,<13"

[target.osx-arm64.dependencies]
metal = ">=1.0.0,<2"

​
Build Constraints

For detailed specs with build strings: 
[dependencies]
pytorch = { version = ">=2.0,<3", build = "py311*" }
After upgrade: 
[dependencies]
pytorch = { version = ">=2.2.0,<3", build = "py311*" }
Wildcard build strings are preserved. Exact build strings are removed during upgrade.

​
Use Cases

​
Major Version Upgrade

# NumPy 1.x → 2.x
pixi upgrade numpy
pixi run pytest  # Test for breaking changes

​
Refresh All Dependencies

pixi upgrade
Useful after:
  • Long time without updates
  • Major dependency releases
  • Security advisories

​
Upgrade Dev Dependencies Only

pixi upgrade --feature dev

[feature.dev.dependencies]
black = ">=23.0,<24"
ruff = ">=0.1,<0.2"
After: 
[feature.dev.dependencies]
black = ">=24.0.0,<25"
ruff = ">=0.3.0,<0.4"

​
CI/CD Integration

Automatic upgrade checks: 
#!/bin/bash
pixi upgrade --dry-run > upgrade-report.txt
if grep -q "Would upgrade" upgrade-report.txt; then
  echo "Upgrades available"
  exit 1  # Notify team
fi

​
Gradual Migration

Upgrade one package at a time: 
pixi upgrade numpy --dry-run
# Review changes
pixi upgrade numpy
pixi run pytest

pixi upgrade pandas --dry-run
# Review changes
pixi upgrade pandas
pixi run pytest

​
Global Options

​
--manifest-path
string
Path to pixi.toml, pyproject.toml, or workspace directory.Short flag: -m
pixi upgrade --manifest-path /path/to/project

​
Config Options

  • --auth-file <FILE>: Authentication credentials
  • --tls-no-verify: Disable TLS verification
  • --concurrent-solves <N>: Max concurrent solves

​
Troubleshooting

​
Package Not Found

Error: could not find a package named 'numpyy' Solution with suggestions: 
Error: could not find a package named 'numpyy'
Help: did you mean 'numpy', 'numba'?

​
No Upgrades Available

pixi upgrade numpy
Output: 
✓ All packages are already up-to-date
Possible reasons:
  • Already at latest version
  • Package is git/url/path spec (not upgradable)
  • Package not in selected feature

​
Solver Conflicts

Error: cannot solve dependencies Solution: Upgrade dependencies together: 
pixi upgrade numpy pandas scipy
Or use --dry-run to identify conflicts: 
pixi upgrade --dry-run

​
Manifest Not Modified

If manifest is not updated, package might be:
  1. Git dependency: Not upgradable 
    mypackage = { git = "..." }
  2. URL dependency: Not upgradable 
    mypackage = { url = "..." }
  3. Path dependency: Not upgradable 
    mypackage = { path = "..." }
  4. Python in pyproject.toml: Must be in tool.pixi.dependencies

​
Best Practices

  1. Always use —dry-run first: 
    pixi upgrade --dry-run
pixi upgrade  # If changes look good
  2. Test after upgrades: 
    pixi upgrade
pixi run pytest
pixi run myapp  # Integration testing
  3. Upgrade gradually for large projects: 
    pixi upgrade numpy --dry-run
pixi upgrade numpy
# Test
pixi upgrade pandas --dry-run
pixi upgrade pandas
# Test
  4. Review manifest changes: 
    pixi upgrade
git diff pixi.toml
  5. Commit manifest and lock together: 
    pixi upgrade
git add pixi.toml pixi.lock
git commit -m "Upgrade numpy to 2.0"
  6. Use feature isolation: 
    pixi upgrade --feature dev    # Safe
pixi upgrade --feature test   # Test changes
pixi upgrade                  # Production
  7. Document breaking changes: 
    pixi upgrade numpy
# Document in CHANGELOG.md
echo "- Upgraded NumPy to 2.0 (breaking changes in API)" >> CHANGELOG.md

​
Common Workflows

​
Security Update Workflow

# Check for vulnerable package
pixi upgrade requests --dry-run

# Upgrade if safe
pixi upgrade requests

# Test
pixi run pytest

# Commit
git add pixi.toml pixi.lock
git commit -m "Security: Upgrade requests"

​
Major Version Migration

# Upgrade in test environment first
pixi upgrade numpy --feature test
pixi run -e test pytest

# If successful, upgrade in default
pixi upgrade numpy
pixi run pytest

​
Quarterly Maintenance

# Upgrade all packages
pixi upgrade --dry-run > upgrade-plan.txt

# Review plan with team
cat upgrade-plan.txt

# Execute upgrade
pixi upgrade

# Full test suite
pixi run pytest
pixi run integration-tests

# Commit
git add pixi.toml pixi.lock
git commit -m "Q1 2024 dependency upgrades"

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us