Difference Between composer.json and composer.lock

In every Laravel project, you will have two files, composer.json and composer.lock. What is the difference between them?

In composer.json you specify what packages should be installed, and with what versions. For example:

{
    "require": {
        laravel/breeze": "^1.19",
    },
}

This tells the composer to install the larave/breeze package, with version higher than 1.19.

For all the possible syntax options of ^ and * symbols for the versions, check Composer documentation here.

Now, which exact version is installed at any moment? Here comes the composer.lock file.

When you run the composer install command, it checks the composer.lock for the exact locked package version which has been already installed previously, during the previous composer install.

For example:

{
    // ...
    "name": "laravel/breeze",
    "version": "v1.19.1",
    "source": {
        "type": "git",
        "url": "https://github.com/laravel/breeze.git",
        "reference": "4bbb1ea3476901c4f5fc706f8d80e4eac31c3afb"
    },
    "dist": {
        "type": "zip",
        "url": "https://api.github.com/repos/laravel/breeze/zipball/4bbb1ea3476901c4f5fc706f8d80e4eac31c3afb",
        "reference": "4bbb1ea3476901c4f5fc706f8d80e4eac31c3afb",
        "shasum": ""
    },
    // ...
}

Here, you can see that Laravel Breeze v1.19.1 was installed the last time.

When you run the composer update command, the composer checks if there is a newer package, and if there is, downloads the new package version and updates the composer.lock content with the new version.

You can see the composer.lock difference for the laravel/breeze package after running composer update, which updated the package version from 1.19.1 to 1.19.2 below:

TIP: On production servers, always use composer install and never composer update, because sometimes updating packages without testing could break your application. Use composer update locally, then commit the updated composer.lock to the repository, and then run composer install on the production server.