Install & Compatibility
Where this runs
tested against v0.0.26359 · 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
build_error
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 4.0s · import 0.064s · 306MB
304MB installed
● package 304MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
HyperProcess
✓ from tableauhyperapi import HyperProcess
Connection
✓ from tableauhyperapi import Connection
TableDefinition
✓ from tableauhyperapi import TableDefinition
TableDefinition.Column
✓ from tableauhyperapi import TableDefinition, SqlType; column = TableDefinition.Column("name", SqlType.text())
SqlType
✓ from tableauhyperapi import SqlType
TableName
✓ from tableauhyperapi import TableName
Inserter
✓ from tableauhyperapi import Inserter
This quickstart demonstrates how to initialize a HyperProcess, establish a connection to a .hyper file, define a table schema, create the table, and insert data into it. It emphasizes proper resource management using `with` statements to ensure connections and the Hyper process are correctly closed.
import os
from tableauhyperapi import HyperProcess, Connection, TableDefinition, TableName, SqlType, Inserter
# Define the path for the new Hyper file
hyper_file_path = 'my_first_hyper_file.hyper'
# Remove the file if it already exists to start fresh
if os.path.exists(hyper_file_path):
os.remove(hyper_file_path)
# 1. Start the HyperProcess
with HyperProcess(telemetry_opt_out=True) as hyper:
print(f"The HyperProcess has started on port {hyper.endpoint.port}.")
# 2. Connect to the Hyper file (creates it if it doesn't exist)
with Connection(endpoint=hyper.endpoint, database=hyper_file_path, create_mode=Connection.CreateMode.CREATE_AND_REPLACE) as connection:
print("The connection to the Hyper file is open.")
# 3. Define the table schema
table_name = TableName('public', 'my_data_table')
table_definition = TableDefinition(
table_name,
[
TableDefinition.Column('id', SqlType.int()),
TableDefinition.Column('name', SqlType.text()),
TableDefinition.Column('value', SqlType.double()),
]
)
# 4. Create the table
connection.catalog.create_table(table_definition)
print(f"Table '{table_name}' created.")
# 5. Insert data
with Inserter(connection, table_definition) as inserter:
inserter.add_row([1, 'Alpha', 10.5])
inserter.add_row([2, 'Beta', 20.3])
inserter.add_row([3, 'Gamma', 30.1])
inserter.execute()
print(f"{inserter.number_of_inserted_rows} rows inserted.")
print("The connection to the Hyper file is closed.")
print("The HyperProcess is shut down.")
print(f"Hyper file '{hyper_file_path}' created successfully.")
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'tableauhyperapi'
The `tableauhyperapi` package is not installed in the Python environment where the script is being executed.
fixpip install tableauhyperapi
TableauException: "Cannot open hyper file '<path_to_file>.hyper'"
The Hyper file cannot be accessed, possibly due to an incorrect file path, insufficient file permissions, the file being locked by another process, or corruption.
fixVerify the file path, check file permissions, ensure no other process (like Tableau Desktop) is accessing the file, and confirm the file is not corrupted.
TableauException: "The table with name 'Extract' does not exist."
The specified table name does not exist within the Hyper file, often due to a typo in the table name or forgetting to explicitly create the table before attempting to interact with it.
fixDouble-check the exact table name used and ensure the table schema has been properly defined and created in the Hyper file using `TableDefinition` and `create_table()`.
TableauException: "Column 'ID' does not exist in table 'Extract'."
The specified column name does not match any existing column in the target table's schema within the Hyper file, commonly caused by a typo or a mismatch with the table definition.
fixReview the table's schema definition (e.g., `table_definition.add_column(...)`) and ensure the column name in your code exactly matches an existing column in the table.
Upgrade
Version history
0.0.26359latest on PyPI · released Aug 24, 2026
Audit
Dependencies
No dependency data recorded yet.