:::info Supported Python versions

dltHub currently supports Python versions 3.10-3.13.

:::

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

Quickstart#

Start a new workspace (recommended)#

If you already have uv installed:

uvx dlthub-start@latest

If you don't have uv yet, either install it first or run via pipx — the CLI will offer to install uv for you before syncing dependencies:

pipx run dlthub-start

Either way, it prompts for a workspace name, scaffold, and which AI agents to wire up (Claude / Cursor / Codex), scaffolds a workspace with .dlt/.workspace already set, vendors the AI toolkits (rest-api-pipeline, transformations, dlthub-runtime, data-exploration), and runs uv sync so dlt[hub] and all workspace dependencies are installed.

For the recommended defaults non-interactively, pass a name explicitly:

uvx dlthub-start@latest my-workspace --yes

Add dltHub to an existing project#

To install dlt[hub] into an existing project, activate its virtual environment and run:

uv pip install "dlt[hub]"

This installs dlt plus two plugin packages pulled in by the hub extra:

• dlthub—enables the dlthub command and features like AI toolkits and transformations
• dlthub-client—enables access to the managed dltHub Platform (login, deploy, run, serve, ...)

Workspace-level dependencies (destinations like duckdb, plus tools like marimo or fastmcp used by notebooks and MCP jobs) are managed in your workspace's pyproject.toml, not via dlt extras. Run dlthub init (see below)—it scaffolds a pyproject.toml you can extend with uv add <package>.

Upgrade existing installation#

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

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

This keeps the current 1.27.0 dlt and upgrades dlthub and dlthub-client to their newest matching versions.

Enable workspace mode#

The full dltHub feature surface—profiles, the dlthub CLI host, and managed-platform commands—is gated behind Workspace mode, signaled by a .dlt/.workspace marker file. The simplest way to turn it on is:

dlthub init

This scaffolds a fresh dltHub workspace—it creates the .dlt/.workspace marker plus config.toml, secrets.toml, .gitignore, and a pyproject.toml (or requirements.txt if uv isn't on PATH). See Initialize a pipeline for the next steps.

If you'd rather flip the toggle by hand in an existing project, create the empty marker file yourself:

<Tabs values={[{"label": "Ubuntu", "value": "ubuntu"}, {"label": "macOS", "value": "macos"}, {"label": "Windows", "value": "windows"}]} groupId="operating-systems" defaultValue="ubuntu">

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

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

mkdir .dlt
type nul > .dlt\.workspace