Note 1 XWiki provides migration paths to upgrade from any older version to any newer one. You don't need to upgrade to intermediary versions.

Note 2 It's also good to check the Release Notes for the versions between your old version and the new version you're upgrading to. You should pay an extra care about the section in the release notes entitled "Issues specific to XWiki <version>". For example, it's important to check if the new version of XWiki you're upgrading to has new hardware of software requirements.

Backup Before you proceed, be sure to backup all of your data, just in case something goes wrong with the update / downgrade. Depending on your usage, you should be backing up your information regularly.

Extensions Before upgrading XWiki itself it's generally a good idea to make sure that all your extensions are up to date since new versions might contain compatibility fixes that would have otherwise preventing the new version fully start.

Upgrading

Keep your XWiki instance up to date to benefit from the best new features and keep your data safe from security threats. There are multiple methods to upgrade XWiki depending on how many data you need to migrate or how experienced you are with different tools.

In the majority of cases an upgrade consists of two parts:

• Part 1: Upgrading the distribution on the server / filesystem and 
• Part 2: Upgrading the flavor (wiki pages) from a browser.

Part 1 Upgrading the distribution

Method Demo Upgrading from the Demo package

• If you've installed the standard distribution (zip or jar distribution) and you wish to upgrade it, the simplest is to download the new version and install it as you did the first time. Just make sure you don't install the new version over the old one (both installations need to exist).
• Then copy the configuration files and the permanent directory from the old installation to the new one. Ideally you should not copy over the configuration files exactly since the new version could have added new configuration options and thus ideally you should do a merge instead of a pure copy. Another strategy is to use the new configuration files, not copy over the old configuration files and instead manually edit the new configuration to make the same changes as you have may done before (If you've never touched the configuration files then there's nothing to do obviously!).

• If you're on a unix system here are some commands that may help you doing the merge instead of doing it fully manually:

  ## Note: We're assuming that "xwiki.new" is a symbolic link that points to the location
  ## where the new xwiki version is located and that "xwiki" is the location of the previous
  ## xwiki installation.
  mv xwiki.new/WEB-INF/web.xml xwiki.new/WEB-INF/web.xml.ori; sudo sdiff xwiki/WEB-INF/web.xml xwiki.new/WEB-INF/web.xml.ori -B -W -E -o xwiki.new/WEB-INF/web.xml
  mv xwiki.new/WEB-INF/xwiki.cfg xwiki.new/WEB-INF/xwiki.cfg.ori; sudo sdiff xwiki/WEB-INF/xwiki.cfg xwiki.new/WEB-INF/xwiki.cfg.ori -B -W -E -o xwiki.new/WEB-INF/xwiki.cfg
  mv xwiki.new/WEB-INF/xwiki.properties xwiki.new/WEB-INF/xwiki.properties.ori; sudo sdiff xwiki/WEB-INF/xwiki.properties xwiki.new/WEB-INF/xwiki.properties.ori -B -W -E -o xwiki.new/WEB-INF/xwiki.properties
  mv xwiki.new/WEB-INF/struts-config.xml xwiki.new/WEB-INF/struts-config.xml.ori; sudo sdiff xwiki/WEB-INF/struts-config.xml xwiki.new/WEB-INF/struts-config.xml.ori -B -W -E -o xwiki.new/WEB-INF/struts-config.xml
  mv xwiki.new/WEB-INF/classes/logback.xml xwiki.new/WEB-INF/classes/logback.xml.ori; sudo sdiff xwiki/WEB-INF/classes/logback.xml xwiki.new/WEB-INF/classes/logback.xml.ori -B -W -E -o xwiki.new/WEB-INF/classes/logback.xml

• Note that the database schema is automatically upgraded when needed. All you need to do is to ensure your xwiki.cfg file is correctly configured to perform the migration. Here's a relevant excerpt from the xwiki.cfg file:

  #-# Whether migrations are enabled or not. Should be enabled when upgrading, but for a better startup time it is better to
  #-# disable them in production.
  xwiki.store.migration=1
  
  #-# Whether to exit after migration. Useful when a server should handle migrations for a large database, without going
  #-# live afterwards.
  # xwiki.store.migration.exitAfterEnd=0
  
  #-# Indicate the list of databases to migrate.
  #-# to upgrade all wikis database set xwiki.store.migration.databases=all
  #-# to upgrade just some wikis databases set xwiki.store.migration.databases=xwiki,wiki1,wiki2
  #-# Note: the main wiki is always migrated whatever the configuration.
  # xwiki.store.migration.databases=

  From a failed migration the database tables DATABASECHANGELOG and DATABASECHANGELOGLOCK may be left over.
  Ensure that these tables are dropped before restarting a failed migration.

Part 2 Upgrading the flavor

Using Distribution Wizard

Recommended The recommended way to upgrade an XWiki installation is to use the Distribution Wizard which is automatically triggered after you upgrade the XWiki WAR (you need to be logged with a user having admin rights). It allows you to automatically upgrade extensions installed in your wiki, supporting automatic merges and conflict resolution.

If you're upgrading an XWiki far (i.e. a wiki with multiple sub-wikis), you'll need to navigate to each subwiki. You'll then be presented with the Distribution Wizard for each wiki that requires an upgrade.

Alternative Start fresh, plus Export and Reimport your data

There are cases when all you can do is export your current content as a XAR and reimport it into a new instance. You should use this method when you know exactly what content you have created and you manually check to not forget anything on the old instance.

Some tips:

• Make sure to only import your own content pages and not the default XWiki pages since you’d overwrite the ones provided in new XWiki install.
• You may get issues when trying to export a large XAR. In that case you may want to try installing one of the Export Extensions but you'll need to verify that the one you install will work on your old version of XWiki.

Downgrading

A previous upgrade may have modified the database schema and the data saved in the permanent directory may also have incompatible changes. Thus the best strategy for downgrading is using the Alternative Method, and that consists of exporting your wiki pages as XAR (the ones having your content, not the default wiki pages provided by the XWiki distribution or installed Extensions). Then install the older XWiki version and re-install optional Extensions that you need. Then reimport your XAR in it.

Troubleshooting

XWiki won't start without any error in the log and stay stuck on Solr initialization

Solr has a tendency to lock itself when it has several cores to initialize. To workaround that, XWiki started creating new cores with an option to disable loading the core during Solr init (it's loaded during its first use), but you might still have some existing cores without this option set, in which case you will have to set it by hand: go to <permdir>/store/solr/ and edit each core core.properties file to add loadOnStartup=false