How to Update Tableau Server

Updating your Tableau Server is one of those essential maintenance tasks that ensures you have the latest features, security patches, and performance improvements. This guide provides a modern, step-by-step walkthrough for upgrading Tableau Server using the TSM (Tableau Services Manager) command line, which is the standard for versions 2018.2 and later.

Graphed

Your AI Data Analyst to Create Live Dashboards

Connect your data sources and let AI build beautiful, real-time dashboards for you in seconds.

Build Your First Dashboard

Why Update Your Tableau Server?

If your current server version is working, it can be tempting to put off an update. However, staying current provides several serious advantages that directly impact your users and your organization's security.

• Access New Features: Each release introduces new visualizations, connectors, and quality-of-life improvements. Features like Dynamic Zone Visibility, improved Map Layers, and advances in Ask Data empower your users to find more insights.
• Strengthen Security: New versions include critical patches for security vulnerabilities. Running an outdated server is like leaving a door unlocked - it exposes your data to unnecessary risks.
• Boost Performance: The Tableau development team is constantly optimizing the platform. Updates often bring significant performance gains, faster dashboard loads and faster extract refreshes make for happier, more productive users.
• Resolve Known Bugs: Every software has bugs. Updates provide fixes that resolve known issues, creating a more stable and reliable analytics environment for everyone.
• Maintain Support and Compatibility: Tableau only provides full support for recent versions. Staying current ensures you can get help when you need it and that your server remains compatible with modern operating systems and data sources.

Your Pre-Update Checklist: Planning for a Smooth Upgrade

Proper preparation is the most critical part of a successful Tableau Server update. Rushing this stage is where things typically go wrong. Spending 30 minutes on this checklist can save you hours of stressful troubleshooting later.

1. Read the Release Notes

Before you do anything else, read the official release notes for the version you're upgrading to. Don't just skim them! They contain vital information about "breaking changes," deprecated features, and any new system requirements. Pay close attention to the section on "Known Issues" to see if anything might impact your specific environment or workbooks.

2. Verify System Requirements

While minor updates rarely change requirements, major version jumps often do. Double-check that your server hardware (CPU, RAM) and available disk space meet or exceed the minimum specifications for the new version. Running a resource-intensive upgrade on an undersized machine can lead to a failed installation.

AI for Data Analysis

Crash Course

Graphed

Free PDF Guide

AI for Data Analysis Crash Course

Learn how to get AI to do data analysis for you — the best tools, prompts, and workflows to go from raw data to insights without writing a single line of code.

Download Free Guide

3. Schedule Downtime and Communicate

You cannot perform an in-place upgrade on a running Tableau Server. The process requires taking the server offline, so you must schedule a maintenance window. Choose a time with low usage, like a weekend or overnight. More importantly, communicate this planned outage to your users. A simple email or Slack message like, "Heads up, team! Tableau Server will be down for a required system update from 10 PM Friday to 2 AM Saturday," prevents a flood of panicked support tickets.

4. Create a Full Backup (The Golden Rule)

If you only do one thing on this checklist, make it this one. A full backup is your ultimate safety net. If anything goes wrong during the upgrade - a power outage, a failed script, an unexpected error - you can restore from this backup and get back to a working state. You can create a backup using the TSM command line.

First, open Command Prompt as an Administrator on your server machine. Then, run the following command:

tsm maintenance backup -f your_backup_name -d

• The -f your_backup_name flag specifies the name of the backup file (e.g., pre_upgrade_2023_10_27.tsbak).
• The -d flag adds the current date to the filename, which is a great best practice for versioning.

Once the backup is complete (this can take time depending on your server's size), copy the resulting .tsbak file to a separate machine or a network drive. A backup file on a server that fails to boot is not very useful!

5. Gather Your Resources

Finally, gather everything you'll need before you start:

• Administrator credentials for the Windows Server or Linux machine.
• Your Tableau Server administrator username and password.
• The downloaded installer executable for the new version of Tableau Server from the official product downloads page.

Step-by-Step Guide to Updating Tableau Server

With your checklist complete, you're ready to begin the update. Follow these steps methodically. The entire process typically takes between 30 and 90 minutes, depending on the size of your repository and the performance of your server.

Graphed

Your AI Data Analyst to Create Live Dashboards

Connect your data sources and let AI build beautiful, real-time dashboards for you in seconds.

Build Your First Dashboard

Step 1: Stop the Server

The first step in the actual update process is to gracefully shut down all Tableau Server services. This ensures that no processes are running or holding files open when the installer tries to make changes.

In your administrator command prompt, run:

tsm stop

Wait for the command to complete. It will confirm that all services have been stopped successfully.

Step 2: Run the New Installer

Navigate to the folder where you saved the downloaded Tableau Server installer file. Right-click on the .exe file and select "Run as administrator." The installer will automatically detect your existing installation and inform you that it will perform an upgrade. Follow the prompts, accepting the license agreement and confirming the install location (which should default to your current directory).

Step 3: Run the Upgrade Script

This is the most important step in a TSM upgrade. After the installer finishes laying down the new files, you must run a special script to migrate your old configuration and repository data to the new version's format. The installer doesn't do this for you.

The installer should automatically open a terminal window in the new scripts directory. If it doesn't, navigate there manually. The path will look something like this (the version number will change):

C:\Program Files\Tableau\Tableau Server\packages\scripts.<new-version>\

Once you are in that directory in your command prompt, execute the upgrade script:

upgrade-tsm.cmd

The script will start, providing detailed output as it progresses through various stages like decommissioning the old version, upgrading the repository database, and applying saved configuration changes. Grab a coffee, this part takes the most time. Do not close the command window until it explicitly says it has completed.

AI for Data Analysis

Crash Course

Graphed

Free PDF Guide

AI for Data Analysis Crash Course

Learn how to get AI to do data analysis for you — the best tools, prompts, and workflows to go from raw data to insights without writing a single line of code.

Download Free Guide

Step 4: Start the Server

Once the upgrade script has triumphantly finished, it's time to bring your newly updated server back to life. In the same command prompt, simply run:

tsm start

Step 5: Verify the Upgrade

Now that the server is running, the final step is to confirm everything worked as expected.

• Check the version: Log into the Tableau Server web interface. Click the information icon ("i") in the top-right corner and select "About Tableau Server." The dialog box should show the new version number you just installed.
• Test Functionality: Navigate to a few different Projects and open complex dashboards. Interact with some filters and test a data source connection to ensure workbooks are rendering and behaving correctly.
• Let Your Users Know: Send a follow-up communication to your users letting them know the update is complete and the server is available. It's also helpful to point out one or two of the new features they can now use.

After the Update: Verification and Common Issues

Once the critical path is done, there are a few final clean-up items and common issues to be aware of.

Quick Post-Upgrade Tasks

• Clear Browser Cache: Recommend that your users clear their browser caches. This ensures they load the new version of the web interface files and prevents weird visual glitches caused by cached files from the old version.
• Monitor Logs: Keep an eye on the server for the next day or so. Check status pages and administrative logs to catch any unusual activity or recurring errors early.

Common Troubleshooting Tips

• Problem: The upgrade-tsm script fails mid-process. Solution: Don't panic. The script creates detailed logs. Check the output in the command window for the location of the log file and look for keywords like "ERROR" or "FATAL." The error is often self-explanatory (e.g., "Insufficient disk space"). If you can't resolve it, this is when you use your backup. You would need to obliterate the failed installation and restore from your pre-upgrade backup.
• Problem: The server won't start after the upgrade (tsm start fails). Solution: Run tsm status -v to see which specific service or process is failing to launch. The most common culprits are the Repository (PostgreSQL) and the VizQL Server. Check the logs for that specific process to find the root cause. This could be due to permission changes or port conflicts.
• Problem: Some dashboards are broken or throw data source errors. Solution: This often happens if the dashboard connects to a database requiring a driver (like Oracle, Snowflake, etc.). A major Tableau Server upgrade may require you to install a new, compatible version of that database driver on the server.

Final Thoughts

Updating Tableau Server requires careful planning and a methodical approach, but following this checklist and step-by-step process demystifies it. By running regular backups, scheduling downtime, and working through the TSM commands, you can keep your analytics platform modern, secure, and full of valuable new features for your users.

While maintaining server infrastructure like Tableau is crucial, getting answers from your unique marketing and sales data shouldn't be so complex. We built Graphed to connect to data sources like Google Analytics, Shopify, and Salesforce in seconds, automatically handling the complexity of data pipelines and warehousing. Instead of wrestling with server configurations or learning a new BI tool, you can simply ask questions in plain English to create live dashboards, letting you focus on strategy and insights, not software maintenance.