You're looking at an older version of Totara.

Please see Totara 15 help for the latest version.

On this page



Before upgrading to Totara 13 please ensure your site has been upgraded to at least Totara 9 and check that your server meets the minimum requirements described in the Server system requirements.

Upgrade process

Please note that the upgrade process for Totara 13 differs from previous major releases as the code base has been reorganised, and the distribution now includes Totara Learn, Perform and Engage.
For more information on these changes please see Totara 13 code reorganisation and Totara 13 notable technical changes.

  1. Log in as a Site Administrator.
  2. Check the live logs to check if any users are currently using the site. The site will be offline while the upgrades are performed (Quick-access menu > Reports > Live Logs).
  3. Run cron.
  4. Enable maintenance mode in Totara (Quick-access menu > Server > Maintenance Mode).
  5. Disable cron.
  6. Log out.
  7. Back up the Totara database.
  8. Back up the sitedata directory.
  9. Back up the Totara source code directory.
  10. Make a copy of your config.php and any plugins you have installed.
  11. Remove the old source code - delete everything.
  12. Extract the new source code into the source code directory.

    Do not copy the new code on top of the existing code folder.

  13. Copy your config.php and any third-party plugins back into the source code directory.
  14. Modify your config.php as described in the Modifying your config.php section.
  15. Modify your web server configuration to point to the server directory.

    This is a significant change to web server configuration and enables us to present a more secure solution. Failing to change your web server configuration to serve the server directory will compromise the security of your site.

  16. Run the command below in your terminal, replacing www-data with your web user's username (if using a Linux- or Unix-based system), otherwise you can navigate to the site URL (redirected automatically) to perform the upgrade via the browser.

    sudo -u www-data php server/admin/cli/upgrade.php
  17. Review the information provided and confirm you want to continue.
  18. Carefully check the output in the terminal and ensure no errors were encountered.

    If you have encountered an error the site will need to be rolled back, the issue fixed, and then the upgrade attempted again.

  19. Purge the caches:

    sudo -u www-data php server/admin/cli/purge_caches.php
  20. Log in as a Site Administrator.
  21. Review and save changes to new settings (if any).
  22. Review your theme and test.
  23. Disable server maintenance mode.
  24. Re-enable cron and let it run.
  25. Congratulations, your site is now upgraded. Read for details on what is new.

What to do if the upgrade fails

When an upgrade fails for any reason the best course of action is to roll back to the last known good working state. This is likely the backups you took immediately before the upgrade (steps 7-9 in the upgrade process above). Fix the error, and then proceed through the upgrade again.

If you are unsure why the upgrade failed, or are unsure of how to fix it please reach out to us via our help desk.

Attempting to resume an upgrade that has previously failed should not be attempted unless you fully understand the nature of the failure and are sure that the site data is still in a valid state. If at all unsure we recommend rolling back and restarting the upgrade process.

Modifying your config.php

You need to update your existing config.php file with the following changes:

  • Remove the following line if it exists near the top of the config.php file:
    global $CFG;
  • Add a flavour declaration specifying which flavour the site should be using:
    $CFG→forceflavour = 'flavourname';
    The following options are available for flavourname depending on which combination of products the upgraded site will be using:
    • learn
    • engage
    • perform
    • learn_perform
    • learn_engage
    • perform_engage
    • learn_perform_engage
    • learn_professional
  • Remove this line (or any similar one) from the bottom of config.php:
    require_once(dirname(__FILE__) . '/lib/setup.php');

Your config.php should remain in the top-level folder (do not move it to server/config.php).

Considerations for upgrading

When upgrading there are many things to consider both from a technical and training perspective. It is important to ensure all elements of your system are technically compatible, including your theme and any customisations. You will also want to make sure any training materials, and indeed any trainers, are up-to-date with new features and improvements. 


It is important to review the changelogs and make sure you understand what is changing. New features and improvements are likely to bring changes to interfaces, behaviour, and workflows. Our changelogs will help you identify which areas have changed, so you can then find information on new behaviours and workflows on this help site. This is important so that any internal training material you have can be updated and staff trainers can learn about what has changed.

You should also review any new administration settings, as new controls get added with every major release. These added controls may facilitate new functionality, improve security, or allow further customisation. Each setting should be reviewed so that you can check your Totara site configuration is current and understood.

System requirements may also change and although these will have no impact for those using the site, you will need review them to ensure they are met during deployment of the new release. 

Changelogs can be found published in the release notes area of the Totara community and in the product source code within the file.


User experience (UX) changes will mean that you will need to review your theme. It is likely there will be new places that need to be styled to make them look a part of your site. This is because HTML structure, CSS classes, and Javascript changes have been made. New features also bring new interfaces.

The Standard Totara responsive, Custom Totara responsive, bootstrap base, and Kiwifruit responsive themes have been removed from Totara v10+. You can read more in the Totara developer documentation.


Our APIs can change significantly between major releases. We have a deprecation policy that ensures that all changes where possible are backwards compatible, and that customisations will continue to function in the short term. When backwards compatibility is being used developer debugging information will be printed out to inform you that customisations and plugins will need to be updated. It is important these changes are made as backwards compatibility is only maintained for a limited time (typically one major release).

Incompatible API changes are rare, but they do occur. If you have customisations using API that no longer functions you will be presented with a debugging notice and you'll find that your customisations don't function as they should.

Totara registration

You may be prompted to register your Totara site - you can find more information on the Totara registration page.

More information

Further information can be found at Upgrading from Totara Learn 12 or below to Totara Talent Experience Platform.

Provide feedback about this page using the link in the bottom right of this page. 

 Still have questions? 

Why not post them in the forums on the Totara Community?

  • No labels