> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/zhcndoc/bun/llms.txt
> Use this file to discover all available pages before exploring further.

# Lockfile

Bun's lockfile locks package versions for reproducible installs.

## Lockfile formats

Bun supports two lockfile formats:

### Binary lockfile (bun.lockb)

Default format. Fast to read/write, compact size.

```bash theme={null}
$ ls -lh bun.lockb
-rw-r--r-- 1 user user 147K Dec 1 10:00 bun.lockb
```

### Text lockfile (bun.lock)

Human-readable format, better for version control diffs.

```bash theme={null}
$ ls -lh bun.lock  
-rw-r--r-- 1 user user 456K Dec 1 10:00 bun.lock
```

## Choosing a format

### Binary lockfile (default)

Best for:

* Large projects with many dependencies
* Faster CI/CD pipelines
* Private projects with less merge conflicts

Advantages:

* **3x faster** to parse
* **3x smaller** file size
* Less disk I/O

Disadvantages:

* Not human-readable
* Binary diffs in version control

### Text lockfile

Best for:

* Open source projects
* Projects requiring human review of dependency changes
* Better git diffs

Advantages:

* Human-readable
* Reviewable diffs
* Easy to debug

Disadvantages:

* Larger file size
* Slower parsing

## Configuration

### Use text lockfile

#### Via bunfig.toml

```toml theme={null}
[install]
saveTextLockfile = true
```

#### Via CLI flag

Generate text lockfile on next install:

```bash theme={null}
bun install --save-text-lockfile
```

### Convert formats

Convert binary to text:

```bash theme={null}
# With existing bun.lockb
bun install --save-text-lockfile
```

Convert text to binary:

```bash theme={null}
# Delete text lockfile
rm bun.lock

# Install to create binary lockfile
bun install
```

Or configure in `bunfig.toml`:

```toml theme={null}
[install]
saveTextLockfile = false
```

## Lockfile behavior

### Automatic generation

Bun automatically creates/updates the lockfile:

```bash theme={null}
$ bun install
$ ls
bun.lockb  package.json  node_modules/
```

### Lockfile updates

The lockfile updates when:

* Installing new packages
* Removing packages
* Updating package versions
* Changing version ranges in `package.json`

### Frozen lockfile

Prevent lockfile updates (useful in CI):

```bash theme={null}
bun install --frozen-lockfile
```

Fails if lockfile is out of sync with `package.json`.

#### Via bunfig.toml

```toml theme={null}
[install]
frozenLockfile = true
```

### No lockfile

Install without creating/updating lockfile:

```bash theme={null}
bun install --no-save
```

## Lockfile structure

### Binary lockfile

Binary format (not human-readable):

```bash theme={null}
$ file bun.lockb
bun.lockb: data
```

### Text lockfile format

```yaml theme={null}
# bun.lock
name: my-app
version: 1.0.0

packages:
  react@18.2.0:
    resolved: https://registry.npmjs.org/react/-/react-18.2.0.tgz
    integrity: sha512-...
    dependencies:
      loose-envify: 1.4.0
  
  typescript@5.0.0:
    resolved: https://registry.npmjs.org/typescript/-/typescript-5.0.0.tgz
    integrity: sha512-...
```

## Lockfile commands

### View lockfile hash

```bash theme={null}
$ bun pm hash
f3d8b2a1c4e5d6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1
```

The hash represents the lockfile state.

### View hash string

```bash theme={null}
$ bun pm hash-string
packages|react@18.2.0|react-dom@18.2.0|typescript@5.0.0
```

### Print stored hash

```bash theme={null}
$ bun pm hash-print
f3d8b2a1c4e5d6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1
```

## Migration

### From other package managers

Migrate existing lockfiles:

```bash theme={null}
bun pm migrate
```

Supported lockfiles:

* `package-lock.json` (npm)
* `yarn.lock` (Yarn)
* `pnpm-lock.yaml` (pnpm)

Example:

```bash theme={null}
$ bun pm migrate
Migrated from package-lock.json to bun.lock
```

Force migration (overwrite existing):

```bash theme={null}
bun pm migrate --force
```

## Version control

### Commit lockfile

Always commit your lockfile:

```bash theme={null}
git add bun.lockb  # or bun.lock
git commit -m "Lock dependencies"
```

### Ignore lockfile (not recommended)

If you must ignore lockfile:

```gitignore theme={null}
# .gitignore
bun.lockb
bun.lock
```

**Warning:** This makes installs non-reproducible.

## CI/CD

### GitHub Actions

Cache and use lockfile:

```yaml theme={null}
name: CI
on: [push]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - uses: oven-sh/setup-bun@v1
      
      - name: Install dependencies
        run: bun install --frozen-lockfile
      
      - name: Run tests
        run: bun test
```

### GitLab CI

```yaml theme={null}
image: oven/bun:latest

before_script:
  - bun install --frozen-lockfile

test:
  script:
    - bun test
```

## Troubleshooting

### Lockfile out of sync

If lockfile doesn't match `package.json`:

```bash theme={null}
$ bun install --frozen-lockfile
error: lockfile out of sync with package.json
```

Fix:

```bash theme={null}
bun install
git add bun.lockb
git commit -m "Update lockfile"
```

### Merge conflicts

For binary lockfile conflicts:

```bash theme={null}
# Use their version
git checkout --theirs bun.lockb
bun install

# Or use our version
git checkout --ours bun.lockb  
bun install

# Or regenerate
rm bun.lockb
bun install
```

For text lockfile conflicts:

```bash theme={null}
# Resolve in editor
vim bun.lock

# Or regenerate
rm bun.lock
bun install
```

### Corrupted lockfile

If lockfile is corrupted:

```bash theme={null}
rm bun.lockb  # or bun.lock
bun install
```

### Different machines

If lockfile differs between machines:

1. Ensure same Bun version:

```bash theme={null}
bun --version
```

2. Use same registry:

```toml theme={null}
# bunfig.toml
[install]
registry = "https://registry.npmjs.org/"
```

3. Regenerate lockfile:

```bash theme={null}
rm bun.lockb
bun install
```

## Custom lockfile path

### Set lockfile path

```toml theme={null}
[install.lockfile]
path = "custom.lockb"
```

Or:

```toml theme={null}
[install.lockfile]  
path = "locks/dependencies.lock"
```

### Save lockfile to different location

```toml theme={null}
[install.lockfile]
savePath = "locks/bun.lock"
```

## Workspaces

In workspace projects, use a single root lockfile:

```
my-monorepo/
├── package.json
├── bun.lockb          # Shared lockfile
├── packages/
│   ├── app/
│   │   └── package.json
│   └── shared/
│       └── package.json
```

All workspace dependencies are tracked in the root lockfile.

## Performance

### Binary lockfile

* **Read time**: \~5-10ms for 1000 packages
* **Write time**: \~10-20ms for 1000 packages
* **File size**: \~100-200KB for 1000 packages

### Text lockfile

* **Read time**: \~15-30ms for 1000 packages
* **Write time**: \~30-60ms for 1000 packages
* **File size**: \~300-600KB for 1000 packages

## Best practices

### Always commit lockfile

```bash theme={null}
git add bun.lockb
git commit -m "Update dependencies"
```

### Use frozen lockfile in CI

```yaml theme={null}
run: bun install --frozen-lockfile
```

### Review lockfile changes

For text lockfiles:

```bash theme={null}
git diff bun.lock
```

Check for:

* Unexpected version changes
* New dependencies
* Removed dependencies

### Regenerate periodically

Regenerate lockfile to clean up:

```bash theme={null}
rm bun.lockb
bun install
```

### Use text lockfile for open source

Easier for contributors to review:

```toml theme={null}
[install]
saveTextLockfile = true
```

## Examples

### Enable text lockfile

```toml theme={null}
# bunfig.toml
[install]
saveTextLockfile = true
```

```bash theme={null}
bun install
ls
# bun.lock  package.json  node_modules/
```

### Switch to binary lockfile

```toml theme={null}
# bunfig.toml
[install]
saveTextLockfile = false
```

```bash theme={null}
rm bun.lock
bun install
ls
# bun.lockb  package.json  node_modules/
```

### Frozen lockfile

```bash theme={null}
$ bun install --frozen-lockfile
bun install v1.0.0

 134 packages installed [1.42s]
```

### Migrate from npm

```bash theme={null}
$ ls
package.json  package-lock.json  node_modules/

$ bun pm migrate
Migrated from package-lock.json to bun.lock

$ ls
package.json  bun.lock  node_modules/
```