Skip to main content
Version: devel View Markdown

Installation

Supported Python versions

dltHub currently supports Python versions 3.10-3.13.

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.

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 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-platform, 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

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

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.

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:

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:

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

This demo works on codespaces. Codespaces is a development environment available for free to anyone with a Github account. You'll be asked to fork the demo repository and from there the README guides you with further steps.
The demo uses the Continue VSCode extension.

Off to codespaces!

DHelp

Ask a question

Welcome to "Codex Central", your next-gen help center, driven by OpenAI's GPT-4 model. It's more than just a forum or a FAQ hub – it's a dynamic knowledge base where coders can find AI-assisted solutions to their pressing problems. With GPT-4's powerful comprehension and predictive abilities, Codex Central provides instantaneous issue resolution, insightful debugging, and personalized guidance. Get your code running smoothly with the unparalleled support at Codex Central - coding help reimagined with AI prowess.