pixi self-update

The pixi self-update command updates the pixi binary to the latest version or downgrades to a specific version.

Usage

pixi self-update [OPTIONS]

Options

Version Selection

--version

string

Specify the desired version to upgrade or downgrade to.Format: X.Y.Z (without leading ‘v’)If not specified, updates to the latest version.

pixi self-update --version 0.25.0
pixi self-update  # Updates to latest

Leading ‘v’ characters are automatically removed if provided (e.g., v0.25.0 becomes 0.25.0).

Dry Run

--dry-run

boolean

default:"false"

Show what would be updated without actually modifying the binary.Displays release notes and version changes without performing the update.

pixi self-update --dry-run
pixi self-update --version 0.24.0 --dry-run

Example output:

📝 Release notes for version 0.25.0 (2024-03-15):

## Added
- New workspace command for managing projects
- Support for import command

## Fixed
- Lock file consistency issues
- Windows path handling

ℹ️  Pixi version would be updated from 0.24.0 to 0.25.0, but `--dry-run` given.

Force Update

--force

boolean

default:"false"

Force download and replace even if versions match.

With --version: Downloads specified version even if it’s already installed
Without --version: Always downloads and replaces with the latest version

pixi self-update --force
pixi self-update --version 0.25.0 --force

Skip Release Notes

--no-release-note

boolean

default:"false"

Skip printing release notes during update.Useful for automated scripts or CI/CD pipelines.

pixi self-update --no-release-note

Behavior

Automatic Version Detection

When no --version is specified:

pixi self-update

Fetches the latest release from GitHub
Compares with current version
Downloads and installs if newer version is available

Version Comparison

The command handles different scenarios:

Up to date: No action taken, displays current version
Upgrade: Newer version available, downloads and installs
Downgrade: Older version specified, prompts for confirmation (unless --force or --version is used)

Downgrade Confirmation

When downgrading without explicit version:

# If latest remote is 0.24.0 but you have 0.25.0
pixi self-update

Prompts:

Current version (0.25.0) is more recent than remote (0.24.0). Do you want to downgrade? [y/N]

Skip prompt by specifying version:

pixi self-update --version 0.24.0  # No prompt

Release Notes

By default, release notes are displayed before updating:

📝 Release notes for version 0.25.0 (2024-03-15):

## Added
- New import command for environment files
- Workspace subcommands for manifest management

## Changed
- Improved lock file performance

## Fixed
- Resolved platform-specific installation issues

✅ Pixi will be updated from 0.24.0 to 0.25.0
✅ Pixi archive downloaded.
✅ Pixi archive uncompressed.
✅ Pixi has been updated to version 0.25.0.

Examples

Update to Latest Version

pixi self-update

Output:

✅ Pixi will be updated from 0.24.0 to 0.25.0
✅ Pixi archive downloaded.
✅ Pixi archive uncompressed.
✅ Pixi has been updated to version 0.25.0.

Check for Updates (Dry Run)

pixi self-update --dry-run

Shows what would be updated without changing anything.

Update to Specific Version

pixi self-update --version 0.24.0

Downloads and installs version 0.24.0.

Downgrade to Older Version

pixi self-update --version 0.23.0

Downgrades from current version to 0.23.0 (prompts for confirmation if needed).

Force Reinstall Current Version

pixi self-update --force

Redownloads and reinstalls even if already on the latest version.

Silent Update (No Release Notes)

pixi self-update --no-release-note

Updates without displaying release notes.

Automated Update in CI

pixi self-update --no-release-note --force

Ideal for CI/CD pipelines where you always want the latest version.

Platform Support

Supported platforms:

Linux: x86_64-unknown-linux-musl, aarch64-unknown-linux-musl
macOS: x86_64-apple-darwin, aarch64-apple-darwin
Windows: x86_64-pc-windows-msvc, aarch64-pc-windows-msvc

The correct binary is automatically detected based on your system.

Update Process

Fetch version information: Queries GitHub for latest release or specified version
Display release notes: Shows what’s changed (unless --no-release-note)
Download archive: Downloads platform-specific binary archive
Extract binary: Unpacks the archive to temporary directory
Replace binary: Replaces current pixi binary with new version
Verify: New version is immediately available

Troubleshooting

Download Failed

Error: Failed to download the archive Solution: Check internet connection and GitHub availability:

# Try again
pixi self-update

# Or download manually from
# https://github.com/prefix-dev/pixi/releases

Version Not Found

Error: URL returned 404 Solution: Verify the version exists:

# Check available versions at
# https://github.com/prefix-dev/pixi/releases

pixi self-update --version 0.25.0  # Use valid version

Permission Denied

Error: Permission denied when replacing binary Solution: Ensure you have write permissions:

# On Unix systems, you may need to make the binary writable
chmod u+w $(which pixi)
pixi self-update

Already Up to Date

Message: pixi is already up-to-date To reinstall anyway:

pixi self-update --force

Release Notes Failed to Fetch

Warning: Failed to fetch release notes The update continues despite this warning. Check the release page manually:

https://github.com/prefix-dev/pixi/releases/tag/vX.Y.Z

Self-Update Disabled Builds

Some pixi installations (e.g., via package managers like Homebrew, apt, or Conda) may have self-update disabled.

Error message:

This version of pixi was built without self-update support.
Please use your package manager to update pixi.

Solution:

# Homebrew (macOS)
brew upgrade pixi

# Conda
conda update -c conda-forge pixi

# apt (Ubuntu/Debian)
sudo apt update && sudo apt upgrade pixi

# Or download from GitHub
curl -fsSL https://pixi.sh/install.sh | bash

Environment Variables

No environment variables affect pixi self-update.

Exit Codes

0: Success (updated or already up-to-date)
1: Error (download failed, permission denied, etc.)

Security

The self-update mechanism downloads binaries from official GitHub releases at https://github.com/prefix-dev/pixi/releases.

All downloads are verified by:

Using HTTPS for secure transport
Respecting system TLS configuration
Using official GitHub release artifacts

Version Format

Versions follow Semantic Versioning:

Format: MAJOR.MINOR.PATCH
Example: 0.25.0

Do not include the ‘v’ prefix:

# ✅ Correct
pixi self-update --version 0.25.0

# ⚠️ Works but shows warning
pixi self-update --version v0.25.0

Workspace Commands

Environment Commands

Global Commands

Build Commands

Other Commands

pixi self-update

Usage

Options

Version Selection

Dry Run

Force Update

Skip Release Notes

Behavior

Automatic Version Detection

Version Comparison

Downgrade Confirmation

Release Notes

Examples

Update to Latest Version

Check for Updates (Dry Run)

Update to Specific Version

Downgrade to Older Version

Force Reinstall Current Version

Silent Update (No Release Notes)

Automated Update in CI

Platform Support

Update Process

Troubleshooting

Download Failed

Version Not Found

Permission Denied

Already Up to Date

Release Notes Failed to Fetch

Self-Update Disabled Builds

Environment Variables

Exit Codes

Security

Version Format

See Also

Build docs developers (and LLMs) love

Workspace Commands

Environment Commands

Global Commands

Build Commands

Other Commands

Documentation Index

​Usage

​Options

​Version Selection

​Dry Run

​Force Update

​Skip Release Notes

​Behavior

​Automatic Version Detection

​Version Comparison

​Downgrade Confirmation

​Release Notes

​Examples

​Update to Latest Version

​Check for Updates (Dry Run)

​Update to Specific Version

​Downgrade to Older Version

​Force Reinstall Current Version

​Silent Update (No Release Notes)

​Automated Update in CI

​Platform Support

​Update Process

​Troubleshooting

​Download Failed

​Version Not Found

​Permission Denied

​Already Up to Date

​Release Notes Failed to Fetch

​Self-Update Disabled Builds

​Environment Variables

​Exit Codes

​Security

​Version Format

​See Also

Build docs developers (and LLMs) love

Usage

Options

Version Selection

Dry Run

Force Update

Skip Release Notes

Behavior

Automatic Version Detection

Version Comparison

Downgrade Confirmation

Release Notes

Examples

Update to Latest Version

Check for Updates (Dry Run)

Update to Specific Version

Downgrade to Older Version

Force Reinstall Current Version

Silent Update (No Release Notes)

Automated Update in CI

Platform Support

Update Process

Troubleshooting

Download Failed

Version Not Found

Permission Denied

Already Up to Date

Release Notes Failed to Fetch

Self-Update Disabled Builds

Environment Variables

Exit Codes

Security

Version Format

See Also