Install & Compatibility
Where this runs
tested against v0.41 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.468s · 24.6MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 2.6s · import 0.430s · 25MB
23MB installed
● package 23MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
TSC
✓ import tableauserverclient as TSC
This is the universally accepted alias for convenience and readability.
Server
✓ from tableauserverclient import Server
✗ from tableauserverclient.server import Server
Direct import from the top-level package is preferred; internal module structure might change. Generally accessed via TSC.Server.
TableauAuth
✓ from tableauserverclient import TableauAuth
Standard authentication method for username/password, though PersonalAccessTokenAuth is often recommended for automation. Generally accessed via TSC.TableauAuth.
PersonalAccessTokenAuth
✓ from tableauserverclient import PersonalAccessTokenAuth
Recommended authentication method for scripting and automation. Generally accessed via TSC.PersonalAccessTokenAuth.
This quickstart demonstrates how to connect to Tableau Server or Tableau Cloud using a Personal Access Token (PAT) and retrieve a list of all workbooks on a specified site. It uses environment variables for sensitive credentials and includes basic error handling.
import tableauserverclient as TSC
import os
TABLEAU_SERVER_URL = os.environ.get('TABLEAU_SERVER_URL', 'https://your-tableau-server.com')
TABLEAU_SITE_ID = os.environ.get('TABLEAU_SITE_ID', '') # Use '' for Default site
TABLEAU_PAT_NAME = os.environ.get('TABLEAU_PAT_NAME', 'your_pat_name')
TABLEAU_PAT_SECRET = os.environ.get('TABLEAU_PAT_SECRET', 'your_pat_secret')
# 1. Authenticate using Personal Access Token (PAT)
tableau_auth = TSC.PersonalAccessTokenAuth(
token_name=TABLEAU_PAT_NAME,
personal_access_token=TABLEAU_PAT_SECRET,
site_id=TABLEAU_SITE_ID
)
# 2. Initialize the Server object and set API version handling
# It's recommended to use the server's version for compatibility.
server = TSC.Server(TABLEAU_SERVER_URL, use_server_version=True)
try:
# 3. Sign in to Tableau Server
with server.auth.sign_in(tableau_auth):
print(f"Successfully signed in to Tableau Server: {TABLEAU_SERVER_URL}, Site: {TABLEAU_SITE_ID if TABLEAU_SITE_ID else 'Default'}")
# 4. Example: Query all workbooks on the site
all_workbooks, pagination_item = server.workbooks.get()
print(f"\nFound {pagination_item.total_available} workbooks:")
for workbook in all_workbooks:
print(f" - {workbook.name} (ID: {workbook.id})")
except TSC.ServerError as e:
print(f"Tableau Server Error: {e.code}: {e.message}")
except Exception as e:
print(f"An unexpected error occurred: {e}")
Debug
Known issues
breakingThe TSC library version must be compatible with the Tableau Server REST API version it is connecting to. Incompatible versions can lead to unexpected behavior or `ServerError` exceptions.fixInitialize the `TSC.Server` object with `use_server_version=True` (e.g., `server = TSC.Server(URL, use_server_version=True)`) to automatically use the latest REST API version supported by the server. Alternatively, manually set `server.version = 'X.Y'` to target a specific REST API version.
affects: <=0.40 (continuous concern)
breakingMinor version upgrades of `tableauserverclient` can sometimes introduce subtle breaking changes or stricter validation, particularly around authentication. Users reported `NotSignedInError` issues when upgrading from v0.28 to v0.29.fixAlways review the `tableauserverclient` changelog and release notes before upgrading. If encountering unexpected authentication errors after an upgrade, consider pinning the `tableauserverclient` version in your `requirements.txt` to the last known working version and thoroughly test the new version in a development environment. Review your authentication parameters carefully.
affects: Potentially any minor version upgrade (e.g., 0.28 to 0.29)
gotchaIt is generally not possible to change the authentication *method* (e.g., from username/password to SAML IDP or OAuth) for existing data source connections via `tableauserverclient` or the underlying Tableau REST API.fixIf an authentication method change is required, you may need to download the workbook/data source, modify its XML (e.g., using the Tableau Document API if applicable), and then republish it. Direct in-place updates of authentication methods are not supported.
affects: <=0.40
breakingWhen running `tableauserverclient` on Python versions older than 3.10, a `TypeError: unsupported operand type(s) for |: 'types.GenericAlias' and 'NoneType'` may occur during module import. This is due to the library using the PEP 604 union type syntax (`X | Y`) which was introduced in Python 3.10.fixUpgrade your Python environment to version 3.10 or newer. Alternatively, if you must use an older Python version (e.g., 3.9), downgrade `tableauserverclient` to a version that does not use the `|` union type syntax (e.g., `tableauserverclient < 0.18`).
affects: tableauserverclient >= 0.18 on Python < 3.10
breakingThe script failed to establish a connection to the Tableau Server host due to a name resolution error (`socket.gaierror: [Errno -2] Name does not resolve`), indicating that the provided server hostname could not be translated into an IP address. This typically means the hostname is incorrect, the server is offline, or there's a DNS configuration issue in the execution environment.fixEnsure the `URL` provided to `TSC.Server()` (e.g., `https://your-tableau-server.com`) is the correct and fully qualified domain name (FQDN) or IP address of your Tableau Server. Verify network connectivity from the execution environment to the Tableau Server, check DNS settings, and confirm the server is running and accessible.
affects: N/A (environmental/configuration issue, affects all versions if conditions met)
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'tableauserverclient'
The tableauserverclient library is not installed in the active Python environment.
fixpip install tableauserverclient
tableauserverclient.server.endpoint.exceptions.ServerResponseError: 401001: Unauthorized access.
Authentication failed due to incorrect credentials (username, password, or Personal Access Token), an invalid site name, or attempting an operation before successfully signing in.
fixVerify your TableauAuth credentials and site ID, and ensure that server.auth.sign_in() is called correctly before other operations.
tableau_auth = TSC.TableauAuth('username', 'password_or_pat', site_id='your-site-id')
server = TSC.Server('https://your-tableau-server.com', use_server_version=True)
with server.auth.sign_in(tableau_auth):
# Your operations here tableauserverclient.server.endpoint.exceptions.ServerResponseError: 409003: A resource with the specified name already exists.
Attempting to publish a workbook or data source with a name that already exists on Tableau Server without specifying the overwrite option.
fixSet `mode='Overwrite'` in the `server.workbooks.publish()` or `server.datasources.publish()` method to replace the existing resource.
new_workbook = TSC.WorkbookItem(name='MyWorkbook', project_id='<project-id>')
server.workbooks.publish(new_workbook, r'C:\Path\To\MyWorkbook.twbx', mode='Overwrite')
tableauserverclient.server.endpoint.exceptions.ServerResponseError: 404003: Resource Not Found
The requested resource (e.g., workbook, data source, project, user) could not be found on the Tableau Server, possibly due to an incorrect ID or name.
fixDouble-check the ID or name of the resource you are trying to access or modify to ensure it exists on the server and is spelled correctly.
Upgrade
Version history
0.41latest on PyPI · released Jun 25, 2026
Audit
Dependencies
requestsrequiredAs a REST API client, it implicitly relies on an HTTP client library, and 'requests' is a core dependency for network operations, even for offline installs.