Introduction

The short answer: Yes, commit composer.lock for applications. No, don't commit it for libraries. The lock file records the exact versions of every dependency installed, ensuring all developers and deployment environments use identical packages. This distinction between applications and libraries is important because they have fundamentally different dependency resolution needs.

For Applications: Always Commit

When building a deployable application (website, API, CLI tool), commit composer.lock:

git add composer.lock
git commit -m "Lock dependencies to tested versions"

Why?

• Reproducible builds: composer install reads composer.lock and installs the exact versions recorded. Without the lock file, composer install falls back to composer update behavior, resolving the latest compatible versions — which may differ from what was tested.
• Team consistency: Every developer gets identical dependencies, eliminating "works on my machine" issues.
• Deployment safety: Production gets the same packages that passed CI, not whatever versions happen to be latest at deploy time.

The Workflow

1# Developer A adds a new package
2composer require guzzlehttp/guzzle
3# This updates composer.json AND composer.lock
4git add composer.json composer.lock
5git commit -m "Add Guzzle HTTP client"
6
7# Developer B pulls and installs
8git pull
9composer install  # Installs exact versions from lock file
10
11# Updating dependencies (intentional)
12composer update  # Resolves latest compatible versions, updates lock file
13git add composer.lock
14git commit -m "Update dependencies"

For Libraries: Don't Commit

When building a reusable library (a Composer package that others require), do not commit composer.lock:

# .gitignore for a library
composer.lock

Why?

• Libraries should be flexible: A library's composer.json defines version constraints (^8.0). The consuming application's composer.lock determines the actual installed version.
• Testing across versions: Without a lock file, CI tests the library against the latest compatible dependencies, catching compatibility issues early.
• Avoiding conflicts: If a library ships with a lock file, contributors may get confused about whether to use install or update.

install vs update

1# Update a specific package only
2composer update guzzlehttp/guzzle
3
4# Update all packages
5composer update
6
7# Dry run — see what would change
8composer update --dry-run

CI/CD Pipeline

1# GitHub Actions example
2jobs:
3  test:
4    runs-on: ubuntu-latest
5    steps:
6      - uses: actions/checkout@v4
7
8      - name: Install dependencies
9        run: composer install --no-interaction --prefer-dist --no-progress
10
11      # For libraries (no lock file), use:
12      # run: composer update --no-interaction --prefer-dist --no-progress
13
14      - name: Run tests
15        run: vendor/bin/phpunit

Use composer install (not update) in CI for applications to ensure deterministic builds.

Handling Merge Conflicts

composer.lock is a large JSON file that often conflicts during merges:

1# After a merge conflict in composer.lock
2# Option 1: Accept either version, then re-resolve
3git checkout --theirs composer.lock
4composer update --lock
5
6# Option 2: Delete and regenerate
7rm composer.lock
8composer install
9git add composer.lock

Comparison with Other Ecosystems

The same principle applies across all ecosystems: commit lock files for deployable applications, omit them for reusable libraries.

Common Pitfalls

• Running composer update in production: Always use composer install in production. composer update may pull in untested versions.
• Ignoring lock file changes: If composer.lock changes unexpectedly in a PR, review the diff — a dependency may have been updated intentionally or accidentally.
• Outdated lock file: If composer.json is edited manually (changing version constraints), run composer update to sync the lock file. A stale lock file causes composer install warnings.
• Platform requirements: composer.lock records the PHP version and extensions available at lock time. Deploying on a different PHP version may cause issues. Use config.platform.php in composer.json to pin the target PHP version.
• --no-dev in production: Use composer install --no-dev for production to skip development dependencies (PHPUnit, debugging tools).

Summary

• Applications: Always commit composer.lock for reproducible, deterministic builds
• Libraries: Don't commit composer.lock — let consuming applications resolve versions
• Use composer install for installing from the lock file (daily development, CI, deployment)
• Use composer update only for intentional dependency version changes
• The same application-vs-library rule applies in npm, Yarn, Poetry, Bundler, and Cargo