Install & Compatibility
Where this runs
tested against v5.3.2 · 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.406s · 26.6MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 2.7s · import 0.374s · 27MB
25MB installed
● package 25MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
InfluxDBClient
✓ from influxdb import InfluxDBClient
✗ from influxdb_client import InfluxDBClient
This library (`influxdb`) is for InfluxDB 1.x. The `influxdb_client` library is for InfluxDB 2.x and has a different API.
DataFrameClient
✓ from influxdb import DataFrameClient
For simplified interaction with Pandas DataFrames in InfluxDB 1.x.
This quickstart demonstrates how to connect to an InfluxDB 1.x instance, create a database if necessary, write data points using line protocol, and query the data back. Ensure your InfluxDB 1.x instance is running and accessible. Connection details can be provided via environment variables (INFLUXDB_HOST, INFLUXDB_PORT, INFLUXDB_USERNAME, INFLUXDB_PASSWORD, INFLUXDB_DATABASE).
import os
from influxdb import InfluxDBClient
# Configuration for InfluxDB 1.x
HOST = os.environ.get('INFLUXDB_HOST', 'localhost')
PORT = int(os.environ.get('INFLUXDB_PORT', 8086))
USER = os.environ.get('INFLUXDB_USERNAME', 'root')
PASSWORD = os.environ.get('INFLUXDB_PASSWORD', 'root')
DATABASE = os.environ.get('INFLUXDB_DATABASE', 'testdb')
client = InfluxDBClient(host=HOST, port=PORT, username=USER, password=PASSWORD)
try:
# Create database if it doesn't exist
databases = client.get_list_database()
if {'name': DATABASE} not in databases:
client.create_database(DATABASE)
print(f"Database '{DATABASE}' created.")
client.switch_database(DATABASE)
# Prepare data points
points = [
{
"measurement": "cpu_load_short",
"tags": {
"host": "server01",
"region": "us-west"
},
"time": "2009-11-10T23:00:00Z",
"fields": {
"value": 0.64
}
},
{
"measurement": "cpu_load_short",
"tags": {
"host": "server02",
"region": "us-east"
},
"time": "2009-11-10T23:00:00Z",
"fields": {
"value": 0.99
}
}
]
# Write data points
client.write_points(points)
print("Data points written successfully.")
# Query data
results = client.query('SELECT value FROM cpu_load_short WHERE region = \'us-west\'')
print("Query Results:")
for item in results.get_points(measurement='cpu_load_short'):
print(item)
except Exception as e:
print(f"An error occurred: {e}")
finally:
client.close()
Debug
Known issues
breakingThis `influxdb` library is *only* for InfluxDB 1.x. It is not compatible with InfluxDB 2.x or 3.x.fixFor InfluxDB 2.x, use `pip install influxdb-client` and import `from influxdb_client import InfluxDBClient`. For InfluxDB 3.x, use `pip install influxdb3-python` and import `from influxdb_client_3 import InfluxDBClient`.
affects: All versions of `influxdb` when used with InfluxDB 2.x/3.x servers.
deprecatedThe `influxdb` library for InfluxDB 1.x is in maintenance mode; new feature development has ceased.fixFor new projects, consider migrating to InfluxDB 2.x or 3.x and using their respective client libraries (`influxdb-client` or `influxdb3-python`) to leverage active development and newer features.
affects: All versions 5.x and newer.
gotchaAuthentication methods differ significantly between InfluxDB 1.x and 2.x/3.x.fixInfluxDB 1.x uses username/password for authentication (as seen in `InfluxDBClient(username, password)`). InfluxDB 2.x/3.x primarily use API tokens. Attempting to use a token with this 1.x client will likely fail authentication.
affects: All versions.
gotchaData organization and query languages are different across InfluxDB versions.fixInfluxDB 1.x uses `databases` and `retention policies` and queries primarily with `InfluxQL`. InfluxDB 2.x uses `buckets` and `organizations` and queries primarily with `Flux`. InfluxDB 3.x uses `databases` and can query with `SQL` or `InfluxQL` via Apache Arrow Flight. Ensure your code aligns with the specific InfluxDB server version and its terminology/query language.
affects: All versions.
gotchaDefault connection parameters might not match your InfluxDB setup, especially if running on Docker or a custom port.fixExplicitly define `host`, `port`, `username`, `password`, and `database` when initializing `InfluxDBClient`. Use environment variables or a configuration file for sensitive credentials.
affects: All versions.
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'influxdb'
This error occurs when the 'influxdb' package is not installed in the Python environment being used, or when attempting to import the `influxdb` client for InfluxDB 1.x while having installed `influxdb-client` for InfluxDB 2.x/3.x, or vice versa.
fixEnsure the correct library is installed for your InfluxDB version. For InfluxDB 1.x, use `pip install influxdb`. If you are using InfluxDB 2.x or 3.x, install `influxdb-client` or `influxdb3-python` respectively, and update your import statements (e.g., `from influxdb_client import InfluxDBClient`).
ConnectionRefusedError: [Errno 111] Connection refused
The Python client failed to establish a connection to the InfluxDB server. This typically means the InfluxDB service is not running, is running on a different host or port than specified, or a firewall is blocking the connection.
fixVerify that the InfluxDB service is running on the specified host and port (default 8086). Check firewall rules and ensure the `host` and `port` parameters in your `InfluxDBClient` initialization match your InfluxDB server configuration. You can also try connecting using `curl` from your terminal to confirm network access.
influxdb.exceptions.InfluxDBClientError: 401: Unauthorized
This error indicates that the InfluxDB server rejected the connection due to invalid authentication credentials (e.g., incorrect username, password, or token) or because authentication is enabled on the server but no credentials were provided by the client.
fixEnsure that the `username` and `password` or `token` provided to the `InfluxDBClient` are correct and have the necessary permissions for the requested operations. If authentication is enabled on your InfluxDB instance, make sure you are passing valid credentials to the client constructor.
AttributeError: 'list' object has no attribute 'get'
This error often occurs when the `write_points` method receives a list of dictionaries as its top-level argument, but an internal function attempts to call `.get()` on this list, expecting a single dictionary or a specific structure that the list does not conform to.
fixWhen using `write_points`, ensure the data structure for a single point is a dictionary, or if writing multiple points, pass a list of dictionaries where each dictionary represents a single point formatted according to the InfluxDB line protocol JSON format. For example, `client.write_points([{'measurement': 'cpu_load', 'fields': {'value': 0.6}}])`. Data not being written, no error reported (InfluxDB 1.x influxdb-python)
Data might not appear in InfluxDB even without explicit errors for several reasons, including incorrect data formatting (e.g., malformed line protocol), issues with timestamps, or the client's internal buffer not being flushed if `write_points` is used in a way that doesn't immediately commit data.
fixDouble-check your data format against InfluxDB's line protocol or JSON format requirements. For small, infrequent writes, consider setting `protocol='json'` explicitly in `write_points`. Ensure timestamps are correctly formatted and within retention policy. If writing in a loop, explicitly call `client.close()` at the end of your script or after a batch of writes to ensure buffered data is flushed.
Upgrade
Version history
5.3.2latest on PyPI · released Apr 18, 2024
Audit
Dependencies
requestsrequiredMain HTTP library for communication with InfluxDB.
pandasoptionalOptional dependency for writing from and reading to DataFrames.