ExpressionEngine® 3 User Guide

Legacy Documentation

You are using the documentation for version 3.5.17. Go here for the latest version or check here for your available upgrades to the latest version.

Upgrading from ExpressionEngine 2

Important

Third-party add-ons from v2 will not work with ExpressionEngine 3. Check with each add-on author to see if there are updates available. If you maintain your own add-ons, please see the 3.0 Conversion Guidelines.

Add-ons that you will not be using in v3 must be uninstalled and refactored out of your site before upgrading. ExpressionEngine 3 will not be able to run incompatible code to uninstall those add-ons after upgrading. For example, the Playa & Matrix Importer can be used to convert those third-party field types to native ExpressionEngine Relationship and Grid fields, and should be run while still on v2.

1. Backup and Prepare

  1. Clear the cache in ExpressionEngine by going to Tools ‣ Data ‣ Clear Caching. Select All Caches and click Submit.
  2. Back-up your ExpressionEngine database.
  3. Back-up all of your ExpressionEngine files and directories.
  4. Download the latest release of ExpressionEngine (either ExpressionEngine Core or the standard edition, whichever your site is currently running) and unzip the files to a folder on your computer.
  5. Take your site offline:
    1. Copy system/expressionengine/utilities/offline.html to your web root directory (the same place you have your main index.php file).
    2. Rename offline.html to index.html. Now your visitors will see the “offline” page while you update your site.

2. Copy Files

Now copy the following files from the backup of your current site to the newly downloaded ExpressionEngine 3.x directory:

  1. Copy system/expressionengine/config/config.php to system/user/config/config.php
  2. Copy system/expressionengine/config/database.php to system/user/config/database.php
  3. If you have any languages other than English in your Control Panel, copy all files and directories except english from system/expressionengine/language/ to system/user/language/.
  4. If you have the forum module installed, copy the directory themes/forum_themes/ to themes/user/forum/.
  5. If you have the wiki module installed, copy the directory themes/wiki_themes/ to themes/user/wiki_themes/.
  6. If you save templates as files, copy all files and directories from system/expressionengine/templates/ to system/user/templates/.

Note

We recommend putting ExpressionEngine 3 compatible third-party add-ons into the system/user/addons/ directory now.

3. Upload Files

On the server, rename the following files and directories:

  • Rename system/ to system_old/
  • Rename themes/ to themes_old/
  • Rename index.php to index.php.old
  • Rename admin.php to admin.php.old

Then upload the following files and directories:

  • system/
  • themes/
  • index.php
  • admin.php

Note

If you’ve moved your system directory, make sure to change both index.php and admin.php to point to the correct directory.

Note

If you have MSM installed using subfolders, make sure to update the index.php and admin.php files in those folders as well.

4. Check Permissions

Apache

You need to enable write access to the following files and folders. In a worst-case scenario that would be 666 for files and 777 for directories. You should check with your web host to see if more restrictive permissions can be used to allow PHP to write to files and directories. See File Permissions for details.

Make this file writable:

  • system/user/config/config.php

Make these directories (and their subdirectories) writable:

  • system/user/cache/
  • system/user/templates/

IIS

Provide all permissions to the IIS user for following directories (and their subdirectories):

  • system/user/cache/
  • system/user/templates/

5. Run Upgrade

Go to your site’s control panel URL (typically found at http://example.com/admin.php or http://example.com/system/) and follow the on-screen instructions to upgrade ExpressionEngine.

6. Clean up

  1. Remove or rename the offline index.html file from your site.

  2. If the updater could not automatically rename the installer, rename or remove system/ee/installer/ directory manually.

    Note

    The installer directory can be safely removed after installing ExpressionEngine.

  3. Review any Version Notes since they outline any version-specific changes that you may need to make to your installation.

  4. Review our best practices for recommendations on protecting your installation against common security risks.

  5. Go to the Add-On Manager and run the updates for any of your compatible add-ons.

    Control Panel Location: Developer Menu ‣ Add-On Manager

You’re Done! ExpressionEngine is now fully upgraded.

Report a problem with this page
ExpressionEngine® 3.5.17 User Guide
©2002–2021 Packet Tide,LLC.