Use Drush with Upsun

Drush is a command-line shell and scripting interface for Drupal. On Upsun, you have several ways to run it: through the Upsun CLI, over SSH, or from within your app’s hooks. This guide covers how to install Drush, make it available on your path, and choose the right way to run it for your use case.

Before you begin

You need:

A Drupal site deployed on Upsun.
The Upsun CLI installed and authenticated.

1. Install Drush

Add Drush to your project as a Composer dependency:

composer require drush/drush

Drush needs a writable scratch space for its own caches and backups. Define mounts for both in your app configuration:

.upsun/config.yaml

applications:
  myapp:
    mounts:
      '/.drush':
        source: storage
        source_path: 'drush'
      '/drush-backups':
        source: storage
        source_path: 'drush-backups'

2. Make Drush available on your path

Composer installs Drush to your project’s vendor/bin directory, which isn’t on your path by default. This is what makes running drush directly return drush: command not found. Add the following to a .environment file at the root of your app so Drush (and any other Composer binary) is available whenever you connect:

.environment

if [ -n "$PLATFORM_APP_DIR" -a -f "$PLATFORM_APP_DIR"/composer.json ] ; then
  bin=$(composer config bin-dir --working-dir="$PLATFORM_APP_DIR" --no-interaction 2>/dev/null)
  export PATH="${PLATFORM_APP_DIR}/${bin:-vendor/bin}:${PATH}"
fi

3. Set the site URI

Many Drush commands (such as drush uli for one-time login links) need to know your site’s URL. Set DRUSH_OPTIONS_URI from your routes in the same .environment file:

.environment

export PRIMARY_URL="$(echo "$PLATFORM_ROUTES" | base64 --decode | jq -r 'to_entries[] | select(.value.primary) | .key | rtrimstr("/")')"
export DRUSH_OPTIONS_URI="$PRIMARY_URL"

Run Drush commands

There are three ways to run Drush commands against a deployed environment, depending on your use case.

Using the CLI

The Upsun CLI has a built-in drush alias that runs a command against a remote environment without opening a full SSH session:

upsun drush -- <COMMAND>

For example, to rebuild the cache on your current environment:

upsun drush -- cache-rebuild

This is the fastest option for one-off commands, and it works the same way whether or not Drush is on your local machine.

The upsun CLI doesn’t support generating Drush aliases, so you’ll need to set them up manually. This is unlike the platform CLI, which includes a local:drush-aliases command for this.

Over SSH

To run Drush as part of a longer interactive session, connect over SSH and run Drush directly, or pass the command inline:

upsun ssh -e feature -- drush -y cache-rebuild

Replace feature with the name of the environment you want to target.

Set up Drush aliases manually

A Drush alias lets you run drush @myproject.main <COMMAND> from your local machine without connecting over SSH first. Since the Upsun CLI doesn’t generate these for you, create them by hand:

Get the SSH host and username for each environment you want an alias for:

upsun ssh --pipe --project <PROJECT_ID> --environment <ENVIRONMENT_NAME>

Get the environment’s primary URL with the url command:

upsun url --primary --project <PROJECT_ID> --environment <ENVIRONMENT_NAME>

Create a site alias file at drush/sites/<PROJECT_NAME>.site.yml in your local repository, with one entry per environment:

drush/sites/myproject.site.yml

main:
  host: ssh.us.upsun.com
  user: abc123-main-7cs6q4a--app
  root: /app/web
  uri: 'https://www.example.com'
feature:
  host: ssh.us.upsun.com
  user: abc123-feature-7cs6q4a--app
  root: /app/web
  uri: 'https://feature-abc123.upsun.app'

root is your app’s docroot on the remote environment, the same directory Drush runs from in deploy hooks.

Run commands against an alias instead of connecting manually:
drush @myproject.main cache-rebuild

You need to update the file whenever an environment is created, renamed, or deleted, since Upsun doesn’t keep it in sync automatically.

In hooks

To run Drush automatically on every deployment, add it to a deploy or post_deploy hook. This assumes Drush is already on your path. Without that, the hook fails with drush: command not found:

.upsun/config.yaml

applications:
  myapp:
    hooks:
      deploy: |
        cd /app/web
        if [ -n "$(drush status --field=bootstrap)" ]; then
          drush -y cache-rebuild
          drush -y updatedb
          if [ -n "$(ls $(drush php:eval "echo realpath(Drupal\Core\Site\Settings::get('config_sync_directory'));")/*.yml 2>/dev/null)" ]; then
            drush -y config-import
          fi
        fi

The drush status --field=bootstrap check confirms Drupal is installed and bootstraps successfully before running further commands, which avoids failed deployments on a fresh environment that hasn’t been installed yet.

Common commands

The following Drush commands are frequently useful in an Upsun workflow:

Command	Purpose
`drush cache-rebuild` (`drush cr`)	Rebuild all Drupal caches.
`drush updatedb` (`drush updb`)	Run pending database updates.
`drush config-import` (`drush cim`)	Import configuration from the sync directory.
`drush sql:sanitize`	Remove personally identifiable information from a database. See sanitizing MariaDB with Drush.
`drush uli`	Generate a one-time login link for an administrator.
`drush state:set`	Set a Drupal state value, useful for gating one-time deploy hook logic.

Troubleshooting

`composer require drush/drush` fails

If Composer reports that it can’t find drush/drush, or blocks the install over a security advisory, this is usually a version mismatch rather than a network issue:

Package not found: Drush’s minimum PHP requirement increases with each major version. If your app’s PHP version is older than any available Drush release supports, Composer reports it as unable to find a matching package. Check your app’s PHP version against Drush’s current requirements, and pin to an older Drush major version if you can’t upgrade PHP yet, for example composer require drush/drush:^11.
Security-advisory conflict: If your composer.json includes a package like roave/security-advisories, it blocks installing versions with known vulnerabilities. Composer’s error output names the exact conflicting package and version — upgrade Drush past that range to resolve it.

`drush: command not found`

Confirm Drush is installed as a Composer dependency and that your path includes vendor/bin.

A command returns the wrong domain

If a command that depends on the site URI (such as drush uli) returns the wrong domain or an error, confirm DRUSH_OPTIONS_URI is set for the environment you’re running against.

Drush can’t query the database on a multisite install

On a multisite Drupal install, running a bare drush command can fail with an error like the following:

Command config-get was not found. Drush was unable to query the database.

This happens because Drush can’t determine which site to target when there are multiple sites under your site directory (for example, web/sites). Specify the site with the -l (--uri) flag. Despite the flag’s name, use the site’s subdirectory name (for example, site1), not a full URL:

drush -l <SITE> <COMMAND>

To run the same command across every site, loop over each site directory:

cd web/sites
for site in site1 site2 site3; do
  drush -l $site <COMMAND>
done

Get Started

Core Concepts

Configure Apps & Services

Build, Deploy & Run

Manage Projects

Manage Environments

Manage Resources

Observability & Metrics

Integrations

Troubleshooting

Resources

Before you begin

1. Install Drush

2. Make Drush available on your path

3. Set the site URI

Run Drush commands

Using the CLI

Over SSH

Set up Drush aliases manually

In hooks

Common commands

Troubleshooting

`composer require drush/drush` fails

`drush: command not found`

A command returns the wrong domain

Drush can’t query the database on a multisite install

See also

​Before you begin

​1. Install Drush

​2. Make Drush available on your path

​3. Set the site URI

​Run Drush commands

​Using the CLI

​Over SSH

​Set up Drush aliases manually

​In hooks

​Common commands

​Troubleshooting

​composer require drush/drush fails

​drush: command not found

​A command returns the wrong domain

​Drush can’t query the database on a multisite install

​See also

Before you begin

1. Install Drush

2. Make Drush available on your path

3. Set the site URI

Run Drush commands

Using the CLI

Over SSH

Set up Drush aliases manually

In hooks

Common commands

Troubleshooting

`composer require drush/drush` fails

`drush: command not found`

A command returns the wrong domain

Drush can’t query the database on a multisite install

See also