Install & Compatibility
Where this runs
tested against v? · 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.920 runs
build_error
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 3.3s · import 0.683s · 184MB
184MB installed
● package 184MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
connect
✓ from trino.dbapi import connect
✗ from presto.dbapi import connect
The original 'presto-client' package imported under 'presto'. The current, actively maintained package is 'trino'.
TrinoQueryError
✓ from trino.exceptions import TrinoQueryError
✗ from presto.exceptions import PrestoQueryError
Exception class names have also changed from 'Presto...' to 'Trino...'.
This quickstart demonstrates how to connect to a Trino cluster, execute a simple query, and fetch results using the DBAPI 2.0 interface. It uses environment variables for configuration to avoid hardcoding sensitive information. The `with conn.cursor()` syntax is supported from version 0.334.0 onwards.
import trino
import os
# Connect to Trino using environment variables for host, port, etc.
# Default to common local settings if env vars are not set.
conn = trino.dbapi.connect(
host=os.environ.get('TRINO_HOST', 'localhost'),
port=int(os.environ.get('TRINO_PORT', '8080')),
user=os.environ.get('TRINO_USER', 'python_client'),
catalog=os.environ.get('TRINO_CATALOG', 'system'),
schema=os.environ.get('TRINO_SCHEMA', 'runtime'),
http_scheme=os.environ.get('TRINO_HTTP_SCHEME', 'http'),
auth=trino.auth.BasicAuthentication(
username=os.environ.get('TRINO_USERNAME', ''),
password=os.environ.get('TRINO_PASSWORD', '')
) if os.environ.get('TRINO_USERNAME') else None,
)
with conn.cursor() as cur:
cur.execute("SELECT node_id, uri FROM nodes LIMIT 5")
for row in cur.fetchall():
print(row)
Debug
Known issues
breakingThe `presto-client` library has been officially renamed and superseded by the `trino` package. Continuing to use `presto-client` is not recommended due to lack of updates and potential incompatibilities with newer Trino servers.fixUninstall `presto-client` (`pip uninstall presto-client`), then install the new client (`pip install trino`). Update all import statements from `import presto` to `import trino`.
affects: All versions of `presto-client`.
gotchaThe PyPI project `trino-python-client` (which is the successor to `presto-client`) is installed using the package name `trino` (`pip install trino`), and imported as `import trino`. Attempting to install or import using `trino-python-client` directly will fail.fixAlways use `pip install trino` for installation and `import trino` in your Python code.
affects: All versions of the `trino` package.
gotchaConnecting to a Trino server over HTTPS (SSL/TLS) requires explicit configuration for `http_scheme` and potentially certificate verification.fixSet `http_scheme='https'` in your `trino.dbapi.connect` call. If using self-signed certificates, you may need to pass `verify=False` (use with extreme caution in production) or provide a `cert` path, e.g., `cert='/path/to/my_ca.pem'`.
affects: All versions of `trino`.
gotchaPerformance for fetching large query results can be significantly improved by installing optional compression libraries, `lz4` or `zstd`.fixInstall optional dependencies using `pip install "trino[lz4]"` or `pip install "trino[zstd]"` (or both with `"trino[lz4,zstd]"`). The client will automatically use them if available.
affects: All versions of `trino`.
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'presto'
You have installed the new `trino` package but your code is still trying to import from the old `presto` package name.
fixChange all import statements in your code from `import presto` or `from presto...` to `import trino` or `from trino...`.
ModuleNotFoundError: No module named 'trino-python-client'
You are trying to import the Python package using its PyPI project name (`trino-python-client`), which contains a hyphen and is not the correct importable package name.
fixThe correct package to import is `trino`. Change your import statement to `import trino` (after ensuring you've installed it with `pip install trino`).
trino.exceptions.TrinoQueryError: Server error: io.trino.spi.security.AccessDeniedException: Cannot select from table system.runtime.nodes
The Trino server denied the query, usually because the connected user lacks necessary permissions or the specified catalog/schema is incorrect or inaccessible.
fixVerify the `user`, `catalog`, and `schema` parameters in your `trino.dbapi.connect` call. Ensure the user specified has the required privileges to access the queried table/schema on the Trino cluster.
requests.exceptions.SSLError: HTTPSConnectionPool(...) Max retries exceeded with url: /v1/statement
The client failed to establish a secure (HTTPS) connection to the Trino server. This can be due to `http_scheme` not being set to `'https'`, an untrusted server certificate, or an incorrect certificate path.
fixIf your Trino server uses HTTPS, ensure `http_scheme='https'` in your connection parameters. If you are using self-signed certificates, you may need to provide the certificate path via the `cert` parameter or (less securely) set `verify=False`.
Upgrade
Version history
0.303.0latest on PyPI · released Jan 13, 2021
Audit
Dependencies
requestsrequiredRequired for HTTP communication with the Trino server.
lz4optionalOptional: Provides faster decompression for query results.
zstdoptionalOptional: Provides faster decompression for query results.