DataHub Windows Quickstart Feedback & Fix

A tested Windows Quickstart audit and documentation fix that replaces Unix-only commands, aligns Python guidance with the CLI, and adds native PowerShell setup examples.

Comment

Inspiration

DataHub’s Quickstart lists Windows as a supported environment, but several commands assume a Unix-like shell. I wanted to identify the exact points where a Windows user could get blocked before reaching a working DataHub setup.

What I tested

I tested the documented prerequisite and CLI installation path on:

  • Windows 10
  • PowerShell 5.1
  • Python 3.13.3
  • acryl-datahub==1.7.0

I focused on commands that could be validated without a hosted DataHub account or an end-to-end Docker deployment.

What I found

Three onboarding problems were reproducible:

  1. python3 --version failed with exit code 9009, while the Windows Python launcher py worked.
  2. The documentation stated “Python 3.10+”, but the installed DataHub CLI warned that versions above Python 3.11 are not actively tested.
  3. The optional signing-key instructions used export and openssl. export is not a PowerShell command, and OpenSSL was not present in the default Windows environment.

These issues can stop a Windows user before they can evaluate DataHub itself.

What I changed

I prepared a documentation contribution that:

  • separates macOS/Linux and Windows commands;
  • uses version-qualified py -3.11 or py -3.10 commands on Windows;
  • documents a python fallback when the Windows launcher is unavailable;
  • explains how to invoke the DataHub CLI when the Scripts directory is not on PATH;
  • replaces Unix-only environment-variable commands with PowerShell syntax;
  • adds a PowerShell-native cryptographic method for generating the signing key and salt.

Pull request:

https://github.com/datahub-project/datahub/pull/19024

Validation

I verified that:

  • a fresh virtual environment could install acryl-datahub==1.7.0;
  • python -m datahub version executed successfully;
  • the PowerShell helper generated two distinct valid 32-byte Base64 values;
  • git diff --check passed;
  • DataHub’s upstream Markdown and documentation checks passed.

The contribution also received one consolidated automated review. I addressed both review points in a single revision.

Limitations

This is a focused open-source documentation contribution and feedback artifact, not a standalone software application. Docker was not installed on the test machine, so I did not claim an end-to-end DataHub deployment. The findings and validation are limited to prerequisites, Python CLI installation, Windows shell compatibility, and configuration commands.

Why it matters

Quickstart documentation is part of the product experience. Providing executable, operating-system-specific commands reduces onboarding failures and helps Windows users reach DataHub without debugging unrelated shell and Python-version problems first.

Built With

Share this project:

Updates