I am using Drupal 9.x now and using Drush 10.x. I have always used drush aliases to manage my D7 sites as it makes life so much easier with various environments etc.

To test the newer YAML file (Drush for my old D7 uses a php file), I created a single Drush alias for a uat environment. The file, local.site.yml, is located in my ~/.drush/sites directory. When I do a drush sa to check what aliases exist, I correctly (I think?!) get the following message:


root: /var/www/my_site/web
uri: 'https://mysite.mydomain.com'

So I think this tells me that the single alias has been found.

When I try to use the alias using drush @local.uat status it fails:

[preflight] The alias @local.uat could not be found.

It must be simple... I have tried using just @uat and @site.uat but nothing works (and I would not expect it to!). Any ideas?! I am running Ubuntu 22.04 and Drush 10.6.2 if that makes a difference.

3 Answers 3


The filepath should be drush/sites/self.site.yml, and the contents should be the following (Indenting must be exact):

  root: /var/www/my_site/web
  uri: 'https://mysite.mydomain.com'

After which you will be able to call drush @local.uat.

  • I originally had self.site.yml and have just tried this - tells me I have the alias as before, but does not work. I've linted the file in a YAML checker again and all is good - one space after the : and two spaces before each section. My file was originally in a ,drush directory but I have changed this. I had to set the alias path in my /home/my_account/vendor/drush/drush/drush.yml file or it would pick up nothing. Also see comments below.
    – ChumKui
    Mar 20 at 17:11

Add an alias file called $PROJECT/drush/sites/self.site.yml, where $PROJECT is the project root (location of composer.json file). The site alias file should be named self.site.yml because this name is special, and is used to define the different environments (usually remote) of the current Drupal site.

The contents of the alias file should look something like the example below:

# File: self.site.yml
  host: server.domain.com
  user: www-admin
  root: /other/path/to/live/drupal
  uri: http://example.com
  host: server.domain.com
  user: www-admin
  root: /other/path/to/stage/drupal
  uri: http://stage.example.com

The top-level element names (live and stage in the example above) are used to identify the different environments available for this site. These may be used on the command line to select a different target environment to operate on by prepending an @ character, e.g. @live or @stage.

Following these steps, a cache:rebuild on the live environment would be:

  $ drush @live cache:rebuild
  • I'm not sure I understand $PROJECT/drush/sites/ path. I have several different envs on the machine, each with their own composer project files. I should be able to just point to a site in my alias and go from there. It might be my Drush config so going back to the drawing board i.e. reinstalling and trying again. The confusion for me is that given it reads back my alias, it should then use it. If it could not find the alias at all, it would make sense
    – ChumKui
    Mar 20 at 17:24

OK - I finally got to the bottom of this and it is working.

In order to get this to work all I needed to do was add the path of ANY alias file or files to each project's Drush config file i.e. drush.yml as well as my own local one.

You can name it whatever you like, self.site.yml or foo.site.yml if you wish, there is no need for a special first name, all you need is myname.site.yml. I have tested this and created two identical alias files with different names:



Both or these files reside in my ~/.drush directory but that is also not important as long as the path is defined in drush.yml in both your local drush installation AND in each project. Remember, you may have different versions of Drush per project.

When I do drush sa:

  root: /var/www/my_site/web
  uri: 'https://mysite.mydomain.com

  root: /var/www/my_site/web
  uri: 'https://my_site'

Both drush @uat status and drush @foo status work equally well as they point to the same Drupal root.

The location of the sites aliases file also makes no difference. Changing the location of my sites alias path to 'bar' instead of drush or .drush is fine as long as the local and project drush.yml are aligned. This is how it looks in all my drush.yml files now:

      - '${env.HOME}/.drush/sites'

I could equally have used ${env.HOME}/.drush/sites, ${env.HOME}/drush/sites or ${env.HOME}/bar/sites

I hope this helps others!

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.