Why --prefer-dist Matters When Installing Laravel
When you run composer create-project laravel/laravel, Composer defaults to creating a development archive. This means it downloads the source code for every package, including all git history and build artifacts like .git directories. While this is perfect for local development where you might want to inspect source files or debug specific library internals, it creates significant overhead when deploying to production.
The flag --prefer-dist changes Composer's behavior to prioritize distributing packages as compressed archives (.zip or .tar.gz) rather than cloning git repositories. This single addition can reduce the size of your deployment significantly and speed up the initial installation process on the server.
The Default Behavior vs. Distributed Archives
By default, Composer acts as a dependency manager that understands source control. When you install a package without additional flags, Composer often clones the repository to ensure you get the latest changes or specific commits if specified in composer.json. For example, installing a popular package like symfony/http-client might result in a full git clone of the SymfonY repository.
This approach has two main drawbacks for production environments:
- Bloat: Git history adds unnecessary weight to your
vendordirectory. A single package can contain thousands of lines of commit logs that are never read by the application. - Latency: Cloning a large repository takes time and consumes bandwidth, especially on slower connections or when deploying via SSH.
Using --prefer-dist instructs Composer to download the pre-built distribution archive instead. This archive contains only the necessary files required to run the application, stripping out git metadata, test suites, and documentation that is not needed in production.
Implementation in Production Environments
In a typical deployment scenario, you want your vendor directory to be as lean as possible. The command looks like this:
composer create-project laravel/laravel --prefer-dist
However, the flag isn't just about the initial Laravel skeleton. It is equally important when updating dependencies later. If you run composer update, Composer will continue to use source distributions by default unless you explicitly tell it otherwise. To ensure your entire dependency tree remains lean during updates, you should add the flag every time you refresh your vendor directory:
composer update --prefer-dist
It is also possible to make this the default behavior for all future operations by configuring your composer.json file. You can set a custom repository package type or use the config option in composer.json to enforce dist preference globally:
{
"config": {
"prefer-dist": true
}
}
Once this is set, every subsequent command will automatically prioritize distribution archives unless you explicitly override it with --prefer-source.
Trade-offs and When Not to Use It
The decision to use --prefer-dist comes with a specific trade-off: reproducibility during development. If you rely on reading source code directly from the vendor directory to debug a package, having the distribution archive might obscure certain details or make it harder to trace changes back to a specific commit.
Furthermore, if a package relies on build steps that are included in the git repository but not in the distribution archive, you might encounter issues. However, Laravel and most modern PHP packages follow PSR standards where the distribution archive is fully functional without needing the source.
You should generally avoid --prefer-dist during local development unless your machine has very limited disk space. The ability to inspect vendor source code, run tests against specific branches, or contribute back to a library usually requires the source form.
Conclusion
The --prefer-dist flag is a simple but powerful tool for optimizing production deployments. By switching from git clones to compressed archives, you reduce storage usage and improve deployment times without sacrificing application functionality. Just remember to keep your local development environment in --prefer-source mode if you need deep visibility into third-party libraries.