UPGRADE.txt

INTRODUCTION
------------
This document describes how to:

  * Update your Drupal site from one minor 7.x version to another minor 7.x
    version; for example, from 7.8 to 7.9, or from 7.6 to 7.10.

  * Upgrade your Drupal site's major version from 6.x to 7.x.

First steps and definitions:

  * If you are upgrading to Drupal version x.y, then x is known as the major
    version number, and y is known as the minor version number. The download
    file will be named drupal-x.y.tar.gz (or drupal-x.y.zip).

  * All directories mentioned in this document are relative to the directory of
    your Drupal installation.

  * Make a full backup of all files, directories, and your database(s) before
    starting, and save it outside your Drupal installation directory.
    Instructions may be found at http://drupal.org/upgrade/backing-up-the-db

  * It is wise to try an update or upgrade on a test copy of your site before
    applying it to your live site. Even minor updates can cause your site's
    behavior to change.

  * Each new release of Drupal has release notes, which explain the changes made
    since the previous version and any special instructions needed to update or
    upgrade to the new version. You can find a link to the release notes for the
    version you are upgrading or updating to on the Drupal project page
    (http://drupal.org/project/drupal).

UPGRADE PROBLEMS
----------------
If you encounter errors during this process,

  * Note any error messages you see.

  * Restore your site to its previous state, using the file and database backups
    you created before you started the upgrade process. Do not attempt to do
    further upgrades on a site that had update problems.

  * Consult one of the support options listed on http://drupal.org/support

More in-depth information on upgrading can be found at http://drupal.org/upgrade

MINOR VERSION UPDATES
---------------------
To update from one minor 7.x version of Drupal to any later 7.x version, after
following the instructions in the INTRODUCTION section at the top of this file:

1. Log in as a user with the permission "Administer software updates".

2. Go to Administration > Configuration > Development > Maintenance mode.
   Enable the "Put site into maintenance mode" checkbox and save the
   configuration.

3. Remove all old core files and directories, except for the 'sites' directory
   and any custom files you added elsewhere.

   If you made modifications to files like .htaccess or robots.txt, you will
   need to re-apply them from your backup, after the new files are in place.

   Sometimes an update includes changes to default.settings.php (this will be
   noted in the release notes). If that's the case, follow these steps:

   - Locate your settings.php file in the /sites/* directory. (Typically
     sites/default.)

   - Make a backup copy of your settings.php file, with a different file name.

   - Make a copy of the new default.settings.php file, and name the copy
     settings.php (overwriting your previous settings.php file).

   - 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.

   You can find the release notes for your version at
   https://www.drupal.org/project/drupal. At bottom of the project page under
   "Downloads" 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.

4. Download the latest Drupal 7.x release from http://drupal.org to a
   directory outside of your web root. Extract the archive and copy the files
   into your Drupal directory.

   On a typical Unix/Linux command line, use the following commands to download
   and extract:

     wget http://drupal.org/files/projects/drupal-x.y.tar.gz
     tar -zxvf drupal-x.y.tar.gz

   This creates a new directory drupal-x.y/ containing all Drupal files and
   directories. Copy the files into your Drupal installation directory:

     cp -R drupal-x.y/* drupal-x.y/.htaccess /path/to/your/installation

   If you do not have command line access to your server, download the archive
   from http://drupal.org using your web browser, extract it, and then use an
   FTP client to upload the files to your web root.

5. Re-apply any modifications to files such as .htaccess or robots.txt.

6. Run update.php by visiting http://www.example.com/update.php (replace
   www.example.com with your domain name). This will update the core database
   tables.

   If you are unable to access update.php do the following:

   - Open settings.php with a text editor.

   - Find the line that says:
     $update_free_access = FALSE;

   - Change it into:
     $update_free_access = TRUE;

   - Once the upgrade is done, $update_free_access must be reverted to FALSE.

7. Go to Administration > Reports > Status report. Verify that everything is
   working as expected.

8. Ensure that $update_free_access is FALSE in settings.php.

9. Go to Administration > Configuration > Development > Maintenance mode.
   Disable the "Put site into maintenance mode" checkbox and save the
   configuration.

MAJOR VERSION UPGRADE
---------------------
To upgrade from a previous major version of Drupal to Drupal 7.x, after
following the instructions in the INTRODUCTION section at the top of this file:

1. Check on the Drupal 7 status of your contributed and custom modules and
   themes. See http://drupal.org/node/948216 for information on upgrading
   contributed modules and themes. See http://drupal.org/node/895314 for a list
   of modules that have been moved into core for Drupal 7, and instructions on
   how to update them. See http://drupal.org/update/modules for information on
   how to update your custom modules, and http://drupal.org/update/theme for
   custom themes.

   You may decide at this point that you cannot upgrade your site, because
   needed modules or themes are not ready for Drupal 7.

2. Update to the latest available version of Drupal 6.x (if your current version
   is Drupal 5.x, you have to upgrade to 6.x first). If you need to update,
   download Drupal 6.x and follow the instructions in its UPGRADE.txt. This
   document only applies for upgrades from 6.x to 7.x.

3. In addition to updating to the latest available version of Drupal 6.x core,
   you must also upgrade all of your contributed modules for Drupal to their
   latest Drupal 6.x versions.

4. Log in as user ID 1 (the site maintenance user).

5. Go to Administer > Site configuration > Site maintenance. Select
   "Off-line" and save the configuration.

6. Go to Administer > Site building > Themes. Enable "Garland" and select it as
   the default theme.

7. Go to Administer > Site building > Modules. Disable all modules that are not
   listed under "Core - required" or "Core - optional". It is possible that some
   modules cannot be disabled, because others depend on them. Repeat this step
   until all non-core modules are disabled.

   If you know that you will not re-enable some modules for Drupal 7.x and you
   no longer need their data, then you can uninstall them under the Uninstall
   tab after disabling them.

8. On the command line or in your FTP client, remove the file

     sites/default/default.settings.php

9. Remove all old core files and directories, except for the 'sites' directory
   and any custom files you added elsewhere.

   If you made modifications to files like .htaccess or robots.txt, you will
   need to re-apply them from your backup, after the new files are in place.

10. If you uninstalled any modules, remove them from the sites/all/modules and
   other sites/*/modules directories. Leave other modules in place, even though
   they are incompatible with Drupal 7.x.

11. Download the latest Drupal 7.x release from http://drupal.org to a
   directory outside of your web root. Extract the archive and copy the files
   into your Drupal directory.

   On a typical Unix/Linux command line, use the following commands to download
   and extract:

     wget http://drupal.org/files/projects/drupal-x.y.tar.gz
     tar -zxvf drupal-x.y.tar.gz

   This creates a new directory drupal-x.y/ containing all Drupal files and
   directories. Copy the files into your Drupal installation directory:

     cp -R drupal-x.y/* drupal-x.y/.htaccess /path/to/your/installation

   If you do not have command line access to your server, download the archive
   from http://drupal.org using your web browser, extract it, and then use an
   FTP client to upload the files to your web root.

12. Re-apply any modifications to files such as .htaccess or robots.txt.

13. Make your settings.php file writeable, so that the update process can
   convert it to the format of Drupal 7.x. settings.php is usually located in

     sites/default/settings.php

14. Run update.php by visiting http://www.example.com/update.php (replace
   www.example.com with your domain name). This will update the core database
   tables.

   If you are unable to access update.php do the following:

   - Open settings.php with a text editor.

   - Find the line that says:
     $update_free_access = FALSE;

   - Change it into:
     $update_free_access = TRUE;

   - Once the upgrade is done, $update_free_access must be reverted to FALSE.

15. Backup your database after the core upgrade has run.

16. Replace and update your non-core modules and themes, following the
   procedures at http://drupal.org/node/948216

17. Go to Administration > Reports > Status report. Verify that everything is
   working as expected.

18. Ensure that $update_free_access is FALSE in settings.php.

19. Go to Administration > Configuration > Development > Maintenance mode.
   Disable the "Put site into maintenance mode" checkbox and save the
   configuration.

To get started with Drupal 7 administration, visit
http://drupal.org/getting-started/7/admin

File

./UPGRADE.txt

View source
  1. INTRODUCTION
  2. ------------
  3. This document describes how to:
  4. * Update your Drupal site from one minor 7.x version to another minor 7.x
  5. version; for example, from 7.8 to 7.9, or from 7.6 to 7.10.
  6. * Upgrade your Drupal site's major version from 6.x to 7.x.
  7. First steps and definitions:
  8. * If you are upgrading to Drupal version x.y, then x is known as the major
  9. version number, and y is known as the minor version number. The download
  10. file will be named drupal-x.y.tar.gz (or drupal-x.y.zip).
  11. * All directories mentioned in this document are relative to the directory of
  12. your Drupal installation.
  13. * Make a full backup of all files, directories, and your database(s) before
  14. starting, and save it outside your Drupal installation directory.
  15. Instructions may be found at http://drupal.org/upgrade/backing-up-the-db
  16. * It is wise to try an update or upgrade on a test copy of your site before
  17. applying it to your live site. Even minor updates can cause your site's
  18. behavior to change.
  19. * Each new release of Drupal has release notes, which explain the changes made
  20. since the previous version and any special instructions needed to update or
  21. upgrade to the new version. You can find a link to the release notes for the
  22. version you are upgrading or updating to on the Drupal project page
  23. (http://drupal.org/project/drupal).
  24. UPGRADE PROBLEMS
  25. ----------------
  26. If you encounter errors during this process,
  27. * Note any error messages you see.
  28. * Restore your site to its previous state, using the file and database backups
  29. you created before you started the upgrade process. Do not attempt to do
  30. further upgrades on a site that had update problems.
  31. * Consult one of the support options listed on http://drupal.org/support
  32. More in-depth information on upgrading can be found at http://drupal.org/upgrade
  33. MINOR VERSION UPDATES
  34. ---------------------
  35. To update from one minor 7.x version of Drupal to any later 7.x version, after
  36. following the instructions in the INTRODUCTION section at the top of this file:
  37. 1. Log in as a user with the permission "Administer software updates".
  38. 2. Go to Administration > Configuration > Development > Maintenance mode.
  39. Enable the "Put site into maintenance mode" checkbox and save the
  40. configuration.
  41. 3. Remove all old core files and directories, except for the 'sites' directory
  42. and any custom files you added elsewhere.
  43. If you made modifications to files like .htaccess or robots.txt, you will
  44. need to re-apply them from your backup, after the new files are in place.
  45. Sometimes an update includes changes to default.settings.php (this will be
  46. noted in the release notes). If that's the case, follow these steps:
  47. - Locate your settings.php file in the /sites/* directory. (Typically
  48. sites/default.)
  49. - Make a backup copy of your settings.php file, with a different file name.
  50. - Make a copy of the new default.settings.php file, and name the copy
  51. settings.php (overwriting your previous settings.php file).
  52. - Copy the custom and site-specific entries from the backup you made into the
  53. new settings.php file. You will definitely need the lines giving the
  54. database information, and you will also want to copy in any other
  55. customizations you have added.
  56. You can find the release notes for your version at
  57. https://www.drupal.org/project/drupal. At bottom of the project page under
  58. "Downloads" use the link for your version of Drupal to view the release
  59. notes. If your version is not listed, use the 'View all releases' link. From
  60. this page you can scroll down or use the filter to find your version and its
  61. release notes.
  62. 4. Download the latest Drupal 7.x release from http://drupal.org to a
  63. directory outside of your web root. Extract the archive and copy the files
  64. into your Drupal directory.
  65. On a typical Unix/Linux command line, use the following commands to download
  66. and extract:
  67. wget http://drupal.org/files/projects/drupal-x.y.tar.gz
  68. tar -zxvf drupal-x.y.tar.gz
  69. This creates a new directory drupal-x.y/ containing all Drupal files and
  70. directories. Copy the files into your Drupal installation directory:
  71. cp -R drupal-x.y/* drupal-x.y/.htaccess /path/to/your/installation
  72. If you do not have command line access to your server, download the archive
  73. from http://drupal.org using your web browser, extract it, and then use an
  74. FTP client to upload the files to your web root.
  75. 5. Re-apply any modifications to files such as .htaccess or robots.txt.
  76. 6. Run update.php by visiting http://www.example.com/update.php (replace
  77. www.example.com with your domain name). This will update the core database
  78. tables.
  79. If you are unable to access update.php do the following:
  80. - Open settings.php with a text editor.
  81. - Find the line that says:
  82. $update_free_access = FALSE;
  83. - Change it into:
  84. $update_free_access = TRUE;
  85. - Once the upgrade is done, $update_free_access must be reverted to FALSE.
  86. 7. Go to Administration > Reports > Status report. Verify that everything is
  87. working as expected.
  88. 8. Ensure that $update_free_access is FALSE in settings.php.
  89. 9. Go to Administration > Configuration > Development > Maintenance mode.
  90. Disable the "Put site into maintenance mode" checkbox and save the
  91. configuration.
  92. MAJOR VERSION UPGRADE
  93. ---------------------
  94. To upgrade from a previous major version of Drupal to Drupal 7.x, after
  95. following the instructions in the INTRODUCTION section at the top of this file:
  96. 1. Check on the Drupal 7 status of your contributed and custom modules and
  97. themes. See http://drupal.org/node/948216 for information on upgrading
  98. contributed modules and themes. See http://drupal.org/node/895314 for a list
  99. of modules that have been moved into core for Drupal 7, and instructions on
  100. how to update them. See http://drupal.org/update/modules for information on
  101. how to update your custom modules, and http://drupal.org/update/theme for
  102. custom themes.
  103. You may decide at this point that you cannot upgrade your site, because
  104. needed modules or themes are not ready for Drupal 7.
  105. 2. Update to the latest available version of Drupal 6.x (if your current version
  106. is Drupal 5.x, you have to upgrade to 6.x first). If you need to update,
  107. download Drupal 6.x and follow the instructions in its UPGRADE.txt. This
  108. document only applies for upgrades from 6.x to 7.x.
  109. 3. In addition to updating to the latest available version of Drupal 6.x core,
  110. you must also upgrade all of your contributed modules for Drupal to their
  111. latest Drupal 6.x versions.
  112. 4. Log in as user ID 1 (the site maintenance user).
  113. 5. Go to Administer > Site configuration > Site maintenance. Select
  114. "Off-line" and save the configuration.
  115. 6. Go to Administer > Site building > Themes. Enable "Garland" and select it as
  116. the default theme.
  117. 7. Go to Administer > Site building > Modules. Disable all modules that are not
  118. listed under "Core - required" or "Core - optional". It is possible that some
  119. modules cannot be disabled, because others depend on them. Repeat this step
  120. until all non-core modules are disabled.
  121. If you know that you will not re-enable some modules for Drupal 7.x and you
  122. no longer need their data, then you can uninstall them under the Uninstall
  123. tab after disabling them.
  124. 8. On the command line or in your FTP client, remove the file
  125. sites/default/default.settings.php
  126. 9. Remove all old core files and directories, except for the 'sites' directory
  127. and any custom files you added elsewhere.
  128. If you made modifications to files like .htaccess or robots.txt, you will
  129. need to re-apply them from your backup, after the new files are in place.
  130. 10. If you uninstalled any modules, remove them from the sites/all/modules and
  131. other sites/*/modules directories. Leave other modules in place, even though
  132. they are incompatible with Drupal 7.x.
  133. 11. Download the latest Drupal 7.x release from http://drupal.org to a
  134. directory outside of your web root. Extract the archive and copy the files
  135. into your Drupal directory.
  136. On a typical Unix/Linux command line, use the following commands to download
  137. and extract:
  138. wget http://drupal.org/files/projects/drupal-x.y.tar.gz
  139. tar -zxvf drupal-x.y.tar.gz
  140. This creates a new directory drupal-x.y/ containing all Drupal files and
  141. directories. Copy the files into your Drupal installation directory:
  142. cp -R drupal-x.y/* drupal-x.y/.htaccess /path/to/your/installation
  143. If you do not have command line access to your server, download the archive
  144. from http://drupal.org using your web browser, extract it, and then use an
  145. FTP client to upload the files to your web root.
  146. 12. Re-apply any modifications to files such as .htaccess or robots.txt.
  147. 13. Make your settings.php file writeable, so that the update process can
  148. convert it to the format of Drupal 7.x. settings.php is usually located in
  149. sites/default/settings.php
  150. 14. Run update.php by visiting http://www.example.com/update.php (replace
  151. www.example.com with your domain name). This will update the core database
  152. tables.
  153. If you are unable to access update.php do the following:
  154. - Open settings.php with a text editor.
  155. - Find the line that says:
  156. $update_free_access = FALSE;
  157. - Change it into:
  158. $update_free_access = TRUE;
  159. - Once the upgrade is done, $update_free_access must be reverted to FALSE.
  160. 15. Backup your database after the core upgrade has run.
  161. 16. Replace and update your non-core modules and themes, following the
  162. procedures at http://drupal.org/node/948216
  163. 17. Go to Administration > Reports > Status report. Verify that everything is
  164. working as expected.
  165. 18. Ensure that $update_free_access is FALSE in settings.php.
  166. 19. Go to Administration > Configuration > Development > Maintenance mode.
  167. Disable the "Put site into maintenance mode" checkbox and save the
  168. configuration.
  169. To get started with Drupal 7 administration, visit
  170. http://drupal.org/getting-started/7/admin

Buggy or inaccurate documentation? Please file an issue. Need support? Need help programming? Connect with the Drupal community.