Install & Compatibility
Where this runs
tested against v0.20.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.920 runs
installs and imports cleanly · install 0.0s · import 0.658s · 198.4MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 4.0s · import 0.585s · 175MB
183MB installed
● package 183MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
InfluxDBClient3
✓ from influxdb_client_3 import InfluxDBClient3
✗ from influxdb_client import InfluxDBClient
This client is specifically for InfluxDB 3.0 and uses 'influxdb_client_3' for its package name, distinct from the InfluxDB 2.x client ('influxdb_client').
Point
✓ from influxdb_client_3 import Point
✗ from influxdb_client.domain.write_options import Point
For InfluxDB 3.0, the `Point` class for data construction is directly available from the top-level `influxdb_client_3` package.
Initializes the client, writes a single data point, and then queries data from InfluxDB 3.0. Credentials are sourced from environment variables for secure and flexible deployment. Remember to replace 'YOUR_API_TOKEN' and 'YOUR_DATABASE' or set corresponding environment variables.
import os
from influxdb_client_3 import InfluxDBClient3, Point
# Ensure these environment variables are set or replace with actual values
# Example: export INFLUXDB_V3_HOST="us-east-1-1.aws.cloud2.influxdata.com"
HOST = os.environ.get("INFLUXDB_V3_HOST", "us-east-1-1.aws.cloud2.influxdata.com")
TOKEN = os.environ.get("INFLUXDB_V3_TOKEN", "YOUR_API_TOKEN")
DATABASE = os.environ.get("INFLUXDB_V3_DATABASE", "YOUR_DATABASE")
client = InfluxDBClient3(host=HOST, token=TOKEN, database=DATABASE)
try:
# Write data
point = Point("measurement1").tag("tag1", "value1").field("field1", 1.0)
client.write(point)
print("Data written successfully.")
# Query data
query = f"SELECT * FROM measurement1 WHERE time > now() - interval '1 hour'"
table = client.query(query=query, database=DATABASE)
print("\nQuery results:")
for row in table:
print(row)
except Exception as e:
print(f"An error occurred: {e}")
finally:
client.close()
Debug
Known issues
gotchaThe `org` parameter, which was mandatory in InfluxDB 2.x and earlier `influxdb-client` versions, is no longer required or supported by `influxdb3-python`. Including it can lead to unexpected behavior or errors.fixRemove the `org` parameter from client initialization or write calls.
affects: v0.13.0 and later
gotchaUsing `write_dataframe()` or `query_dataframe()` methods requires either `pandas` or `polars` to be installed as optional dependencies. If these libraries are not installed, attempting to use these methods will raise an `ImportError`.fixInstall the desired DataFrame library: `pip install 'influxdb3-python[pandas]'` or `pip install 'influxdb3-python[polars]'`.
affects: v0.17.0 and later
gotchaThe `query_async()` method (introduced in v0.12.0) is an `awaitable` coroutine. It must be called with `await` within an `async` function. Calling it directly without `await` will not execute the query and might lead to unexpected behavior or a `RuntimeWarning` if not awaited.fixEnsure `query_async()` is called as `await client.query_async(query)` within an `async def` function and an active `asyncio` event loop.
affects: v0.12.0 and later
gotchaThe `WriteOptions.no_sync` flag (introduced in v0.14.0) allows for faster writes by not waiting for Write-Ahead Log (WAL) persistence confirmation. While faster, data is not guaranteed to be durable if the server crashes immediately after the write. Default is `False`.fixOnly set `WriteOptions.no_sync=True` when write performance is critical and some data loss upon server failure is acceptable. Otherwise, rely on the default `False` for durability.
affects: v0.14.0 and later
gotchaPrior to version 0.18.0, `InfluxDBClient3.write_file()` and `InfluxDBClient3.write_dataframe()` could fail when batching mode was enabled due to a bug. This was fixed in v0.18.0.fixUpgrade to `influxdb3-python` v0.18.0 or newer to ensure correct behavior with `write_file()` and `write_dataframe()` in batching mode.
affects: Prior to v0.18.0
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'influxdb_client'
The user is attempting to import modules from older InfluxDB Python client libraries (for InfluxDB 1.x or 2.x) instead of the `influxdb3-python` client library.
fixInstall `influxdb3-python` using `pip install influxdb3-python` and then import `InfluxDBClient3` from `influxdb_client_3` as `from influxdb_client_3 import InfluxDBClient3`.
FlightUnavailableError: Flight returned unavailable error, with message: empty address list:
The Python client cannot establish a connection to the InfluxDB 3.0 instance, often due to the server not running, incorrect host/port in the client configuration, or network issues preventing the Flight client from reaching the server.
fixVerify the InfluxDB 3.0 instance is running and accessible from where the client code is executed. Ensure the `host`, `token`, `org` (if InfluxDB Cloud), and `database` parameters in the `InfluxDBClient3` constructor are correct and match your InfluxDB setup.
AttributeError: 'InfluxDBClient' object has no attribute 'write_api'
The user is attempting to use API methods specific to the InfluxDB 2.x Python client (`influxdb-client`) with the `influxdb3-python` client, which has a different, more direct interface for writing and querying data.
fixUse the `client.write()` and `client.query()` methods directly on the `InfluxDBClient3` object, as the separate `write_api` and `query_api` objects do not exist in the `influxdb3-python` library. For example: `client.write(point)` instead of `client.write_api().write(bucket, point)`.
Error parsing query: missing parameter
The SQL or InfluxQL query string provided to `client.query()` contains syntax errors, such as incorrect quoting, unsupported clauses, or misconfigured parameter binding.
fixDouble-check the query syntax against InfluxDB 3.0's SQL/InfluxQL documentation, ensuring correct use of quotes, keywords, and parameter binding (if applicable). Parameters typically need to be directly embedded or correctly formatted within the query string for InfluxDB 3.0 queries.
Upgrade
Version history
0.20.0latest on PyPI · released Jun 11, 2026
Audit
Dependencies
pandasoptionalFor `write_dataframe` and `query_dataframe` methods when using pandas.
polarsoptionalFor `write_dataframe` and `query_dataframe` methods when using polars.