> ## 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.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

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

## 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

```toml theme={null}
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

```toml theme={null}
[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

```toml theme={null}
[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:

```toml theme={null}
[[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:

```toml theme={null}
[[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.

<Accordion title="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
</Accordion>

<Accordion title="Lock file in .gitignore?">
  **No!** Do not add `pixi.lock` to `.gitignore`.

  Only ignore environment directories:

  ```gitignore theme={null}
  # .gitignore
  .pixi/
  .pixi.lock  # Don't do this!
  ```
</Accordion>

### Handling Merge Conflicts

If you get a merge conflict in `pixi.lock`:

1. **Accept either version**:
   ```bash theme={null}
   git checkout --theirs pixi.lock  # Or --ours
   ```

2. **Regenerate lock file**:
   ```bash theme={null}
   pixi install
   ```

3. **Commit resolved lock file**:
   ```bash theme={null}
   git add pixi.lock
   git commit
   ```

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

## Lock File Commands

### Update lock file

```bash theme={null}
# Update all packages
pixi update

# Update specific packages
pixi update numpy pandas

# Update without installing
pixi lock
```

### Use existing lock file

```bash theme={null}
# Install from lock file (don't update)
pixi install --frozen

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

### Validate lock file

```bash theme={null}
# 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

```yaml theme={null}
# .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

<Accordion title="Lock file is out of date">
  **Error:** "Lock file is out of date with the manifest"

  **Solution:**

  ```bash theme={null}
  pixi install  # Regenerate lock file
  ```
</Accordion>

<Accordion title="Lock file conflicts in merge">
  **Problem:** Git merge conflict in pixi.lock

  **Solution:**

  ```bash theme={null}
  # Accept one version
  git checkout --theirs pixi.lock

  # Regenerate
  pixi install

  # Commit
  git add pixi.lock
  git commit
  ```
</Accordion>

<Accordion title="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
</Accordion>

<Accordion title="Corrupted lock file">
  **Error:** "Failed to parse lock file"

  **Solution:**

  ```bash theme={null}
  # Delete and regenerate
  rm pixi.lock
  pixi install
  ```
</Accordion>

## Related Commands

* [`pixi install`](/commands/install) - Install from lock file
* [`pixi update`](/commands/update) - Update lock file
* [`pixi lock`](/commands/lock) - Generate lock file without installing

## Related Configuration

* [`--frozen`](/reference/cli-options#frozen) - Don't update lock file
* [`--locked`](/reference/cli-options#locked) - Require up-to-date lock file
* [`PIXI_FROZEN`](/reference/environment-variables#pixi_frozen) - Environment variable