How to Upgrade XNAT

There are a couple different update methodologies you can pursue:

This is appropriate if you are still in test mode and do not need to preserve the data you've previously uploaded to your XNAT installation.

New Release / Old Database

Download the full release, and set it up in tandem to your old version, but re-use your prior database.

Previous versions of XNAT required that all customizations be placed into the projects folder under your XNAT builder folder. This documentation said that you should copy that folder over from your existing XNAT builder into the projects of your new XNAT builder when upgrading. This step has changed and is documented in more detail below.

Updates and Upgrades

New Release / New Database

Follow the steps in the  installation guide  to complete the installation. If you've made modifications to your projects directory, perform the following steps after Step 4 in the installation guide.

  1. Migrate your XNAT customization code.
  2. Update.

New Release / Old Database

If you haven't written custom code for XNAT, or your only customizations are in xnat/projects:

  1. If your Tomcat server is running, shut it down.
  2. Back up your current XNAT installation.
  3. Extract or download the copy of your new version of XNAT into a different location from your previous one.
  4. Configure in the new release, using your old as a guide.
  5. Run the bin/ script to initialize your new release.  This is the same as step 4 in the installation guide (also, be aware of any breaking changes). Note that, for this step, you should run bin/ without the -Ddeploy=true option, even if you normally build or update with that option turned on.
  6. If you have any project customizations from your previous installation, migrate them to the new version.
  7. Delete the old XNAT web application from your Tomcat installation. If you've installed by war file, you'll want to make sure you delete both the war and the exploded application folder if it exists.
  8. Run the bin/ script. Here you can specify the -Ddeploy=true option if you normally use that method for deploying your application.
  9. Run the deployments/project/sql/project-update.sql database update script. For a project named 'xnat':

    psql -f deployments/xnat/sql/xnat-update.sql xnat
  10. Migrate scan times from their pre-1.6 location in the schema by downloading the scan time update script and running it. See below

If you've modified the file–for example, to add an LDAP authentication repository–you should compare your version of this file with the updated version. The primary concern is not values that are different–those would mostly be due to configuration-specific differences–but properties that have been added to the core XNAT development version that won't be present in your customized copy of You will need to merge any changes between the two files into your deployed XNAT web application.

If you've customized xnat_builder (assuming you forked it at some point in the past):

  1. Take a backup.
  2. Pull xnat_builder from BitBucket and merge with your changes.
  3. Update.
  4. Migrate scan times from their pre-1.6 location in the schema by downloading the scan time update script and running it. See below

Another option: Use pgdump to duplicate your database, and upgrade using that copied database. This will allow you to leave your old site up and running until you are comfortable that your upgrade was successful. To do this, you should modify the database connection parameters in after you copy it to the new installation.

If you've built your upgraded XNAT in a different folder from your previous version and use the standard pipeline engine installed under the xnat_builder folder, or if you've installed your upgraded pipeline engine in a folder separate from your xnat_builder but in different folder from your previous version, you need to make sure you change the configured location of your pipeline in your upgraded XNAT installation before running any pipelines, including archiving new sessions, which implicitly invokes the auto-run pipeline:

  1. Log into your upgraded XNAT with an administrator account.
  2. Click the Administer->Configuration menu command.
  3. Select the File System tab.
  4. Enter the new location for your pipeline engine in the Pipeline Installation Location text box.
  5. Click the Save button.

If you don't make this change, you may see all kinds of weird errors, including failing to generate snapshots of your newly archived sessions, verbose messages in error logs, etc.

Migrating XNAT Customizations During XNAT Upgrades

Migrating the projects folder is the "traditional" (for lack of a better term) method of carrying over customizations from one version to the next. This is problematic, though, since things that have changed in the meantime may not be updated in the projects folder, meaning that you'll be getting old code instead of the new release.

Optimally, you'd manage this by having all of your customization code in modules. If you already have all of your XNAT customizations in modules, you can simply delete the projects and deployments folders and re-run setup and update (this ordering is necessary since update generates the SQL script to update database based on any changes in the data-type schema). This generates your projects and deployments folders again on the setup and creates your database migration script on the the update. Both scripts will process any modules you have in the specified module repo folder.

If you don't have all of your XNAT customization code in modules, you can keep your existing projects folder and copy over only those files that are part of your own customizations. This may be easier said than done, especially if you've worked on lots of little bits of code over a period of years. In that case, you can perform a diff of your projects folder with a vanilla XNAT projects folder from your previous release. To get the vanilla projects folder for this purpose, you could download, for example, the builder from:

Run setup on this without the deploy flag set to true (i.e. just bin/ You should be able then to diff your projects folder with the newly generated one and get a good idea of what's changed.

Take a Backup

  • Backup your database (using pgdump or pgAdminIII)
  • Backup your xnat webapp by making a copy of XNAT_HOME\deployments\xnat\target\xnat.war (if it's not there, run the update script w/o the deploy=true flag).  

Migrating Pre-1.6 Scan Times for XNAT 1.6.x

If you are upgrading, you should run the deployments/project/sql/project-update.sql script before running the scan-time migration script.

If you have made any customizations, either in xnat_builder or in your own projects, and any of your customized files use scan time, you should modify those files manually. Scan time was previously stored in:

  • xnat:mrScanData/parameters/scanTime
  • xnat:ctScanData/parameters/scanTime
  • xnat:petScanData/parameters/scanTime
  • xnat:optScanData/parameters/scanTime

No other modalities had a scan time attribute.  The replacement is for these separate scan times is xnat:imageScanData/startTime . To migrate the old scan time attributes to use the new start time attribute, we've provided a migration script that only needs to be run once when migrating from a pre-1.6 database. To perform this migration:

  1. Shut down Tomcat if it's running.
  2. Run the scan-time update script:
    psql -U postgres -d xnat -f scan_time_update.sql
  3. Restart Tomcat.