Creating a new project with Acquia BLT


  • To use Acquia BLT, do not clone either Acquia BLT or the blt-project project.
  • The BLT project template is minimally maintained for backwards compatibility with BLT 11. If you are using BLT 12, you should instead add BLT to your preferred distribution or existing application: Adding Acquia BLT to an existing project.

To create a Acquia BLT project:

  1. Determine a machine name for your new project (such as my-project). For compatibility with third-party tools, Acquia recommends you use only letters, numbers, and hyphens for the machine name.

  2. In a command prompt window, run the following commands to both create your new project and download all dependencies (including Acquia BLT):

    composer create-project --no-interaction acquia/drupal-recommended-project my-project
    composer require acquia/blt
  3. Change to your project directory. For example:

    cd my-project
  4. If this is your first time using Acquia BLT on this computer, restart your shell to allow Bash to detect the new Acquia BLT alias.

  5. Customize your blt/blt.yml file to select an install profile. The build.yml file includes all available configuration values.

    By default, Acquia BLT installs websites using the Drupal minimal profile. You can change this setting to any other core, contributed, or custom profile in your codebase.

    To change to another profile:

    1. Download the profile of your choice, based on the following command:

      composer require acquia/acquia_cms
    2. Enter the name of the profile in the blt/blt.yml file, in the profile:name setting. For example:

      profile: name: acquia_cms
  6. Start your application hosting stack (also called a LAMP stack) by running the following command to create a Drupal VM instance:

    blt vm

    To customize your virtual machine (VM), such as to enable Solr or to change the PHP version, respond no when Acquia BLT offers to boot your VM, and then make any necessary modifications to the box/config.yml file before starting your VM.

    Using your own LAMP stack

    To set up your own LAMP stack, see Local development with Acquia BLT, and then execute the following command to generate default local settings files:

    blt blt:init:settings

    Change the generated docroot/sites/default/settings/local.settings.php file by adding your custom MySql credentials.

  7. Install Drupal and generate any remaining required files (such as settings.php or hash salt) by running the following command:

    blt setup
  8. Sign in to Drupal by running the following command:

    drush @my-project.local uli

    Be sure to replace my-project with the name of your project, which must be the value of project.machine_name in the blt/blt.yml file.

You now have a running local Drupal website that uses Acquia BLT.

For information about common instructions and how to begin using Acquia BLT, see Next steps with Acquia BLT.


If you have trouble creating the project, attempt to resolve the issue by using one of the following methods:

  • Clear the Composer cache.

  • Increase the process timeout by running the following command:

    composer clear-cache

If you have trouble using the blt alias, verify the alias is installed as expected, and then restart your terminal session by running the following commands, based on your version of Acquia BLT:

./vendor/bin/blt blt:init:shell-alias
source ~/.bash_profile
composer run-script blt-alias
source ~/.bash_profile

If you receive syntax errors from vendor packages, ensure that the version of PHP on your host matches the version of PHP in your VM, or else be sure to always run Composer commands from the VM.

Additional troubleshooting resources

If you continue to have issues with Acquia BLT, review the following resources: