pixi.lock File Format

Understanding the pixi.lock file format

The pixi.lock file is a lock file that records the exact versions of all packages installed in your environments. It ensures reproducible installations across different machines and over time.

Overview

The lock file is automatically generated by pixi and should be committed to version control. It contains:

• Exact package versions and builds
• Package URLs and hashes
• Dependency relationships
• Platform-specific packages
• Environment configurations

The lock file format is considered internal and may change between pixi versions. Do not manually edit the lock file.

Lock File Location

The lock file is always named pixi.lock and placed in the workspace root, next to pixi.toml or pyproject.toml.

my-workspace/
├── pixi.toml
├── pixi.lock       # Lock file
└── .pixi/
    └── envs/

When is it Generated?

The lock file is created or updated when:

• Running pixi install
• Running pixi add or pixi remove
• Running pixi run (if lock file is outdated)
• Running pixi update
• Manually running pixi lock

The lock file is not updated when:

• Using --frozen flag
• Using --locked flag (fails instead if outdated)
• Lock file is already up-to-date with manifest

File Format

The lock file uses a custom TOML-based format optimized for readability and merge-friendliness.

Basic Structure

version = 6

[metadata]
channels = ["conda-forge", "pytorch"]
platforms = ["linux-64", "osx-64", "win-64"]

[environments]
default = ["default"]

[[package]]
name = "python"
version = "3.11.8"
build = "h2628c8c_0_cpython"
subdir = "linux-64"
url = "https://conda.anaconda.org/conda-forge/linux-64/python-3.11.8-h2628c8c_0_cpython.conda"
sha256 = "..."
md5 = "..."
depends = [
  "bzip2 >=1.0.8,<2.0a0",
  "ld_impl_linux-64 >=2.36.1",
  "libexpat >=2.5.0,<3.0a0",
  "libffi >=3.4,<4.0a0",
]

[[package]]
name = "numpy"
version = "1.26.4"
# ... more packages ...

Metadata Section

[metadata]
channels = ["conda-forge"]
platforms = ["linux-64", "osx-64"]
content_hash = "..."

Contains:

• channels - Channels used during solve
• platforms - Target platforms
• content_hash - Hash of manifest content for validation

Environments Section

[environments]
default = ["default"]
test = ["default", "test"]
prod = ["default", "prod"]

Maps environment names to their feature lists.

Package Entries

Each package is recorded with complete information:

[[package]]
name = "numpy"
version = "1.26.4"
build = "py311h64a7726_0"
build_number = 0
subdir = "linux-64"
url = "https://conda.anaconda.org/conda-forge/linux-64/numpy-1.26.4-py311h64a7726_0.conda"
sha256 = "abc123..."
md5 = "def456..."
size = 8589934
timestamp = 1707139200000
depends = [
  "libblas >=3.9.0,<4.0a0",
  "libcblas >=3.9.0,<4.0a0",
  "python >=3.11,<3.12.0a0",
]
license = "BSD-3-Clause"
license_family = "BSD"

Key fields:

• name - Package name
• version - Exact version
• build - Build string
• build_number - Build number
• subdir - Platform (linux-64, osx-64, etc.)
• url - Download URL
• sha256 / md5 - Checksums for verification
• size - Package size in bytes
• timestamp - Build timestamp
• depends - Runtime dependencies

PyPI Packages

PyPI packages are recorded separately:

[[pypi-package]]
name = "requests"
version = "2.31.0"
url = "https://files.pythonhosted.org/packages/.../requests-2.31.0-py3-none-any.whl"
sha256 = "..."
requires-dist = [
  "charset-normalizer<4,>=2",
  "idna<4,>=2.5",
  "urllib3<3,>=1.21.1",
  "certifi>=2017.4.17",
]

Version Control

Should I Commit pixi.lock?

Yes! Always commit pixi.lock to version control.

Why commit the lock file?

• Reproducibility: Ensures everyone gets the same package versions
• Determinism: Builds are consistent across environments
• History: Track dependency changes over time
• Debugging: Know exactly what versions were used
• CI/CD: Reliable automated builds

Lock file in .gitignore?

No! Do not add pixi.lock to .gitignore.

Only ignore environment directories:

# .gitignore
.pixi/
.pixi.lock  # Don't do this!

Handling Merge Conflicts

If you get a merge conflict in pixi.lock:

1. Accept either version:

   git checkout --theirs pixi.lock  # Or --ours
   

2. Regenerate lock file:

   pixi install
   

3. Commit resolved lock file:

   git add pixi.lock
   git commit
   

The lock file format is designed to minimize merge conflicts, but when they occur, regenerating is the safest approach.

Lock File Commands

Update lock file

# Update all packages
pixi update

# Update specific packages
pixi update numpy pandas

# Update without installing
pixi lock

Use existing lock file

# Install from lock file (don't update)
pixi install --frozen

# Fail if lock file is outdated
pixi install --locked

Validate lock file

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

Lock File vs Manifest

Understanding the difference:

Aspect	Manifest (pixi.toml)	Lock File (pixi.lock)
Purpose	Declare requirements	Record exact versions
Format	TOML	TOML (internal format)
Edit	Manually	Automatically
Commit	Yes	Yes
Versions	Constraints (>=1.20)	Exact (1.26.4)
Hashes	No	Yes
URLs	No	Yes

Reproducibility

The lock file provides reproducibility through:

1. Exact versions: No version ranges, specific builds
2. Checksums: SHA256/MD5 hashes verify package integrity
3. URLs: Direct download links (with fallbacks)
4. Dependencies: Full dependency tree recorded
5. Platforms: Platform-specific packages for each target

Example: Reproducible CI

# .github/workflows/test.yml
name: Test
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - uses: prefix-dev/setup-pixi@v0.8.0
      
      - name: Install dependencies
        run: pixi install --frozen  # Use lock file exactly
      
      - name: Run tests
        run: pixi run test

Lock File Optimization

Pixi optimizes the lock file for:

• Merge-friendliness: Deterministic ordering
• Readability: Human-readable TOML
• Size: Compressed format for large dependency trees
• Performance: Fast parsing and lookup

Troubleshooting

Lock file is out of date

Error: “Lock file is out of date with the manifest”

Solution:

pixi install  # Regenerate lock file

Lock file conflicts in merge

Problem: Git merge conflict in pixi.lock

Solution:

# Accept one version
git checkout --theirs pixi.lock

# Regenerate
pixi install

# Commit
git add pixi.lock
git commit

Lock file is huge

Problem: Lock file is very large

Cause: Large dependency trees, many platforms

Solution:

• Reduce number of platforms if not needed
• Consider splitting environments
• This is normal for complex projects

Corrupted lock file

Error: “Failed to parse lock file”

Solution:

# Delete and regenerate
rm pixi.lock
pixi install

Related Commands

• pixi install - Install from lock file
• pixi update - Update lock file
• pixi lock - Generate lock file without installing

Related Configuration

• --frozen - Don’t update lock file
• --locked - Require up-to-date lock file
• PIXI_FROZEN - Environment variable