Install & Compatibility
Where this runs
tested against v3.3.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
build_error
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 3.2s · import 0.010s · 154MB
152MB installed
● package 152MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Connects to an IBM DB2 database using environment variables for credentials and executes a simple query to fetch table information.
import ibm_db
import os
# Connection details (replace with your actual DB2/Informix details)
# For security, use environment variables in production.
database = os.environ.get('IBM_DB_DATABASE', 'SAMPLE')
hostname = os.environ.get('IBM_DB_HOSTNAME', 'localhost')
port = os.environ.get('IBM_DB_PORT', '50000')
protocol = os.environ.get('IBM_DB_PROTOCOL', 'TCPIP')
uid = os.environ.get('IBM_DB_UID', 'db2inst1')
pwd = os.environ.get('IBM_DB_PWD', 'password')
conn_string = f"DATABASE={database};HOSTNAME={hostname};PORT={port};PROTOCOL={protocol};UID={uid};PWD={pwd};"
try:
# Connect to the database
# Note: User/password can be passed separately or embedded in conn_string.
# Empty strings for user/pwd are allowed if already in conn_string.
conn = ibm_db.connect(conn_string, "", "")
print("Connection to DB2 successful!")
# Execute a query
stmt = ibm_db.exec_immediate(conn, "SELECT * FROM SYSCAT.TABLES FETCH FIRST 5 ROWS ONLY")
# Fetch results
result = ibm_db.fetch_both(stmt)
while result:
print(result)
result = ibm_db.fetch_both(stmt)
# Close the connection
ibm_db.close(conn)
print("Connection closed.")
except Exception as e:
print(f"Connection or query failed: {e}")
Debug
Known issues
breakingOn Windows and Linux, `ibm-db` requires the IBM Data Server Driver for ODBC and CLI to be pre-installed on the system. The `pip install` command only installs the Python bindings. This external driver is typically downloaded from IBM's support portal.fixDownload and install the IBM Data Server Driver for ODBC and CLI appropriate for your operating system before running `pip install ibm-db`.
affects: All versions on Windows/Linux
gotchaAfter installing the IBM Data Server Driver for ODBC and CLI, you may need to set environment variables such as `IBM_DB_HOME` (pointing to the driver's installation directory) or update `LD_LIBRARY_PATH` (Linux) / `DYLD_LIBRARY_PATH` (macOS) to ensure the Python driver can locate the native libraries.fixRefer to the `ibm-db` documentation for platform-specific environment variable configurations. Restart your terminal/IDE after setting them.
affects: All versions
gotchaConnection strings for DB2/Informix databases can be complex. Ensure all parameters (DATABASE, HOSTNAME, PORT, PROTOCOL, UID, PWD) are correctly specified. Common issues include incorrect port numbers or hostname resolutions.fixCarefully review the database connection details provided by your DBA or cloud provider. Test connectivity with a native CLI tool if available.
affects: All versions
gotchaFor ORM integration (e.g., SQLAlchemy), `ibm-db` alone is often not enough. You typically need the `ibm-db-sa` package (SQLAlchemy adapter for ibm-db) in addition to `ibm-db`.fixInstall `pip install ibm-db-sa` if you plan to use `ibm-db` with SQLAlchemy or other ORMs.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'ibm_db'
The `ibm_db` Python package is not installed or not accessible in the current Python environment.
fixRun `pip install ibm-db` to install the package. If using a specific Python version, use `pip3 install ibm-db`.
ImportError: DLL load failed: The specified module could not be found.
On Windows, this error occurs when the underlying IBM Data Server Driver for ODBC and CLI (clidriver) DLLs (like `db2cli.dll`) are not found in the system's PATH or a location discoverable by Python.
fixEnsure the `IBM_DB_HOME` environment variable is set to the `clidriver` directory (e.g., `C:\IBM\clidriver`), and its `bin` subdirectory is included in the system's PATH. Alternatively, in Python code, add `os.add_dll_directory(os.getenv('IBM_DB_HOME') + '/bin')` before importing `ibm_db`. ERROR: Command errored out with exit status 1: ... during pip install ibm-db
This installation error often indicates missing build tools (like GCC, `python-devel` on Linux/macOS, or Visual C++ build tools on Windows) required to compile the native components of `ibm_db`, or issues with the automatic download of the `clidriver`.
fixInstall necessary development packages specific to your OS (e.g., `sudo apt-get install build-essential python3-dev` on Debian/Ubuntu, `sudo yum install gcc python3-devel` on RedHat, or Visual C++ build tools on Windows). If you have an existing Db2 CLI driver, set the `IBM_DB_HOME` environment variable to its installation path before running `pip install ibm-db --no-binary :all: --no-cache-dir`.
SQL30081N A communication error has been detected.
This Db2 SQL error indicates a failure to establish a connection to the database server, commonly due to incorrect connection parameters in the connection string, network issues (firewall, VPN), or the database server not running or being inaccessible.
fixCarefully verify all connection string parameters (hostname, port, database name, username, password). Check network connectivity between the client and the database server, including firewall rules and VPN configurations. Ensure the Db2 or Informix server is running and configured to accept remote connections on the specified port.
DB2 SQL Error: SQLCODE=-204, SQLSTATE=42704, SQLERRMC=<object-name> not found
This SQL error signifies that an SQL statement attempted to access a database object (e.g., table, view, or function) that either does not exist, is misspelled, or the connecting user lacks the necessary privileges to access it within the current schema.
fixReview and correct the object name in your SQL query. Confirm that the object exists in the specified schema on the database server. Verify that the user credentials used for the database connection have sufficient permissions to access the object.
Upgrade
Version history
3.3.0latest on PyPI · released Aug 11, 2026
Audit
Dependencies
No dependency data recorded yet.