Install & Compatibility
Where this runs
tested against v0.24.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
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.194s · 32.7MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 4.3s · import 0.184s · 30MB
30MB installed
● package 30MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
connect
✓ from impala.dbapi import connect
This quickstart demonstrates how to establish a connection to an Impala server, execute a simple SQL query, and fetch the results using the DB API 2.0 interface. It uses environment variables for host and port for flexibility.
import os
from impala.dbapi import connect
IMPALA_HOST = os.environ.get('IMPYLA_TEST_HOST', 'localhost')
IMPALA_PORT = int(os.environ.get('IMPYLA_TEST_PORT', 21050))
try:
conn = connect(host=IMPALA_HOST, port=IMPALA_PORT)
cursor = conn.cursor()
cursor.execute('SHOW TABLES')
tables = cursor.fetchall()
print('Tables in Impala:')
for table in tables:
print(table[0])
cursor.close()
conn.close()
except Exception as e:
print(f"Could not connect or query Impala: {e}")
print("Please ensure an Impala daemon is running at the specified host and port.")
Debug
Known issues
breakingIn version 0.20.0, the behavior of `Cursor.rowcount` and the automatic closing of finished queries (`close_finished_queries`) changed. This might be a breaking change for existing applications.fixTo restore the old behavior for `close_finished_queries`, set `close_finished_queries=False` when creating a Cursor object. Note that `Cursor.rowcount` only works with Impala server; it will return -1 for Hive.
affects: 0.20.0 and later
gotchaWhen connecting to Impala via Impyla, ensure you use the HiveServer2 port (default 21050). Using the Beeswax port (default 21000), which the Impala shell typically uses, will result in connection errors.fixAlways specify `port=21050` (or your configured HiveServer2 port) in the `connect()` function.
affects: All versions
gotchaImpyla has been reported to break with newer versions of the `bitarray` library (e.g., version 2.1.0). Compatibility issues may arise if `bitarray` is updated beyond tested versions.fixPin the `bitarray` dependency to a known compatible version if you encounter `bitarray`-related errors, for example, `bitarray<2.1.0`.
affects: Potentially 0.19.0 and later (unconfirmed exact range, report seen for 'newer version')
gotchaPython 3.12 support is incomplete in Impyla versions up to 0.22.0. A known issue is that installation using `setuptools` may fail with Python 3.12.fixConsider using Python versions prior to 3.12, or monitor GitHub for updated compatibility with Python 3.12 and later.
affects: Up to 0.22.0
deprecatedThe `auth_cookie_names` parameter in the `connect()` API was deprecated in version 0.18.0. Authentication cookie functionality is now enabled by default.fixRemove the `auth_cookie_names` parameter from your `connect()` calls. If you explicitly set it to `None` for GSSAPI authentication in older versions, note that the auth cookie will be enabled after upgrading to 0.18.0 or newer.
affects: 0.18.0 and later
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'impala.dbapi'
This error often occurs because developers mistakenly install a package named `impala` instead of `impyla`, or because `impyla` is not installed in the active Python environment. The correct library is `impyla`, and its main entry point for DB API is `impala.dbapi`.
fixEnsure you have installed the `impyla` library: `pip install impyla`. If you have a package named `impala` installed, uninstall it first: `pip uninstall impala`.
TTransportException: Could not connect to <host>:<port>
This error indicates that the Python client cannot establish a network connection to the Impala daemon or HiveServer2 at the specified host and port. This can be due to incorrect host/port, the Impala/HiveServer2 service not running, firewall issues, or network connectivity problems.
fixVerify that the Impala daemon or HiveServer2 is running and accessible from your client machine on the specified host and port. Check firewall rules, network connectivity, and ensure the host and port in your `impyla.dbapi.connect()` call are correct.
javax.security.sasl.SaslException: GSS initiate failed [Caused by GSSException: No valid credentials provided (Mechanism level: Failed to find any Kerberos tgt)]
This error occurs when attempting to connect to a Kerberos-secured Impala or HiveServer2 instance without valid Kerberos credentials (Ticket Granting Ticket - TGT) or with an incorrect Kerberos configuration.
fixBefore running your Python script, ensure you have obtained a valid Kerberos TGT using `kinit` for the appropriate user. Also, verify that `kerberos_service_name` and `auth_mechanism='GSSAPI'` are correctly configured in your `impyla.dbapi.connect()` call, and that necessary Kerberos client libraries are installed on your system.
impala.error.HiveServer2Error: Invalid OperationHandle: OperationHandle
This error often indicates that an operation handle (representing an active query or session on the server) has become invalid or expired on the HiveServer2/Impala server side. This can be due to query timeouts, the server canceling the operation, or issues with concurrent operations.
fixThis can sometimes be transient. Retry the query. If persistent, investigate server-side Impala/HiveServer2 logs for issues related to query execution or session management. For long-running queries, consider increasing client-side or server-side timeouts if appropriate. Ensure that the Impala/HiveServer2 instance is stable and not overloaded.
Upgrade
Version history
0.24.0latest on PyPI · released Jun 19, 2026
Audit
Dependencies
pythonrequiredRequires Python 2.7+ or 3.5+
sixrequiredRequired for core functionality
bitarrayrequiredRequired for core functionality
thrift==0.16.0requiredRequired for Thrift protocol communication
thrift_sasl==0.4.3requiredRequired for SASL authentication
kerberosoptionalOptional, for Kerberos over HTTP support (requires system Kerberos libraries)
winkerberosoptionalOptional, alternative for Kerberos on Windows
pandasoptionalOptional, for converting query results to DataFrames
sqlalchemyoptionalOptional, for SQLAlchemy engine integration