Install & Compatibility
Where this runs
tested against v1.7.0.7 · 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.910 runs
installs and imports cleanly · install 0.0s · import 1.864s · 110.7MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 17.4s · import 1.728s · 112MB
116MB installed
● package 116MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
DatahubRestEmitter
✓ from datahub.emitter.rest_emitter import DatahubRestEmitter
Used for sending metadata changes to DataHub over REST.
MetadataChangeProposalWrapper
✓ from datahub.emitter.mcp import MetadataChangeProposalWrapper
A wrapper for constructing metadata change proposals.
DatasetPropertiesClass
✓ from datahub.metadata.schema_classes import DatasetPropertiesClass
Example of a generated schema class for common metadata aspects.
DatahubClientConfig
✓ from datahub.ingestion.graph.client import DatahubClientConfig, DataHubGraph
Used for configuring and interacting with the DataHub GraphQL API programmatically.
This quickstart first outlines how to set up a local DataHub instance using the CLI's `docker quickstart` command. Following this, it provides a Python snippet demonstrating how to programmatically connect to a DataHub server using the `DatahubRestEmitter` and publish basic dataset properties.
import os
from datahub.emitter.rest_emitter import DatahubRestEmitter
from datahub.emitter.mcp import MetadataChangeProposalWrapper
from datahub.metadata.schema_classes import DatasetPropertiesClass
# --- CLI Quickstart (run in your terminal) ---
# 1. Install Docker and Docker Compose v2.
# 2. Start a local DataHub instance:
# datahub docker quickstart
# (This command might take some time to download and start services)
#
# --- Python SDK Example (after DataHub is running) ---
# For local quickstart, GMS server is typically http://localhost:8080
gms_server = os.environ.get("DATAHUB_GMS_SERVER", "http://localhost:8080")
token = os.environ.get("DATAHUB_GMS_TOKEN", "") # For cloud/secured instances, provide a token
# Initialize the REST emitter
# Note: The 'token' parameter is available for direct use, not just extra_headers.
emitter = DatahubRestEmitter(gms_server=gms_server, token=token)
# Define a sample dataset URN
dataset_urn = "urn:li:dataset:(urn:li:dataPlatform:hive,sample_dataset,PROD)"
# Create a DatasetProperties aspect
dataset_properties = DatasetPropertiesClass(
description="This is a sample dataset emitted via the Python SDK quickstart.",
customProperties={
"owner_team": "data_platform",
"environment": "production_dev"
}
)
# Create a MetadataChangeProposalWrapper
mcp = MetadataChangeProposalWrapper(
entityUrn=dataset_urn,
aspect=dataset_properties,
)
# Emit the metadata change proposal
try:
emitter.emit(mcp)
print(f"Successfully emitted properties for dataset: {dataset_urn}")
except Exception as e:
print(f"Failed to emit metadata: {e}")
print("Ensure your DataHub instance is running and accessible at", gms_server)
datahub --version
Debug
Known issues
breakingPython 3.9 support has been officially dropped. All `acryl-datahub` packages now require Python 3.10 or later.fixUpgrade your Python environment to version 3.10 or newer before upgrading `acryl-datahub`.
affects: v1.4.0 and later
breakingThe V1 UI theme is officially sunset as of v1.5.0. All development targets the V2 UI going forward. If you're self-hosting, ensure your GMS environment variables `THEME_V2_ENABLED` and `THEME_V2_DEFAULT` are set to `true`.fixSet `THEME_V2_ENABLED=true` and `THEME_V2_DEFAULT=true` in your DataHub GMS configuration. The `THEME_V2_TOGGLEABLE` variable should also be set to `false`.
affects: v1.5.0 and later
breakingThe `acryl-datahub` package now requires Pydantic v2. Support for Pydantic v1 has been dropped.fixEnsure `pydantic>=2.0` is installed in your environment. If you have other packages requiring Pydantic v1, consider using separate virtual environments.
affects: v1.4.0.2 and later
breakingSQL view query IDs now use SHA-256 hashes instead of URL-encoding the view URN. This means old query entities for view lineage tracking will become orphaned.fixUse stateful ingestion to clean up and re-ingest view lineage to generate new URNs based on the SHA-256 hash.
affects: v1.5.0 and later
gotchaFor DataHub CLI version 1.5, the handling of the token signing key for Metadata Service Authentication has changed. If not explicitly set via environment variables, new random values are generated and stored locally (`~/.datahub/quickstart/.local-secrets.env`).fixFor production deployments, explicitly set `DATAHUB_TOKEN_SERVICE_SIGNING_KEY` and `DATAHUB_TOKEN_SERVICE_SALT` environment variables to your own secure values.
affects: v1.5.0 and later
gotchaThe `DatahubRestEmitter.emit()` method (and `emit_mcp()`) now returns `Optional[TraceData]` instead of `None` or an `int`. This change exposes trace IDs for SYNC_PRIMARY and ASYNC modes.fixUpdate any code that expects a `None` or `int` return type from `emit()` or `emit_mcp()`. The return value should now be checked for `TraceData` if trace information is needed.
affects: v1.5.0 and later
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'acryl_datahub'
The module name is incorrect; it should be 'acryl-datahub' with a hyphen, not an underscore.
fixInstall the package using the correct name: 'pip install acryl-datahub'.
ImportError: cannot import name 'CustomAssertionInfoClass' from 'datahub.metadata.schema_classes'
The 'CustomAssertionInfoClass' was removed or renamed in a newer version of the 'acryl-datahub' package.
fixUpdate your code to use the correct class name or downgrade to a compatible version of 'acryl-datahub'.
ModuleNotFoundError: No module named 'airflow.providers.common.compat.openlineage.utils'
The 'acryl-datahub-airflow-plugin' is incompatible with Airflow version 2.10.2 due to deprecated dependencies.
fixDowngrade Airflow to a compatible version or update the plugin to a version that supports Airflow 2.10.2.
Client version (1.2.0.1) is newer than server version (0.3.13). Please consider downgrading your CLI version.
The DataHub CLI version is newer than the server version, leading to potential compatibility issues.
fixDowngrade the CLI to match the server version or upgrade the server to match the CLI version.
ERROR ContextFactory: Query execution is null: can't emit event for executionId 13
The 'acryl-spark-lineage' tool is unable to emit events due to a null query execution context.
fixEnsure that the Spark application is correctly configured to generate query execution events.
Upgrade
Version history
1.7.0.7latest on PyPI · released Aug 26, 2026
Audit
Dependencies
PythonrequiredRequired for the acryl-datahub CLI and SDK.
pydanticrequiredRequired by internal components; a breaking change in v1.4.0.2 moved to Pydantic v2.