Updating Drupal core manually

Last updated on
26 October 2022

This documentation needs review. See "Help improve this page" in the sidebar.

Before you begin

The recommended update method is via Composer.

And, if you have installed any contributed modules with 3rd party dependencies using Composer, you need to use Composer to update Drupal core too, as the instructions below will overwrite your vendor/ directory.

If not already done, it is suggested that you read this introduction, which summarizes your options to choose from when updating your Drupal. As mentioned, the recommended update method is via Composer.

PS! This update procedure is also described in the User Guide.

Note that drupal-x.y.z refers to Drupal and the version number, eg drupal-9.3.0.

Update Drupal core

Steps to update Drupal core using a manual installation and a command line (shell):

  1. Back up both your files and database. Having a complete backup makes it easy to revert to the prior version if the update fails.

    Optionally, if you made manual modifications to files like .htaccess, composer.json, or robots.txt, copy them somewhere easy to find. Because after you've installed the new Drupal core, you will need to re-apply the changes. For example, Acquia Dev Desktop places a .htaccess file in the top-level directory and without it, only the homepage on your site will work.

    Always revert to a backup if you get a fatal error in the update process.

  2. Using Drupal, log in as any user with the permission "Administer software updates".

  3. Using Drupal, put your site into maintenance mode. To do so:

    1. Navigate the admin interface to Administration > Configuration > Development > Maintenance mode.

    2. Check "Put site into maintenance mode" checkbox.

    3. Click on "Save configuration".

  4. Choose one of the following two options to remove the files in the top-level directory as well as the 'core' and 'vendor' directories, leaving the 'modules', 'profiles', 'sites', 'themes' directories behind:

    • Using the shell
      1. Navigate into your Drupal installation.
        cd /path/to/your/drupal/directory
      2. Remove the 'core' and 'vendor' directories.
        rm -rf core vendor
      3. Remove all of the files in the top-level directory.
        rm -f *.* .[a-z]*
    • Using an FTP client
      1. Navigate to your Drupal directory.
      2. Select all the files in the top-level directory (also hidden files starting with a dot) as well as the 'core' and 'vendor' directories, and delete them. Be sure not to delete the 'modules', 'profiles', 'sites', and 'themes' directories.
  5. Optionally sometimes an update includes changes to default.settings.php or default.services.yml files. This will be noted in the release notes. You can find the release notes for your version at https://www.drupal.org/project/drupal. At bottom of the project page under the "Downloads" section use the link for your version of Drupal to view the release notes. If your version is not listed, use the "View all releases" link. From this page, you can scroll down or use the filter to find your version and its release notes. If the update includes changes to the default.settings.php file, follow these steps:

    1. Locate your settings.php file in the /sites/* directory. (Typically sites/default.)
    2. Make a backup copy of your settings.php file, with a different file name.
    3. Make a copy of the new default.settings.php file, and name the copy settings.php (overwriting your previous settings.php file).
    4. Copy the custom and site-specific entries from the backup you made into the new settings.php file. You will definitely need the lines giving the database information, and you will also want to copy in any other customizations you have added.
  6. Choose one of the following two options to get the new files into the top-level directory and the 'core' and 'vendor' directories:

    • Using shell
      1. On a typical Unix/Linux command line, use the following commands to download and extract:
        wget https://ftp.drupal.org/files/projects/drupal-x.y.z.tar.gz
        tar zxf drupal-x.y.z.tar.gz
      2. This command above created a new directory drupal-x.y.z/ containing all Drupal files and directories. Enter the new directory, and copy the 'core' and 'vendor' directory and the files in the top-level directory into your Drupal installation directory:
        cd drupal-x.y.z
        cp -R core vendor /path/to/your/drupal/directory
        cp *.* .[a-z]* /path/to/your/drupal/directory
    • Using the browser and FTP client
      1. Download the latest Drupal release from https://www.drupal.org/download to a directory outside of your webroot.
      2. Extract the archive.
      3. Use an FTP client, to upload the 'core' and 'vendor' directory and the files in the top-level directory to your Drupal directory.
  7. Optionally, re-apply any manually modifications to files such as .htaccess, composer.json, or robots.txt.

  8. Using your browser, run update.php by visiting http://www.example.com/update.php (replacing www.example.com with your domain name). This will update the core database tables.

    • Optionally, if you are not logged in as a user with the "Administer Software Updates" permission, or the site maintenance account (as created during installation) you will be unable to access update.php. Here are the steps to bypass this restriction:

      1. Open settings.php with a text editor.
      2. Find this line:
        $settings['update_free_access'] = FALSE;
      3. Change the FALSE value to TRUE:
        $settings['update_free_access'] = TRUE;
      4. Visit the /update.php page again.
      5. After you are done with all of the steps above, for security, it is important to change the setting back to FALSE.
  9. Using your browser, log in your Drupal admin and navigate to Administration > Reports > Status report. Verify that everything is working as expected.
  10. Still using your browser, log in your Drupal admin and navigate to Administration > Configuration > Development > Maintenance mode. Uncheck the "Put site into maintenance mode" checkbox and click on the "Save" button.
  11. After updating, remove the Drupal release you downloaded and extracted earlier:

    rm drupal-x.y.z.tar.gz
    rm -rf drupal-x.y.z/
  12. Done. You have successfully updated your Drupal  core using a manual installation and the shell/browser. :)

Help improve this page

Page status: Needs review

You can: