DataHub SDK and CLI Version Compatibility with DataHub Cloud – DataHub Customer Support Portal

Area: Deployment Issues

Sub-Area: Version Compatibility and Package Management

Issue

After upgrading to a new version of DataHub Cloud, users are uncertain which versions of the DataHub CLI (acryl-datahub) and Python SDK (acryl-datahub-cloud) are compatible with their server version. Additionally, users running the DataHub executor image may observe that the bundled CLI version inside the image does not match the latest recommended CLI version, causing confusion about whether their environment is correctly configured.

You Might Be Asking

Which CLI or SDK version should I use after upgrading DataHub Cloud?
Where can I find the recommended CLI version for my DataHub Cloud release?
The executor image I'm running reports a different bundled CLI version than what the release notes recommend — is something wrong?
Does upgrading the executor image automatically update the bundled CLI to the latest version?
Should the acryl-datahub-cloud package version match the server version?

Solution

Determine the recommended CLI version from the DataHub Cloud release notes.
Each DataHub Cloud release specifies a recommended CLI version in its release notes. Always consult the release notes for your specific server version to identify the correct acryl-datahub CLI version to use. For example, DataHub Cloud 2.0.0 recommends CLI version 1.6.0.4.

Release notes are available at:
```
https://docs.datahub.com/docs/managed-datahub/managed-datahub-overview
```
Match the acryl-datahub-cloud Python package version to the server version.
The acryl-datahub-cloud package version should match your DataHub Cloud server version exactly. For example, if your server is on version 2.0.0, install:
```
pip install acryl-datahub-cloud==2.0.0
```
Install the recommended CLI version.
After confirming the correct version from the release notes, install or upgrade the CLI accordingly:
```
pip install acryl-datahub==<recommended-version>
```
To verify the installed version:
```
datahub version
```
Understand bundled CLI versions in executor images.
If you are using the DataHub executor image, be aware that the CLI version bundled inside the image is pinned at the time the image is built and published. Pulling a newer executor image does not automatically update the bundled CLI to the latest recommended version. The bundled CLI version may therefore lag slightly behind the most recently recommended CLI version.

You can inspect the CLI version bundled in a specific executor image by running:
```
docker run -i --rm <your-executor-image> pip3 freeze | grep acryl
```
If the bundled CLI version is slightly behind the latest recommendation (for example, the image ships with CLI 1.5.0.19 while the recommendation has moved to 1.6.0), this is expected behavior. The image was built before the newer CLI version was released. The bundled version in the image is fully supported and will function correctly with the corresponding server version.
When using unbundled executor images with custom virtual environments.
If you are using an unbundled executor image with a custom set of virtual environments, you have full control over the CLI version installed in those environments. In this case, install the CLI version recommended in the release notes directly into your custom virtual environment:
```
pip install acryl-datahub==<recommended-version>
```
If you are unsure of the correct version for your instance, check the UI footer.
The DataHub Cloud UI footer displays the current server version. Use this version to look up the corresponding recommended CLI version in the release notes. If you still cannot determine the correct version, contact DataHub Support for confirmation.

Additional Notes

The CLI version bundled inside executor images is determined at image build time and is intentionally pinned for stability and compatibility. A minor version gap between the bundled CLI and the latest recommended CLI (e.g., one patch release behind) is expected and does not indicate a misconfiguration or defect. If a specific CLI version is required for a feature or fix not available in the bundled version, contact DataHub Support to request an updated executor image. Always upgrade both the CLI and the acryl-datahub-cloud package after a DataHub Cloud server upgrade to ensure full compatibility, access to new features, and continued support eligibility. Version mismatches between the CLI/SDK and the server can result in unexpected behavior or unsupported configurations.

Issue

You Might Be Asking

Solution

Additional Notes

Related Documentation