How to Upgrade Tableau Server
Upgrading your Tableau Server is one of the most important maintenance tasks you’ll perform. It keeps a critical part of your data stack secure and performant, giving your users access to the latest features. This guide provides a clear-cut, step-by-step path to help you plan and execute a smooth upgrade with confidence.
Why Bother Upgrading Tableau Server?
Before jumping into the nuts and bolts, it's worth understanding why this process is so important. An upgrade isn't just about getting a new version number, it brings tangible benefits to your organization.
Access to New Features and Functionality
Tableau is constantly evolving. Each major release introduces powerful new capabilities like dynamic zone visibility, new connectors, improved mapping layers, and enhancements to Tableau Prep. By staying current, you empower your analysts and users with the latest tools to discover insights.
Enhanced Performance and Stability
Upgrades often include significant performance optimizations. These aren't always headline features, but they can dramatically speed up workbook loading times, data extract refreshes, and overall server responsiveness. Tableau also fixes bugs and stability issues from previous versions, leading to a more reliable platform for everyone.
Critical Security Patches
In today's environment, security is paramount. New releases contain patches for potential vulnerabilities in third-party libraries and the platform itself. Running an outdated version of Tableau Server can expose your organization to unnecessary security risks. Regular upgrades are a core part of responsible data governance.
Improved Compatibility
The tech world moves fast. A server upgrade ensures compatibility with the latest operating systems, web browsers, and data source drivers. This prevents frustrating issues where a user updates their browser only to find it no longer works perfectly with your older Tableau Server version.
The Pre-Upgrade Checklist: Your Plan for Success
A successful Tableau Server upgrade is 90% preparation and 10% execution. Rushing this stage is the number one cause of unexpected problems. Follow this checklist to ensure you've covered all your bases before you begin.
1. Read the Release Notes (Seriously)
Each version has its own Release Notes and "Known Issues" page. Reading these isn't optional. They contain vital information about deprecated features, required driver updates, changes in behavior, and potential breaking changes that could impact your existing content. Pay special attention to the "Upgrade" section.
2. Verify System Requirements
Don't assume your current hardware is sufficient for the new version. Check the official Tableau Server Technical Specifications for the version you're upgrading to. Confirm your:
Operating System: Is your Windows Server or Linux distribution still supported?
Hardware: Do you meet the minimum - and ideally, the recommended - requirements for CPU cores, RAM, and especially disk space? The upgrade process itself temporarily requires significant free disk space.
3. Communicate with Your Users
Nobody likes downtime, but unexpected downtime is worse. Proactively inform your users about the planned upgrade window. Send out reminders leading up to the maintenance period, explaining the benefits they'll get from the new version. This builds trust and prevents a flood of support tickets.
4. Perform a Full Backup
This is your non-negotiable safety net. If anything goes wrong, a recent backup is the only way to restore your environment to its previous state. Perform a complete backup and, crucially, copy the backup file to a separate location off the Tableau Server machine.
Use the following TSM (Tableau Services Manager) command:
5. Export Your Configuration and Topology
Alongside the main backup, save a copy of your server's settings and topology. This file contains registration data, configuration settings, and details about how your processes are distributed in a multi-node environment.
6. Run a Test Upgrade (Highly Recommended)
Ideally, you have a non-production environment that mirrors your production setup. Restore your latest production backup to this test server and run through the entire upgrade process there first. This is the single best way to discover environment-specific issues, test critical dashboards on the new version, and accurately estimate how long the real upgrade will take.
7. Clean Up Your Server
A leaner server upgrades faster. Before you begin, perform some housekeeping:
Run
tsm maintenance cleanup -ato remove old log files, temp files, and repository entries.Consider archiving or removing unused workbooks and data sources to reduce the size of the repository.
8. Download the Correct Installer
Navigate to the Tableau Customer Portal or the official Release Notes page to download the installer for your target version. Ensure you get the correct one for your operating system (Windows or a specific Linux distribution).
The Step-by-Step Upgrade Process
Once your pre-upgrade checklist is complete, you're ready to start the actual upgrade. The following steps outline the standard in-place upgrade process using the upgrade-tsm script.
Step 1: Start on the Initial Node
Your upgrade always begins on the initial node of your Tableau Server cluster (or the only node, for single-server installations). Copy the installer you downloaded to this machine.
Step 2: Sign in as an Administrator
On Windows, right-click and run Command Prompt as an Administrator. On Linux, open a terminal session and use sudo for your commands. This is crucial as the upgrade process needs elevated permissions.
Step 3: Run the Installer Package
Execute the installer file you downloaded. The installer will extract the new version's files into a new /packages directory, leaving the old version's files untouched for now. This step does not upgrade the server - it just prepares the new files.
Step 4: Execute the upgrade-tsm Script
This is the main event. This script will stop the server, perform the upgrade on the database and core components, and restart the server with the new version. Navigate to the scripts directory of the newly installed version. The path will look something like this:
On Windows:
On Linux:
The script will run for a while, often 30-60 minutes or more depending on the size of your repository. You’ll see a series of step-by-step checks and updates. Do not close the command window during this process.
Step 5: Handle Multi-Node Environments (If Applicable)
If you have a multi-node cluster, you only run upgrade-tsm on the initial node. After it's complete, you can run the installer on each additional node. The installer will detect the upgrade and handle the next step for you. In older versions, you may have had to run scripts manually, but recent installers streamline this process.
Step 6: Verify the Upgrade
Once everything is finished, the final step in the script will state that the upgrade completed successfully and the server is running. Now, verify its health:
Log into the Tableau Server web UI. The version number in the bottom right corner should reflect the new version.
Navigate to the Server Status page and confirm all processes show a green "Active" status.
Open a few key dashboards and data sources to ensure they render correctly and can connect to their underlying databases.
Post-Upgrade Best Practices
Your server is running on the new version, but the job isn't quite done. These final steps will ensure a clean, stable environment moving forward.
Re-enable Any Suspended Tasks
During the upgrade, Tableau Server may have suspended schedules for subscriptions and extract refreshes. Go to the "Tasks" section on the Server UI and ensure your critical schedules are enabled and ready to run.
Take a Post-Upgrade Backup
Now that your server is successfully upgraded and stable, take another full backup using the tsm maintenance backup command. This creates a new, clean restore point on the new version.
Remove the Old Files
After you are completely confident that the new version is stable (maybe after a few days or a week of normal usage), you should remove the old version's files to reclaim disk space. Be warned: this step is irreversible.
Use the tableau-server-obliterate script with the -l flag to perform a "local" removal that preserves your data and settings while deleting the old file versions:
Let Your Users Know
Send a final communication announcing that the upgrade is complete. Highlight one or two of the key new features they can now use to encourage adoption and demonstrate the value of the maintenance window.
Final Thoughts
Upgrading Tableau Server is a deliberate process that rewards careful planning. By following a structured approach - from the pre-upgrade checklist to the post-upgrade cleanup - you can ensure a seamless transition that minimizes downtime and enhances your organization's analytics capabilities. This keeps your platform secure, performant, and equipped with the latest tools for data discovery.
Maintaining a powerful Business Intelligence platform like Tableau Server is essential, but the ultimate goal is to empower everyone on your team - even those who aren't data experts. After your successful upgrade, consider how your marketing or sales teams access insights. For teams that need answers fast without a steep learning curve, we built Graphed . It allows anyone to connect directly to sources like Google Analytics, Facebook Ads, or HubSpot and create dashboards in seconds using simple, natural language, turning hours of reporting work into quick conversations.