Installation

Supported Python versions

dltHub currently supports Python versions 3.10-3.13.

Quickstart

To install the dlt[hub] package, create a new Python virtual environment and run:

uv pip install "dlt[hub]"

This will install dlt with two additional extras:

• dlthub which enables features that require a license
• dlt-runtime which enables access to dltHub Runtime

When working with locally you'll need several dependencies like duckdb, marimo, pyarrow or fastmcp. You can install them all with:

uv pip install "dlt[workspace]"

If you need to install uv (a modern package manager), please refer to the next section.

Upgrade existing installation

To upgrade just the hub extra without upgrading dlt itself run:

uv pip install -U "dlt[hub]==1.20.0"

This will keep current 1.20.0 dlt and upgrade dlthub and dlt-runtime to their newest matching versions.

tip

Note that particular dlt version expects dlthub and dlt-runtime versions in a matching range. For example: 1.20.x versions expects 0.20.x version of a plugin. This is enforced via dependencies in hub extra and at import time. Installing plugin directly will not affect installed dlt version to prevent unwanted upgrades. For example if you run:

uv pip install dlthub

and it downloads 0.21.0 version of a plugin, dlt 1.20.0 will still be there but it will report a wrong plugin version on import (with instructions how to install valid plugin version).

Enable dltHub Free and Paid features

info

The most recent dltHub features like profiles and runtime access are hidden behind a feature flag, which means you need to manually enable them before use.

To activate these features, create an empty .dlt/.workspace file in your project directory; this tells dlt to switch from the classic project mode to the Workspace mode.

Ubuntu

mkdir -p .dlt && touch .dlt/.workspace

macOS

mkdir -p .dlt && touch .dlt/.workspace

Windows

mkdir .dlt
type nul > .dlt\.workspace

Setting up your environment

Configuration of the Python environment

In this documentation, we use uv (a modern package manager) to install Python versions, manage virtual environments, and manage project dependencies. To install uv, you can use pip or follow the OS-specific installation instructions.

Once you have uv installed you can pick any Python version supported by it:

uv python install 3.13

or use any Python version you have installed on your system.

Virtual environment

We recommend working within a virtual environment when creating Python projects. This way, all the dependencies for your current project will be isolated from packages in other projects. With uv, run:

uv venv

This will create a virtual environment in the .venv folder using the default system Python version.

uv venv --python 3.13

This will use Python 3.13 for your virtual environment.

Activate the virtual environment using the instructions displayed by uv, i.e.:

source .venv/bin/activate

Licensing

To access dltHub’s paid features, such as Iceberg support or Python-based transformations, you need a dltHub Software License.

1. Contact us if you want to purchase a license or get a trial license with unlimited use.
2. Issue a limited trial license yourself.

Install your license

If you've received your license from us, you can install it in one of two ways:

In the secrets.toml file:

license = "your-dlthub-license-key"

As an environment variable:

export DLT_LICENSE_KEY="your-dlthub-license-key"

Features requiring a license:

• @dlt.hub.transformation - a powerful Python decorator to build transformation pipelines and notebooks
• dbt transformations - a staging layer for data transformations, combining a local cache with schema enforcement, debugging tools, and integration with existing data workflows.
• Iceberg support.
• Data Checks.
• MSSQL Change Tracking source.

For more information about the feature scopes, see Scopes. Please, also review our End User License Agreement

Self-licensing

You can self-issue an anonymous 30-day trial license to explore dltHub’s paid features. This trial license is intended for development, education, and CI operations only. Self-issued licenses are bound to the specific machine on which they were created. They cannot be transferred or reused on other machines, workspaces, or environments.

See the Special Terms in our EULA for more details.

Issue a Trial License

Choose a scope for the feature you want to test, then issue a license with:

dlt license issue <scope>

for example:

dlt license issue dlthub.transformation

This will do the following:

• Issue a new license (or merge with existing scopes) for the transformations feature.
• Print your license key in the CLI output.
• Put the license key into your toml file.

Scopes

Display available scopes by running the following command:

dlt license scopes

You can self-issue multiple licenses; newly issued licenses will automatically include previously granted features.

To view your installed licenses:

dlt license info