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.

Pixi provides several global options that can be used with any command. These options control logging, output formatting, and other cross-cutting concerns.

​
Global Options

​
--help

​
--help
boolean
Display help information for the command.Aliases: -h
pixi --help
pixi add --help
pixi run --help

​
--verbose

​
--verbose
count
Increase logging verbosity. Can be specified multiple times for more detail.Aliases: -vLevels:
  • -v - Show warnings
  • -vv - Show info messages
  • -vvv - Show debug messages
  • -vvvv - Show trace messages
pixi install -v          # Show warnings
pixi install -vv         # Show info
pixi install -vvv        # Show debug
pixi install -vvvv       # Show trace (everything)

​
--quiet

​
--quiet
count
Decrease logging verbosity (quiet mode). Suppresses all output except errors.Aliases: -q
pixi install --quiet
pixi install -q
--quiet overrides --verbose if both are specified.

​
--color

​
--color
enum
default:"auto"
Control colored output in the terminal.Values:
  • auto - Automatically detect if colors are supported
  • always - Always use colors
  • never - Never use colors
Environment variable: PIXI_COLOR
pixi install --color never
pixi list --color always

​
--no-progress

​
--no-progress
boolean
default:"false"
Hide all progress bars. Automatically enabled if stderr is not a terminal.Environment variable: PIXI_NO_PROGRESS
pixi install --no-progress
Useful in CI/CD environments:
# GitHub Actions
pixi install --no-progress

​
Configuration Options

These options are available on commands that work with workspaces.

​
--manifest-path

​
--manifest-path
path
The path to pixi.toml, pyproject.toml, or the workspace directory.
pixi install --manifest-path /path/to/pixi.toml
pixi add numpy --manifest-path ./my-workspace
If not specified, pixi searches for a manifest file in the current directory and parent directories.

​
Lock File Options

These options control how pixi interacts with the lock file.

​
--frozen

​
--frozen
boolean
Install the environment as defined in the lockfile without updating it.Environment variable: PIXI_FROZEN
pixi install --frozen
pixi run --frozen test
Use cases:
  • CI/CD: Ensure reproducible builds
  • Production: Deploy exact versions from lock file
  • Offline: Install without network access (if cache is populated)

​
--locked

​
--locked
boolean
Check if lockfile is up-to-date before installing. Aborts if lockfile is outdated.Environment variable: PIXI_LOCKED
pixi install --locked
pixi run --locked test
Use cases:
  • CI/CD: Fail if dependencies have changed
  • Team development: Enforce lock file updates before running
  • Validation: Verify lock file matches manifest

​
Differences: --frozen vs --locked

Behavior: Uses the existing lock file without updating it.When to use:
  • Production deployments
  • CI/CD pipelines
  • When you want exact reproducibility
Effect:
  • Lock file is never updated
  • Installs proceed even if manifest has changed
  • Fast: skips dependency resolution
# CI/CD example
pixi install --frozen
pixi run --frozen test
Behavior: Checks if lock file is up-to-date with manifest, fails if not.When to use:
  • Catching uncommitted dependency changes
  • Enforcing lock file discipline
  • Pre-commit checks
Effect:
  • Lock file is never updated
  • Fails if manifest has changed since lock file was generated
  • Ensures lock file matches manifest
# Pre-commit hook example
pixi install --locked || {
  echo "Lock file is out of date!"
  echo "Run: pixi install"
  exit 1
}
Behavior: Updates lock file if needed, then installs.When to use:
  • Local development
  • After adding/removing dependencies
  • Normal workflow
Effect:
  • Lock file is updated if manifest changed
  • Always installs latest compatible versions
# Development workflow
pixi add numpy
pixi install  # Updates lock file

​
Examples

​
Basic usage

# Verbose installation
pixi install -vv

# Quiet mode (only errors)
pixi run -q test

# No colors in CI
pixi list --color never

​
CI/CD configuration

#!/bin/bash
# Typical CI setup

pixi install \
  --frozen \
  --no-progress \
  --color never \
  --quiet

pixi run --frozen test

​
Development workflow

# Check if lock file is up-to-date
pixi install --locked

# If outdated, update it
if [ $? -ne 0 ]; then
  pixi install
  git add pixi.lock
  git commit -m "Update lock file"
fi

​
Custom manifest location

# Work with multiple workspaces
pixi install --manifest-path ./workspace-a/pixi.toml
pixi install --manifest-path ./workspace-b/pixi.toml

# Run task from specific workspace
pixi run --manifest-path ./api/pixi.toml test

​
Debugging

# Maximum verbosity
pixi install -vvvv

# With Rust logging
RUST_LOG=debug pixi install -vvv

# With backtraces
RUST_BACKTRACE=1 pixi run test

​
Combining Options

Global options can be combined: 
# Frozen install with progress bars hidden
pixi install --frozen --no-progress

# Verbose locked check with no colors
pixi install --locked -vv --color never

# Quiet frozen run
pixi run --frozen --quiet test

​
Option Precedence

When the same setting is specified multiple ways, pixi uses this precedence (highest to lowest):
  1. Command-line flags (e.g., --frozen)
  2. Environment variables (e.g., PIXI_FROZEN=true)
  3. Configuration file (e.g., config.toml)
  4. Defaults
Example: 
# CLI flag overrides environment
export PIXI_FROZEN=false
pixi install --frozen  # Uses frozen mode

# Environment variable used if no flag
export PIXI_FROZEN=true
pixi install  # Uses frozen mode

Build docs developers (and LLMs) love

Get started for freeTalk to us