Install & Compatibility
Where this runs
tested against v0.58.1 · 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
py 3.10
✕ build_error
✓ 53.5s
py 3.11
✕ build_error
✓ 50.8s
py 3.12
✕ build_error
✓ 39.2s
py 3.13
✕ build_error
✕ build_error
py 3.9
✕ build_error
✓ 43.9s
662MB installed
● package 662MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
airbyte
✓ import airbyte as ab
The 'ab' alias is the recommended and most common convention in PyAirbyte documentation and examples for concise and readable code.
This quickstart demonstrates how to connect to a data source (using `source-faker` for demonstration), verify its configuration, extract data, and load it into a Pandas DataFrame. It uses the recommended `import airbyte as ab` convention and shows basic steps for data ingestion.
import airbyte as ab
import os
# Configure a source (e.g., source-faker for demo purposes)
# For real connectors, replace 'source-faker' with the actual connector name
# and 'config' with your credentials/connection details.
# Use os.environ.get for sensitive information.
source = ab.get_source(
"source-faker",
config={
"count": 1000, # Number of records to generate
"seed": 42 # Seed for reproducible data generation
},
install_if_missing=True # Automatically install the connector if not found
)
# Verify configuration and connection
check_result = source.check()
if check_result.status == "succeeded":
print("Source connection successful!\n")
else:
print(f"Source connection failed: {check_result.message}\n")
exit()
# Select all available streams from the source
source.select_all_streams()
# Read data from the source into PyAirbyte's internal cache (DuckDB by default)
read_result = source.read()
# Access a specific stream and convert it to a Pandas DataFrame
# Replace 'users' with the actual stream name from your source
users_df = read_result["users"].to_pandas()
print("First 5 records from 'users' stream:")
print(users_df.head())
Debug
Known issues
breakingThe PyAirbyte MCP (Model Context Protocol) Server is currently experimental. Its API and features may change significantly or be entirely refactored without notice between minor versions of PyAirbyte. Avoid using it in production environments where stability is critical.fixMonitor official PyAirbyte documentation and GitHub releases for updates on the MCP Server's stability. For production, rely on stable APIs.
affects: 0.44.1 (and potentially future minor versions)
gotchaWhile PyAirbyte itself supports Python 3.10+, specific Airbyte connectors might have stricter Python version requirements or dependencies. If you encounter issues, consider explicitly setting the Python version for the connector via the `use_python` argument in `ab.get_source()` or `ab.get_destination()`. Alternatively, using `docker_image=True` can provide greater stability by leveraging Docker.fixWhen initializing a source or destination, use `ab.get_source(..., use_python="3.11")` or `ab.get_source(..., docker_image=True)` to control the connector's execution environment.
affects: All versions
gotchaJava-based Airbyte destination connectors (which typically run as Docker containers) require Docker to be installed and running on your system. For greater portability and Python-native execution, consider utilizing SQL-based caches (e.g., DuckDB, Postgres, Snowflake) directly within PyAirbyte, if your destination is a SQL database.fixInstall Docker for Java-based destinations. For SQL databases, use PyAirbyte's built-in SQL caching mechanisms instead of destination connectors for a more Python-native experience: `cache = ab.get_destination_cache('postgres', config=...)`. affects: All versions
gotchaStarting with PyAirbyte version 0.29.0, the library defaults to using `uv` instead of `pip` for installing Python-based connectors, offering significant speed improvements. If `uv` causes unexpected issues or conflicts in your environment, you can force PyAirbyte to fall back to `pip` for connector installations.fixSet the environment variable `AIRBYTE_NO_UV=true` before running your PyAirbyte code to revert to `pip`-based connector installation: `os.environ['AIRBYTE_NO_UV'] = 'true'`.
affects: >=0.29.0
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'airbyte'
The 'airbyte' module is not installed in the Python environment.
fixInstall the module using 'pip install airbyte'.
ModuleNotFoundError: No module named 'airbyte_cdk.sources.declarative.manifest_declarative_source'
The 'airbyte_cdk' module is either not installed or is an incompatible version.
fixEnsure 'airbyte-cdk' is installed and up-to-date by running 'pip install --upgrade airbyte-cdk'.
RuntimeError: Unknown type encountered
An unknown type error occurs when running PyAirbyte with Python 3.10.
fixDowngrade to Python 3.9 or upgrade PyAirbyte to a version compatible with Python 3.10.
Internal Server Error: Get Spec job failed
Uploading a custom Python connector Docker image to the Airbyte UI fails.
fixVerify the Docker image is correctly built and accessible, and check Airbyte logs for more details.
Client error: 403
Connector creation, updates, and checks fail with a 403 error.
fixEnsure proper authentication and permissions are set, and check Airbyte's status page for any ongoing incidents.
Upgrade
Version history
0.58.1latest on PyPI · released Aug 28, 2026
Audit
Dependencies
uvoptionalUsed by default for faster Python connector installation since v0.29.0; a fallback to pip is available via environment variable.
dockeroptionalRequired for running Java-based destination connectors. Python-native SQL caches are often recommended as an alternative.
pandasoptionalCommonly used for data manipulation after extracting data into DataFrames.