Installation

Supported Python versions

dltHub currently supports Python versions 3.10-3.14.

What is a dltHub workspace?

A workspace is a Python project layout that bundles your dlt pipelines, transformations, configuration, and AI toolkit setup into a single deployable unit. The same folder runs on your local machine, in CI, and — when you deploy — on the managed dltHub platform, so what you build locally is what runs in production.

Every workspace contains:

• .dlt/.workspace — a marker file that activates the dlthub CLI, profile support, and the managed-platform commands. Without this file you're using plain OSS dlt.
• .dlt/config.toml and .dlt/secrets.toml — settings and credentials, with optional per-profile overrides (dev, prod, tests, access).
• pyproject.toml (or requirements.txt) — workspace-level dependencies like dlt[hub], duckdb, marimo.
• Pipeline files and an optional __deployment__.py manifest — the code you run, and the description of how it's deployed.
• AI toolkit configuration — skills, rules, and MCP wiring for Claude Code, Cursor, or Codex (added when you opt in during scaffolding).

For the wider feature surface that a workspace unlocks — profiles, data quality, transformations, the managed platform, the dashboard — see the introduction.

Playground destination

When you deploy and run pipelines on the dltHub platform, you can use destination="playground" without configuring credentials or storage. The platform provisions isolated storage for each workspace and loads your pipeline data as Delta tables. Use it for testing and for a faster introduction to the platform — set destination="playground" in your pipeline and run.

Quickstart

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 you to pick a coding agent (Claude / Cursor / Codex), then runs a guided first experience — it scaffolds the workspace, installs dlt[hub] and dependencies with uv sync, logs you in to the dltHub platform, runs a sample pipeline in a playground, and launches your agent ready to build your own source.

tip

Run dlthub-start yourself with no arguments — it's interactive and guides you through each step. It scaffolds into your current folder, so the AI skills land right where your coding agent is open.

Setting up your environment

Configuration of the Python environment

This documentation uses 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

Working within a virtual environment is recommended when creating Python projects. This way, all the dependencies for your current project are isolated from packages in other projects. With uv, run:

uv venv

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

uv venv --python 3.13

This uses Python 3.13 for your virtual environment.

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

source .venv/bin/activate

Add dltHub to an existing project

To add dltHub to an existing project, run:

uvx dlthub-init@latest

This scaffolds a workspace, installs dlt[hub], and sets up the AI skills your coding agent uses. The dlt[hub] extra pulls in two plugin packages:

• 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, etc.)

Workspace-level dependencies (destinations like duckdb, plus tools like marimo or fastmcp used by notebooks and MCP jobs) are managed in the generated pyproject.toml, not via dlt extras—extend it 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.

tip

A particular dlt version expects dlthub and dlthub-client versions in a matching range. For example: 1.27.x expects 0.27.x of each plugin. This is enforced via dependencies in the hub extra and at import time. Installing a plugin directly won't change the installed dlt version (to prevent unwanted upgrades). For example, if you run:

uv pip install dlthub

and it downloads 0.28.0 of the plugin, dlt 1.27.0 is still installed but reports a wrong plugin version on import (with instructions how to install a compatible plugin version).

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:

uvx dlthub-init@latest

This scaffolds a fresh, ready-to-run dltHub workspace—the .dlt/.workspace marker, local config and secrets, dependencies, and the dltHub AI skills your coding agent uses—and installs everything with uv sync. 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:

Ubuntu

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

macOS

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

Windows

mkdir .dlt
type nul > .dlt\.workspace