3 This document describes how to update your Drupal site between 8.x.x minor and
4 patch versions; for example, from 8.1.2 to 8.1.3, or from 8.3.5 to 8.4.0.
6 To upgrade from a previous major version (for example, Drupal 6 or 7), the
7 process involves importing site configuration and content from your old site
8 into a new Drupal 8 site. The tools and process are currently experimental,
9 rather than being fully supported, so be sure to test in a development
10 environment. You will need to use the core Migrate Drupal UI module which
11 provides a user interface for the Migrate and Migrate Drupal modules included
12 in core. See https://www.drupal.org/upgrade/migrate for details, and
13 https://www.drupal.org/node/2167633 for known issues.
15 First steps and definitions:
17 * If you are upgrading to Drupal version x.y.z, then x is known as the major
18 version number, y is known as the minor version number, and z is known as
19 the patch version number. The download file will be named
20 drupal-x.y.z.tar.gz (or drupal-x.y.z.zip). Previous Drupal versions used
21 only x.y (MAJOR.MINOR) to designate their versions.
23 * All directories mentioned in this document are relative to the directory of
24 your Drupal installation.
26 * Make a full backup of all files, directories, and your database(s) before
27 starting, and save it outside your Drupal installation directory.
28 Instructions may be found at
29 https://www.drupal.org/upgrade/backing-up-the-db
31 * It is wise to try an update or upgrade on a test copy of your site before
32 applying it to your live site. Even minor updates can cause your site's
35 * Each new release of Drupal has release notes, which explain the changes made
36 since the previous version and any special instructions needed to update or
37 upgrade to the new version. You can find a link to the release notes for the
38 version you are upgrading or updating to on the Drupal project page
39 (https://www.drupal.org/project/drupal).
43 If you encounter errors during this process,
45 * Note any error messages you see.
47 * Restore your site to its previous state, using the file and database backups
48 you created before you started the update process. Do not attempt to do
49 further updates on a site that had update problems.
51 * Consult one of the support options listed on https://www.drupal.org/support
53 More in-depth information on updating and upgrading can be found at
54 https://www.drupal.org/upgrade
56 MINOR AND PATCH VERSION UPDATES
57 -------------------------------
58 To update from one 8.x.x version of Drupal to any later 8.x.x version, after
59 following the instructions in the INTRODUCTION section at the top of this file:
61 1. Log in as a user with the permission "Administer software updates".
63 2. Go to Administration > Configuration > Development > Maintenance mode.
64 Enable the "Put site into maintenance mode" checkbox and save the
67 3. Determine if your project is managed by Composer.
69 On a typical Unix/Linux command line, this can be determined by running the
70 following command (replace /PATH/TO/composer with the appropriate location
73 /PATH/TO/composer info drupal/core
75 If this is successful, your project is managed by Composer.
77 If you don't have Composer installed or access to the command line, you can
78 check the contents of composer.json. If "drupal/core" is present in the
79 "require" section of your composer.json file, then the project is managed by
82 If the project is not managed by Composer, follow the steps under "UPDATING
83 CODE WITHOUT COMPOSER", otherwise go to "UPDATING CODE WITH COMPOSER".
85 UPDATING CODE WITH COMPOSER
86 ---------------------------
87 1. On a typical Unix/Linux command line, run the following command from the root
88 directory (replace /PATH/TO/composer with the appropriate location for your
91 /PATH/TO/composer update
93 Note, if Composer is not installed you will need to install it in order to
96 Note, if you want to only update drupal/core the following command will
99 /PATH/TO/composer update drupal/core symfony/* --with-all-dependencies
101 2. Check the release notes for the updated version of Drupal to find out if
102 there is a change to default.settings.php.
104 You can find the release notes for your version at
105 https://www.drupal.org/project/drupal. At bottom of the project page under
106 "Downloads" use the link for your version of Drupal to view the release
107 notes. If your version is not listed, use the 'View all releases' link. From
108 this page you can scroll down or use the filter to find your version and its
111 If there is a change to default.settings.php, follow these steps:
113 - Locate your settings.php file in the /sites/* directory. (Typically
116 - Make a backup copy of your settings.php file, with a different file name.
118 - Make a copy of the new default.settings.php file, and name the copy
119 settings.php (overwriting your previous settings.php file).
121 - Copy the custom and site-specific entries from the backup you made into the
122 new settings.php file. You will definitely need the lines giving the
123 database information, and you will also want to copy in any other
124 customizations you have added.
126 3. Determine if there are any modifications to files such as .htaccess or
127 robots.txt and re-apply them. The Drupal Scaffold composer plugin
128 (https://github.com/drupal-composer/drupal-scaffold) can help you with
129 excluding files you'd like to always preserve when updating Drupal.
131 4. Go to the "UPLOADING THE CODE" section
133 UPDATING CODE WITHOUT COMPOSER
134 ------------------------------
135 1. Remove the 'core' and 'vendor' directories. Also remove all of the files
136 in the top-level directory, except any that you added manually.
138 If you made modifications to files like .htaccess, composer.json, or
139 robots.txt you will need to re-apply them from your backup, after the new
142 This should leave you with the modules, profiles, sites, and themes
143 directories. These directories should only contain code that you've used to
146 2. Download the latest Drupal 8.x.x release from https://www.drupal.org/download
147 to a directory outside of your web root. Extract the archive and copy the
148 files into your Drupal directory.
150 Copy all the files, but do not accidentally overwrite your modules, profiles,
151 sites, or themes directories.
153 On a typical Unix/Linux command line, use the following commands to download
156 wget https://www.drupal.org/files/projects/drupal-x.y.z.tar.gz
157 tar -zxvf drupal-x.y.z.tar.gz
159 This creates a new directory drupal-x.y.z/ containing all Drupal files and
160 directories. Copy the files into your Drupal installation directory:
162 cp -R drupal-x.y.z/* drupal-x.y.z/.htaccess /path/to/your/installation
164 If you do not have command line access to your server, download the archive
165 from https://www.drupal.org using your web browser and extract it locally.
167 3. Check the release notes for the updated version of Drupal to find out if
168 there is a change to default.settings.php.
170 You can find the release notes for your updated version at
171 https://www.drupal.org/project/drupal. At bottom of the project page under
172 "Downloads" use the link for your updated version of Drupal to view the
173 release notes. If your updated version is not listed, use the 'View all
174 releases' link. From this page you can scroll down or use the filter to find
175 your updated version and its release notes.
177 If there is a change to default.settings.php, follow these steps:
179 - Locate your settings.php file in the /sites/* directory. (Typically
182 - Make a backup copy of your settings.php file, with a different file name.
184 - Make a copy of the new default.settings.php file, and name the copy
185 settings.php (overwriting your previous settings.php file).
187 - Copy the custom and site-specific entries from the backup you made into the
188 new settings.php file. You will definitely need the lines giving the
189 database information, and you will also want to copy in any other
190 customizations you have added.
192 4. Re-apply any modifications to files such as .htaccess or robots.txt.
194 If you have added requirements in composer.json, it is recommended that you
195 re-add the requirements using Composer instead of applying the changes by
196 hand. For example, on a typical Unix/Linux command line, to reinstall the
197 Address module and its dependencies run (replace /PATH/TO/composer with the
198 appropriate location for your system):
200 /PATH/TO/composer require drupal/address
202 If you do not have command line access to your server, you will need to run
203 the Composer commands locally before uploading the file system to your
206 5. Go to the "UPLOADING THE CODE" section
210 1. If you updated the code in a different environment from where it is running
211 you need to upload the files to your web root including the vendor/
214 2. Go to the "UPDATING THE DATABASE" section
216 UPDATING THE DATABASE
217 ---------------------
218 1. Run update.php by visiting http://www.example.com/update.php (replace
219 www.example.com with your domain name). This will update the core database
222 If you are unable to access update.php do the following:
224 - Open settings.php with a text editor.
226 - Find the line that says:
227 $settings['update_free_access'] = FALSE;
230 $settings['update_free_access'] = TRUE;
232 - Once the update is done, $settings['update_free_access'] must be reverted
235 2. Go to Administration > Reports > Status report. Verify that everything is
238 3. Ensure that $settings['update_free_access'] is FALSE in settings.php.
240 4. Go to Administration > Configuration > Development > Maintenance mode.
241 Disable the "Put site into maintenance mode" checkbox and save the