impyla, a PEP 249 client that speaks HiveServer2 to Impala and Hive

A driver for the HiveServer2 Thrift protocol

impyla connects to HiveServer2 implementations, and the README names Impala and Hive as the examples, so the wire protocol is Thrift over a socket rather than HTTP or ODBC. The package metadata confirms the shape of the dependency stack. pyproject.toml lists bitarray, thrift>=0.23.0, thrift_sasl==0.4.3 and pure-sasl>=0.6.2 as required dependencies, and packages the generated Thrift IDL with the client through the package-data setting impala = ["thrift/*.thrift"]. That thrift_sasl pin to exactly 0.4.3 is worth noticing, because it means the install will resolve one specific SASL implementation rather than the newest one. The upstream project the README recommends for anything higher level is Ibis, which it describes as offering a Pandas-like interface over distributed data sets, and it does so twice, once in the introduction and once beside the pandas feature.

Installing impyla with pip, and from the repo

The release install is a single pip command:

pip install impyla

For the development version straight from the repository:

pip install git+https://github.com/cloudera/impyla.git

Or clone it and install from the checkout:

git clone https://github.com/cloudera/impyla.git
cd impyla
python -m pip install .

Python 3.8 is the floor, and pyproject.toml encodes that as requires-python = ">=3.8" with classifiers running from 3.8 through 3.14. The version number is not in the packaging file at all: it is declared dynamic and read from impala.__version__ at build time, so the authoritative version lives in the package source. setup.py still exists but says in a comment that project configuration has migrated to pyproject.toml and that the file is kept for backward compatibility only. The build backend is setuptools with wheel, and the project requires setuptools>=61.0.

The first query looks exactly like any other DB API cursor

Because impyla implements PEP 249, the first query needs no special API. The connect helper takes a host and port, and the cursor behaves like a cursor from sqlite or MySQL:

from impala.dbapi import connect
conn = connect(host='my.host.com', port=21050) # auth_mechanism='PLAIN' for unsecured Hive connection, see function doc
cursor = conn.cursor()
cursor.execute('SELECT * FROM mytable LIMIT 100')
results = cursor.fetchall()

The cursor also exposes the iterator interface, and that iterator is buffered, with the buffer size controlled by cursor.arraysize. The column metadata is available on cursor.description, which is what you use to build a CSV export, and the README shows that export writing a header row from the description and then each row from the iterator. Dropping a result set into the Python data stack is a two-line operation:

from impala.util import as_pandas
df = as_pandas(cur)
# carry df through scikit-learn, for example

The caveat is that this is a conversion, not a distributed dataframe, and the documentation says so by pointing at Ibis for a richer experience.

Authentication choices, and the SSL verification trap

impyla works with Kerberos, LDAP, SSL and JWT, and the security-relevant detail is the warning attached to SSL. Setting use_ssl=True does not verify the server by default. To get verification you have to pass verify_cert=True to use the system CA certificates, or ca_cart with a path to your own certificate:

conn = connect(host='my.host.com', use_ssl=True, verify_cert=True)

The custom CA form uses the ca_cart parameter with a path such as /tmp/my_cert.pem. That is a naming inconsistency worth remembering, since ca_cart does not match either of the other two spellings, and a typo here fails at connection time rather than import time. Kerberos is the option with the heaviest setup cost, because it needs the kerberos package at version 1.3.0 or above plus Kerberos libraries installed on the system, and on Windows the documented substitute is winkerberos installed with pip. The system packages differ by distribution, with libkrb5-dev and krb5-user on Ubuntu and krb5-libs, krb5-devel, krb5-server and krb5-workstation on RHEL and CentOS.

Running the test suite against a real impalad

The tests use the pytest toolchain and need a live server, which the documentation handles with three environment variables:

export IMPYLA_TEST_HOST=your.impalad.com
export IMPYLA_TEST_PORT=21050
export IMPYLA_TEST_AUTH_MECH=NOSASL

With those set, the full run is:

cd path/to/impyla
py.test --connect impala

Leaving out the --connect option skips the DB API compliance tests, which is the practical way to run the suite when no cluster is available. Several Python versions at once can be covered with tox:

cd path/to/impyla
tox

And a single environment with a single test can be selected with tox -e py310 -- -ktest_utf8_strings, where -e picks the environment and the arguments after -- go to pytest. A tox.ini sits at the repository root, alongside a .coveragerc for coverage measurement. The presence of a real-server test mode is a good sign for a driver whose hard problems are protocol edge cases rather than SQL semantics.

Where impyla is the wrong tool

The clearest wrong-tool case is anything that wants lazy evaluation or a query planner that pushes work to the engine. impyla is a driver: it implements the interface and it hands you rows. A pandas-like experience over distributed data is Ibis territory, and the README says so in the introduction and again in the feature list. The second limitation is that a PEP 249 surface is a limited vocabulary for a distributed engine, since it gives you a cursor, a description and a fetch, and nothing in the interface exposes partitioning, the cluster state or query progress. The third is packaging, since thrift_sasl is pinned to an exact version and the client ships its own generated Thrift IDL, so the library's install is more constrained than a plain HTTP client. The SQLAlchemy dialects registered in the entry points are named impala and impala4, and they are dialect shims over the same driver rather than a separate implementation.

Project structure, licensing and the contribution gate

The repository is a normal Python package layout: the impala/ directory holds the client, bin/ and dev/ sit alongside it, and tests/, tools/, docs and a MANIFEST.in are present at the top level. CHANGELOG.md and DEVELOP.md exist for history and contributor guidance. Licensing is the Apache License, Version 2.0, stated in pyproject.toml and covered by LICENSE.txt, so commercial use and modification are allowed under the Apache terms without any separate commercial agreement. Contributing is more constrained than the licence suggests. The documentation says you must first sign and return an ICLA and a CCLA, both linked to Cloudera's native-toolchain repository, and submit them to [email protected] before contributions can be accepted and redistributed. Once submitted you are free to start work, and the expected shape of a patch is narrow, tested, and accompanied by a commit message that explains the problem and the fix.

Maintenance: a dated push and no tagged releases

The last push to the repository was on 2026-06-19, and the project publishes no GitHub releases, so there is no tagged version history to track from the release list and the CHANGELOG.md file is where change history has to be read instead. The package version is derived at build time from impala.__version__, which means every build from a checkout reflects whatever that attribute holds at that commit, and consumers pinning a version from PyPI get a number that was set in the source tree. Python 2.7 support ended at impyla 0.23.0, and the classifier list now runs to Python 3.14, so the supported interpreter range has moved forward even though the transport protocol and the DB API surface have not changed. For an engineer picking a driver, that combination says the project is a maintenance-mode dependency: the interface is settled, the interpreter support is current, and the upgrade path is a version bump rather than a rewrite.

Editorial conclusion

Use impyla when you need a standards-compliant Python connection to Impala or Hive and want it to slot into code already written against sqlite or MySQL clients, and skip it when you want a query abstraction, lazy execution or dataframe operations that read naturally, because the project points at Ibis for that. Verify first that your cluster exposes HiveServer2 on the port you connect to, that your authentication mechanism matches what impyla supports without extra system packages, and that you set verify_cert or ca_cart whenever you use use_ssl=True, since the driver does not verify the server by default.

Frequently asked questions

Official sources

1. cloudera/impyla on GitHub
2. Issues
3. License: Apache-2.0
4. README