Registry / database / pytd
library2.4.0pypypi✓ verified 87d ago

pytd is the official Treasure Data Driver for Python, providing a client for interacting with Treasure Data's services. It allows users to query data, load data into tables, and manage databases. The current version is 2.4.0, and it maintains a regular release cadence, typically with several updates per year.

pip install pytd
INSTALL
IMPORT
SIG · PYTD
P
pytd
databasepythonv2.4.0
Install
11.0s avg
Import
1712ms
Disk
320MB
Pass rate
5/ 10
Env Coverage5 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v2.4.0 · 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
musl
py 3.103.920 runs
build_error
glibc
py 3.103.920 runs
installs and imports cleanly · install 11.0s · import 1.712s · 344MB
320MB installed
● package 320MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

Client
from pytd.client import Client
import pytd
Directly importing Client from pytd.client is the standard practice for accessing the main client functionalities.

This quickstart initializes a `pytd` client using environment variables for the API key and server. It then demonstrates how to list available databases. For actual data querying or loading, ensure your Treasure Data API key is valid and you have existing databases/tables that the client can access.

import os from pytd.client import Client # Set your Treasure Data API key and server in environment variables # e.g., export TD_API_KEY="YOUR_API_KEY" # e.g., export TD_API_SERVER="https://api.treasuredata.com" api_key = os.environ.get('TD_API_KEY', '') api_server = os.environ.get('TD_API_SERVER', 'https://api.treasuredata.com') if not api_key: print("Warning: TD_API_KEY environment variable not set. Client may fail to authenticate.") try: # Initialize the client client = Client(apikey=api_key, endpoint=api_server) # List databases databases = client.list_databases() print(f"Databases: {[db.name for db in databases]}") # Example: Execute a simple query (replace 'sample_datasets' and 'www_access' with your actual db/table) # This part requires a valid database and table to exist in your Treasure Data account. if databases and len(databases) > 0: first_db_name = databases[0].name print(f"Using first database found: {first_db_name}") # Example query (uncomment and modify with an actual table in your account): # query_result = client.query(f'SELECT count(*) FROM {first_db_name}.your_table_name_here') # print(f"Query result count: {query_result.fetchall()[0][0]}") else: print("No databases found or API key/server invalid.") except Exception as e: print(f"An error occurred: {e}") print("Please ensure your TD_API_KEY and TD_API_SERVER are correctly set and accessible, and you have network connectivity.")
pytd --version
Debug
Known issues
breakingPython 3.8 support was dropped in `pytd` version 2.0.0. Users on Python 3.8 or older must upgrade their Python environment to 3.9+ (3.10+ recommended) to use `pytd >= 2.0.0`.
fix
Upgrade your Python environment to 3.9 or newer. The current minimum requirement for `pytd 2.4.0` is Python 3.10.
affects: >= 2.0.0
breakingThe underlying SQL client for Trino/Presto queries migrated from `presto-python-client` to `trino-python-client` in `pytd` version 2.0.0. While `pytd` abstracts this, direct interaction with the underlying driver or specific environments with `presto-python-client` dependencies might be affected.
fix
Ensure your environment is compatible with `trino-python-client`. If you have direct dependencies on `presto-python-client`, consider migrating them or pinning `pytd` to `< 2.0.0`.
affects: >= 2.0.0
breakingVersion 2.4.0 introduced increased minimum version requirements for core dependencies: `td-client >= 1.7.0`, `urllib3 >= 2.0.0`, and `pyarrow >= 14.0.1`. Installing `pytd 2.4.0` with older pinned versions of these dependencies will likely cause conflicts.
fix
Update your dependency pins for `td-client`, `urllib3`, and `pyarrow` to meet or exceed the specified minimum versions.
affects: >= 2.4.0
gotcha`pytd` added support for Pandas 2.x in version 1.7.0. If using Pandas DataFrames with `pytd` versions older than 1.7.0, you might encounter compatibility issues with Pandas 2.x. It's recommended to upgrade `pytd` when working with recent Pandas versions.
fix
Upgrade `pytd` to version 1.7.0 or newer to ensure full compatibility with Pandas 2.x. Also ensure your NumPy version is less than 2.0.0.
affects: < 1.7.0 with Pandas >= 2.0
gotchaFor large data imports using `Client.load_table_from_dataframe` or `BulkImportWriter`, `pytd` offers performance features like parallel uploads (`max_workers`, `chunk_record_size`) introduced in 1.7.0/1.9.0. Failing to utilize these parameters can lead to significantly slower uploads.
fix
Consider using `max_workers` and `chunk_record_size` in `load_table_from_dataframe` or `BulkImportWriter` for optimized performance with large datasets. Review `BulkImportWriter` options like `commit_timeout` and `perform_wait_callback` for fine-tuning based on your needs.
affects: All versions
Errors
Common errors & fixes
tdclient.errors.api_error.APIError: 401 Unauthorized
The provided Treasure Data API key is incorrect, expired, or lacks the necessary permissions for the requested operation.
fix
Verify the `apikey` and `endpoint` passed to `pytd.client.Client` are correct, or ensure the `TD_API_KEY` and `TD_API_ENDPOINT` environment variables are properly set. Also, confirm the key has the required privileges.
ModuleNotFoundError: No module named 'pandas'
The `pandas` library, which is an optional dependency for `pytd`'s DataFrame integration methods (e.g., `client.load_table_from_dataframe`), is not installed in the current Python environment.
fix
Install the `pandas` library using `pip install pandas`, or install `pytd` with its pandas extra: `pip install "pytd[pandas]"`.
ValueError: API key or endpoint is missing.
The `pytd.client.Client` could not find the Treasure Data API key or endpoint. These must be provided either as arguments during client initialization or by setting the `TD_API_KEY` and `TD_API_ENDPOINT` environment variables.
fix
Initialize the client with `apikey` and `endpoint` arguments: `client = pytd.client.Client(apikey='YOUR_API_KEY', endpoint='YOUR_ENDPOINT')`. Alternatively, set the environment variables: `export TD_API_KEY='YOUR_API_KEY'` and `export TD_API_ENDPOINT='YOUR_ENDPOINT'`.
tdclient.errors.api_error.APIError: 400 Bad Request: Query failed: [QUERY_ID]: ...
The SQL query executed via `pytd` encountered an error on the Treasure Data service side. This typically indicates a syntax error in the SQL, a non-existent table/database, incorrect permissions, or other logical issues within the query itself.
fix
Examine the full error message returned by Treasure Data (after `[QUERY_ID]:`) to diagnose the problem. Correct the SQL query for syntax, ensure table/database names are accurate, and verify the API key has query permissions.
Upgrade
Version history
2.4.0latest on PyPI · released Feb 3, 2026
Audit
Dependencies
td-clientrequiredCore client for Treasure Data API interaction, required >= 1.7.0.
urllib3requiredHTTP client library, required >= 2.0.0.
pyarrowrequiredUsed for efficient data handling and serialization, required >= 14.0.1.
trino-python-clientrequiredUsed as the underlying SQL client for Trino/Presto queries (replaces presto-python-client since v2.0.0).
pandasoptionalOptional dependency for DataFrame operations, supported up to pandas 2.x.
numpyoptionalOptional dependency, required by pandas, supported < 2.0.0.
Agent activity
11 hits · last 30 days
node
10
Resources