How and Why to Use --prefer-dist in Composer for Drupal Projects

Introduction:
When working on Drupal projects, installing and updating dependencies is a crucial step. All external modules and libraries are managed using Composer. The --prefer-dist option helps speed up this process and ensures more stable installations.

What --prefer-dist Does

Composer can fetch packages in two ways:

1. Cloning the Git repository
2. Distribution (package archive)

By default, Composer chooses the method automatically. Using:

composer install --prefer-dist
composer update --prefer-dist

Composer will always download the package as a ready-made archive (zip, tar.gz) instead of cloning the repository.

Benefits:

• Faster installation and updates.
• Less Git resource usage (no commit history is downloaded).
• More stable versions since the archive already contains a specific package version.

Examples for Drupal

Installing dependencies after cloning a project:

git clone https://github.com/example/drupal-project.git
cd drupal-project
composer install --prefer-dist

• Installs exactly the versions of modules locked in composer.lock.
• Ensures all team members have an identical environment.

Adding a new contrib module:

composer require drupal/pathauto --prefer-dist

• Composer downloads the Pathauto module as an archive.
• The module files are ready to use in Drupal, and the dependency is added to composer.json and composer.lock.

When You Might Skip --prefer-dist

Sometimes, cloning the repository is necessary:

• If you need to develop the package itself and make code changes.
• If archives are unavailable (e.g., private repositories without prepared archives).

Otherwise, --prefer-dist is the preferred choice for stable and fast installations.

Conclusion

The --prefer-dist option is a simple yet powerful practice for Drupal and PHP projects. It speeds up dependency installation, reduces system load, and ensures consistent versions for the entire development team.