--- title: Installation description: Install dlt[hub], create a workspace, and license paid features keywords: [installation, dlthub, dlthub-init, dlthub-start, workspace mode, license] --- :::info 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](../pipeline-operations/profiles.md), 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](../pipeline-operations/profiles.md), [data quality](../data-quality/index.md), [transformations](../transformations/index.md), the [managed platform](../pipeline-operations/overview.md), the [dashboard](../ingestion/dashboard.md) — see the [introduction](introduction.md). ### 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](../ingestion/delta.md). Use it for testing and for a faster introduction to the platform — set `destination="playground"` in your pipeline and run. Read more about [playground destination](../ingestion/playground.md). ## Quickstart If you already have `uv` installed: ```sh uvx dlthub-start@latest ``` If you don't have `uv` yet, either [install it first](#setting-up-your-environment) or run via `pipx` — the CLI will offer to install `uv` for you before syncing dependencies: ```sh 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](https://docs.astral.sh/uv/getting-started/installation/). Once you have `uv` installed you can pick any Python version supported by it: ```sh uv python install 3.13 ``` or use any Python version you have installed on your system. ### Virtual environment Working within a [virtual environment](https://docs.python.org/3/library/venv.html) 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: ```sh uv venv ``` This creates a virtual environment in the `.venv` folder using the default system Python version. ```sh 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.: ```sh source .venv/bin/activate ``` ## Add dltHub to an existing project To add dltHub to an existing project, run: ```sh 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](../pipeline-operations/overview.md) (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 `. ## Upgrade existing installation To upgrade just the `hub` extra without upgrading `dlt` itself run: ```sh 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: ```sh 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](../pipeline-operations/overview.md)—is gated behind **Workspace mode**, signaled by a `.dlt/.workspace` marker file. The simplest way to turn it on is: ```sh 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](../ingestion/init.md) for the next steps. If you'd rather flip the toggle by hand in an existing project, create the empty marker file yourself: ```sh mkdir -p .dlt && touch .dlt/.workspace ``` ```sh mkdir -p .dlt && touch .dlt/.workspace ``` ```sh mkdir .dlt type nul > .dlt\.workspace ```