Add Composer to an existing site

Simplified in Drupal 8.8.0

Note: If you started your project using Drupal version 8.8.0 or later, your site already uses the correct file structure and is Composer-ready.

This page is a step-by-step guide to manually adding Composer support to an existing site previously installed without Composer. This guide is for you if you installed Drupal 8 manually from an archive or used a deprecated Composer template such as drupal/drupal.

For Sites Created with Drupal 8.8.0 or Later

Even if you installed Drupal 8.8.0 from an archive, Composer was pre-initialized. Therefore, you should be able to manage your site using Composer without additional conversion steps.

For Sites Created Before Drupal 8.8.0

The composer.json file included in Drupal downloads before 8.8.0 was not intended for Composer-managed sites. If you want to switch from manual management to using Composer to install and update Drupal core and contributed modules, you'll need to replace your site's composer.json file.

Common Composer error messages that indicate an outdated composer.json:

Nothing to install or update
Installation request for drupal/drupal No version set (parsed as 1.0.0)
don't install drupal/core 8.x.x | remove drupal/drupal
Your requirements could not be resolved to an installable set of packages.

While deleting the composer.lock and vendor/ directories might temporarily solve issues, converting the site to use the recommended Composer project template is a more robust long-term solution. See: Using Composer to Download and Update Files.

Automated tools like gocomposer and composerize-drupal aim to assist in this migration, but manual conversion is straightforward and often preferable.

Quick Summary

1. Create a new Composer-based Drupal project.
2. Copy over all custom modules, themes, files, and configuration.
3. Migrate your settings and environment configuration.
4. Require all contributed modules via Composer.
5. Run database updates and clear caches (drush updb; drush cr).
6. Update your web server to point to the new web/ directory.

Complete Steps

Before You Begin

Converting a legacy site may upgrade Drupal core and contrib modules to their latest versions. Consider if this is appropriate for your environment, especially for tightly version-controlled projects. You can pin specific versions using composer require vendor/package:version.

1. Create a New Composer Project

cd /var/www/sites
composer create-project drupal/recommended-project:~8.8.0 new_html --stability dev --no-interaction

This creates the recommended directory layout: core Composer files at the root, and the website itself in web/.

2. Copy Files

• Custom modules: web/modules/custom/
• Custom themes: web/themes/custom/
• Libraries: web/libraries/
• User files: web/sites/default/files/

Remove temporary folders like php/, css/, js/, styles/ from files/.

3. Migrate settings.php

Copy over database credentials, $settings['hash_salt'], trusted host patterns, and any custom settings. Ensure the $config_directories['sync'] path exists and is writable.

4. Add Contrib Modules

composer require drupal/module_name

Use --dev for development modules:

composer require --dev drupal/devel

5. Run Updates

drush updb
drush cr

6. Reconfigure Web Server

Update your server to point to the web/ directory. Adjust PHP-FPM pool settings and reload your server as needed.

7. Troubleshooting

7.1 Missing $settings['hash_salt']

drush php-eval 'echo \Drupal\Component\Utility\Crypt::randomBytesBase64(55) . "\n"'

7.2 Composer Warnings

Clear composer.lock and vendor/ then retry.

7.3 Error Reports

Review admin/reports/status for configuration errors or missing modules after migration.