Upgrade from Tableau Server 2018.2 or Later (Windows)

To upgrade Tableau Server you install the new version while your existing version is running, then run an upgrade script to switch over to the new version. This reduces the amount of downtime for users because the server continues to run while you install the new version. You only stop the server to run the upgrade script.

Important: Upgrading Tableau Server on Windows from version 2018.1 or older requires special steps that are documented separately. For instructions for how to upgrade from a pre-2018.2 version, see Upgrade from Tableau Server 2018.1.x or Earlier (Windows).

General notes about upgrading:

All upgrades:

  • Backup—Create a backup. You are responsible for creating a backup of your existing Tableau Server data before upgrading. Beginning with 2018.2, upgrading no longer prompts you to create a backup of your old version when installing the new version. We strongly recommend creating a backup before upgrading as this provides you with an up-to-date version of your data you can use if you need to go back to your earlier version of Tableau Server. For more information on properly preparing for an upgrade, see Prepare for the Upgrade.

  • UninstallDo not uninstall your existing version before upgrading. When doing a TSM-to-TSM upgrade (version 2018.2.x to later version), you must leave your existing version in place and running until just before you upgrade using the upgrade script. If you uninstall your existing version before upgrading, you will not be able to upgrade. For your end-users, this has the impact of reducing downtime because you install your new version while the existing version is running. The only time the server is not running is during the period the upgrade script is actually upgrading to the new version.

  • Licenses

    • Trial product keys—You cannot directly upgrade a server that is running a trial product key from one major version to another (for example, from version 10.5.x to version 2018.x). To upgrade from one major version to another with a trial product key, install the new version of Tableau Server on a separate machine, activate a trial key there, and restore a backup from your existing version. For more information, see Confirm licensing requirements.

    • Expired maintenance—You cannot upgrade a server with a product key whose maintenance has expired or expires on a date earlier than the release date of the version you are upgrading to. If you attempt to upgrade a server in this state, your server will be unlicensed and the upgrade may fail. If your maintenance has expired or is too old, refresh your product key before you run the upgrade script to upgrade to your new version. If refreshing the key does not update maintenance to a valid date, check in the Tableau Customer Portal for a Tableau Server key with current maintenance. For details on refreshing the product key, see Refresh Maintenance Date for the Product Key.

  • Install location—When upgrading Tableau Server on Windows you cannot change the install location unless you completely remove all files and folders related to the previous installed version. If you do this, make sure you have a current backup file saved to a safe location. For information on how to completely remove Tableau, see Remove Tableau Server from Your Computer.

  • Install while running—When you upgrade Tableau Server 2018.2 or later, you install the new version before uninstalling the old version. The upgrade process will leave the old version in place. You can uninstall the old version after the upgrade is complete to free up disk space, though this is not required.

  • Multiple versions—After an upgrade, you will see multiple versions of Tableau Server in Control Panel. When you have completed the upgrade, you can uninstall the older version using Control Panel. Uninstalling the old version from Control Panel has no impact on the new, running version. Do not use the obliterate script to uninstall an old version. The script is intended to completely remove Tableau and will remove all versions from your computer.

  • Upgrade script—To complete the upgrade and switch to the new version, after installing the new version on all nodes in your cluster, run the upgrade script upgrade-tsm on the initial node. The script is installed in the \scripts.<version_code> folder . Open a command prompt with administrative permissions and run the script from the new version you just installed.

  • Antivirus software—Antivirus software that scans directories used by Tableau Server can interfere with installation and ongoing use of Tableau Server. In some cases, this can result in installation failures, problems starting Tableau Server, or impacts to performance. If you plan to run antivirus software on the computer running Tableau Server, follow the recommendations in the Knowledge Base.

  • Multiple folders —After an upgrade, you will see multiple versions of Tableau Server folders in the \packages folder. When the upgrade is completed successfully, you can delete the folders related to the older version you upgraded from. You can identify these by the version code in the folder name. For example, scripts.<version_code>. For more information about version codes, see View Server Version.

Multi-node upgrades:

  • Node installation—Run the installer on all nodes in a cluster. Unlike some distributed installation upgrades in versions prior to 2018.2, there is no automatic upgrade of any additional nodes.

  • Single installer—Use the same installer on all nodes, and specify when prompted whether you are upgrading the initial node, or an additional node. Unlike distributed installation upgrades in versions prior to 2018.2, there is no separate Setup program for the additional nodes. Starting with 2018.2 you use the same installer on all nodes.

  • Install while running—When upgrading from Tableau Server on Windows version 2018.2 to a later version, install the new version of Tableau Server on all nodes in the cluster, while the existing version is running. The existing version continues to run until you are ready to switch to the new version and complete the upgrade.

The steps below describe the general process for upgrading version 2018.2 or later of Tableau Server on Windows. Upgrades from beta versions of Tableau Server on Windows are not supported.

As a best practice you should always make a full backup before upgrading any version of Tableau Server. Save this backup file to a location that is not part of your server installation. Creating and saving a backup preserves your pre-upgrade data and configuration and gives you a rollback option in the event of issues during the upgrade. For more information, see Back up Tableau Server data.

When upgrading from Tableau Server 2018.2 or later, you do not uninstall the previous version. The upgrade process is designed to install a new version side-by-side with your existing version, and then switch from the earlier version to the later one. If you uninstall your current version before installing the new version you cannot upgrade properly. After installing the new version and upgrading, you can uninstall the previous version when you choose to do so. You can leave the older version installed indefinitely, though one reason you might choose to uninstall it is to free up disk space used by files specific to the older version. To understand the difference between uninstalling Tableau Server and completely removing all aspects of Tableau Server, see Uninstall Tableau Server.

Upgrading Tableau Server requires a stop and start the server as part of the upgrade process. During this stop/restart Tableau Server is unavailable.

Upgrading will also apply any pending changes. If you have pending changes you do not want applied, you can discard those changes using the tsm pending-changes discard command. To see what changes might be pending, use the tsm pending-changes list command.

Upgrade a Tableau Server single-node installation

Follow these steps to upgrade a single-node installation of Tableau Server.

  1. Confirm that your product key and maintenance are valid for the version you are updating to, and that you have refreshed the product key before upgrading. See the Licenses section above for details. If you do not have a valid product key with active maintenance, your upgrade will fail.

  2. Download or copy the new Tableau Server Setup program to the computer you are upgrading, or to a location accessible by the computer you are upgrading.

  3. Navigate to the folder where you copied the Tableau Server Setup program and run it.

    You will not be prompted for an install location. The Setup program determines where your existing version is installed and will install the new version side-by-side in the same location.

  4. When the installation is done, the last page of the Setup program tells you that the upgrade is not yet finished. You need to run an upgrade script to complete the upgrade. Before you can run the script you need to stop Tableau Server:

    • In TSM, click Tableau Server is running, and Stop Tableau Server:

      You will be prompted to confirm that you want to stop Tableau Server.

    • From a command prompt:

      1. Open a command prompt as administrator.
      2. Enter this command:

        tsm stop

  5. After Tableau Server is stopped, run the upgrade script in one of two ways.

    • From the Setup program:

      1. Select Automatically launch the upgrade script, and click OK:

      2. A command window will open for the script. Because you are logged in as a user with local administrator rights, the script will run using your credentials. If you are prompted, enter your password.

    • On the command line:

      1. On the initial node, open a command prompt as administrator.

      2. Navigate to the scripts folder for your new installation.

        By default:

        C:\Program Files\Tableau\Tableau Server\packages\scripts.<version_code>\

      3. When Tableau is stopped, run the upgrade script:

        upgrade-tsm

        Because you are logged in as a user with local administrator rights, the script will run using your credentials. If you are prompted, enter your password. You can specify a different user and password when you run the script using --username and --password options.

        To see all options for the upgrade-tsm script, use the -h option:
        upgrade-tsm -h

        Note: If you run the script from the scripts.<version_code> folder for your older version, the upgrade will fail with an error:

        "Tableau Server Version change validation failed."
        "Tableau Server <version> is already installed."

  6. Start Tableau Server. You can do this from the TSM web UI or from a command prompt:

    • In TSM, click Tableau Server is stopped, and Start Tableau Server:

    • From a command prompt:

      1. Open a command prompt as administrator.

      2. Enter this command:

        tsm start

        If you get an error that the command is not recognized, close all command windows and then open a command prompt as administrator.

Upgrade a Tableau Server multi-node installation

Follow these steps to upgrade a multi-node installation of Tableau Server:

  1. Confirm that your product key and maintenance are valid for the version you are updating to, and that you have refreshed the product key before upgrading. See the Licenses section above for details. If you do not have a valid product key with active maintenance, your upgrade will fail.

  2. Download or copy the new Tableau Server Setup program to all Tableau Server nodes you are upgrading, or to a location accessible by all the nodes. You will need to run this Setup program on all the nodes.

  3. On the initial node, navigate to the folder where you copied the Tableau Server Setup program and run it. This will install the new version of Tableau Server side-by-side with your existing, running version.

    You will not be prompted for an install location. The Setup program determines where your existing version is installed and will install the new version side-by-side in the same location.

    Important: When the installation is done, the last page of the Setup program tells you that the upgrade is not yet finished. Do not run the upgrade script until after you have installed the new version on all nodes in your cluster. Leave the Setup window open on the initial node and continue with your installation on all the other nodes.

  4. On each additional node, navigate to the folder where you copied the Tableau Server Setup program and run the Setup program. This will install the new version of Tableau Server on each node, side-by-side with your existing, running version.

    Important: When the installation is done, the last page of the Setup program tells you that the upgrade is not yet finished. Make sure "Automatically launch the upgrade script" is notselected, and close the Setup window.

  5. After installing the new version on every node in the cluster, stop Tableau Server.

    You can do this in TSM from web UI, or from a command prompt:

    • In TSM, click Tableau Server is running, and Stop Tableau Server:

    • From a command prompt on the initial node:

      1. Open a command prompt as administrator.
      2. Enter this command:

        tsm stop

  6. After Tableau Server is stopped, run the upgrade script on the initial node.

    If the final Setup screen is still open, you can select Automatically launch the upgrade script and a command window will open to run the script. Alternately, you can run the script directly from a command prompt.

    • To run the upgrade script from the Setup program:

      1. Select Automatically launch the upgrade script and click OK:

      2. A command window will open for the script. Because you are logged in as a user with local administrator rights, the script will run using your credentials. If you are prompted, enter your password.

    • To run the upgrade script from a command prompt:

      1. Open a command prompt as administrator.
      2. Navigate to the scripts directory for the new version you just installed.

        By default:

        C:\Program Files\Tableau\Tableau Server\packages\scripts.<version_code>\

      3. Run the upgrade script:

        upgrade-tsm

        Because you are logged in as a user with local administrator rights, the script will run using your credentials. If you are prompted, enter your password. You can specify a different user and password using the --username and --password options.

        To see all options for the upgrade-tsm script, use the -h option:

        upgrade-tsm -h

        Note: If you accidentally run the script from the scripts.<version_code> folder for the earlier version, the upgrade will fail with an error:

        "Tableau Server Version change validation failed."

      The upgrade script will take some time to complete.

  7. When the upgrade script completes, start Tableau Server. You can do this from the TSM web UI or from a command prompt:

    • In TSM, click Tableau Server is stopped, and Start Tableau Server:

    • From a command prompt:

      1. Open a command prompt as administrator.
      2. Enter this command:

        tsm start

If you have purchased the Tableau Data Management Add-on or the Tableau Server Management Add-on you can activate them once you have completed your upgrade. For more information, see the following topics:

 

Thanks for your feedback! There was an error submitting your feedback. Try again or send us a message.