Upgrading TestRail From 9.4.1 through 10.3.1 in Unix/Linux

Updated May 14, 2026 16:10

TestRail 10.3.1 is available for all Server customers. Customers who wish to upgrade to TestRail 10.3.1 can download the installation files from the TestRail Billing Portal.

Below, you will find information on how to upgrade an existing TestRail installation from any supported version (starting at 9.4.1) to any later version. You can use this document whether you are upgrading to 10.3.1 or to any earlier supported target version (starting at 9.4.1). Please follow these steps to upgrade your TestRail installation.

ℹ️ Important Note:

Starting with TestRail 9.5.1 Server, Cassandra is officially deprecated and enforcement is in place.

Admins must first run the Cassandra deprecation script in version 9.4.1 before upgrading to more recent versions.
If the script has not been executed, the upgrade to more recent versions will be blocked and a warning message will be displayed during the upgrade process.

👉 Please check our Cassandra Deprecation documentation.

Backup

It is strongly recommended to make a backup of your TestRail installation files and TestRail database before upgrading to a newer version. In case there’s a problem with the upgrade, a backup is the only way to roll back the changes and revert to your previous (working) installation. We recommend making backups of your TestRail installation and database regularly, especially before upgrading to a newer version.

Requirements

Before proceeding with an upgrade to TestRail, please review the requirements documentation and operating specific instructions (Windows/Linux). Software dependencies such as PHP and SQL can change over time, so it is important to review these requirements prior to updating your TestRail software.

Install Chrome Headless Shell Dependency

1. Open your preferred terminal application and run:

sudo apt update
sudo apt install -y wget unzip libnss3 libatk1.0-0 libxcomposite1 libxdamage1 libxrandr2 libgbm1 libxkbcommon0 libasound2 libatk-bridge2.0-0 libxfixes3

2. Download Latest Chrome Headless Shell, and in your terminal, run the following commands:

cd /tmp
LATEST_VERSION=$(wget -qO- https://googlechromelabs.github.io/chrome-for-testing/LATEST_RELEASE_STABLE)
Wget https://storage.googleapis.com/chrome-for-testing-public/${LATEST_VERSION}/linux64/chrome-headless-shell-linux64.zip

3. Unzip and Move the Binary. You can now unzip the binary and move it to your preferred location. Keep note of the location where you will move the binary, as you will need to add this path to the TestRail configuration.

unzip chrome-headless-shell-linux64.zip
sudo mv chrome-headless-shell-linux64 /usr/bin/

4. Set Permissions. Make sure that the web user has sufficient permissions to run the Chrome binary:

sudo chown www-data:www-data /usr/bin/chrome-headless-shell-linux64 -R
sudo chmod 775 /usr/bin/chrome-headless-shell-linux64 -R

Remove Old Files and Extract New Installation Files

To upgrade your TestRail installation, in TestRail 10.3.1 you must delete all old installation files in the instance's folder, except for the user-created files/folders (e.g. config.php, logs, and audit folders), before extracting the TestRail 10.3.1 archive.

Some web server configurations can prevent files from being overridden while the web server is active. You need to stop the web server before replacing TestRail’s installation files. This happens mainly with Windows/IIS systems, so if you have upgrade issues, try stopping the web server and overriding the files again.

Once the files have been replaced, the instance has been upgraded.

Update Jira token configuration (Required for versions below 10.1.4)

If you are upgrading from a version earlier than 10.1.4, you must update the Jira token configuration file as part of this process.

Download the update files here.
Update the files
1. Locate your TestRail installation path
2. Replace app/config/consts.php with the updated version provided
3. Set the correct file ownership.
```
chown www-data:www-data <TestRail installation path>app/config/consts.php
```

Now, you will need to add a new entry in config.php:

define('TR_CHROME_PATH', '/usr/bin/chrome-headless-shell-linux64');

Once the above has been done, you can Log into the instance via a web browser (usually ‘http://localhost/testrail/’ or something similar) to confirm a successful upgrade.

Clear browser cache

Once the upgrade has been confirmed, all end-users will be required to clear their browser cache so the jQuery upgrade will take effect. Please follow the following steps to accomplish this on each of our supported browsers:

Troubleshooting

If you override current TestRail installation with new files, then you have to delete a folder from the previous version before extracting installation files for the new version:

- /app/libraries/PhpSpreadsheet folder