> ## Documentation Index > Fetch the complete documentation index at: https://developer.upsun.com/llms.txt > Use this file to discover all available pages before exploring further. # Use Drush with Upsun > Install Drush, make it available on your path, and run Drush commands against your Drupal site on Upsun through the CLI, SSH, or hooks. [Drush](https://www.drush.org/) 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](/tutorials/drupal) deployed on Upsun. * The [Upsun CLI](/cli) installed and authenticated. ## 1. Install Drush Add Drush to your project as a Composer dependency: ```bash theme={null} composer require drush/drush ``` Drush needs a writable scratch space for its own caches and backups. Define [mounts](/docs/configure-apps/image-properties/mounts) for both in your app configuration: ```yaml .upsun/config.yaml theme={null} 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](/docs/development/variables/set-variables#set-variables-via-script) at the root of your app so Drush (and any other Composer binary) is available whenever you connect: ```bash .environment theme={null} 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](/docs/routes) in the same `.environment` file: ```bash .environment theme={null} 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](/cli/reference#environmentdrush) that runs a command against a remote environment without opening a full SSH session: ```bash theme={null} upsun drush -- ``` For example, to rebuild the cache on your current environment: ```bash theme={null} 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](#set-up-drush-aliases-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](/docs/development/ssh) and run Drush directly, or pass the command inline: ```bash theme={null} 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 ` from your local machine without connecting over SSH first. Since the Upsun CLI doesn't generate these for you, create them by hand: 1. Get the [SSH host and username](/docs/development/ssh#get-ssh-connection-details) for each environment you want an alias for: ```bash theme={null} upsun ssh --pipe --project --environment ``` 2. Get the environment's primary URL with the [`url` command](/cli/reference#environmenturl): ```bash theme={null} upsun url --primary --project --environment ``` 3. Create a site alias file at `drush/sites/.site.yml` in your local repository, with one entry per environment: ```yaml drush/sites/myproject.site.yml theme={null} 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](#in-hooks). 4. Run commands against an alias instead of connecting manually: ```bash theme={null} 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](/docs/configure-apps/hooks/hooks-comparison). This assumes Drush is already [on your path](#2-make-drush-available-on-your-path). Without that, the hook fails with `drush: command not found`: ```yaml .upsun/config.yaml theme={null} 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](/docs/development/sanitize-db/mariadb#with-drupal-and-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](https://www.drush.org/latest/install/), 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`](#2-make-drush-available-on-your-path). ### 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](#3-set-the-site-uri) 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: ```bash theme={null} 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: ```bash theme={null} drush -l ``` To run the same command across every site, loop over each site directory: ```bash theme={null} cd web/sites for site in site1 site2 site3; do drush -l $site done ``` ## See also * [Deploy Drupal on Upsun](/tutorials/drupal) * [Sanitizing databases: MariaDB and Drupal](/docs/development/sanitize-db/mariadb) * [Connect securely with SSH](/docs/development/ssh) * [`environment:drush` CLI reference](/cli/reference#environmentdrush)