Skip to content

tycoon setup

Build a project-local .venv on a supported Python interpreter, using uv. Added in v0.1.9 (#57).

Why

tycoon runs dbt out of the same interpreter it lives in — it imports dlt/duckdb in-process and resolves dbt at Path(sys.executable).parent / "dbt". So the single most common first-mile failure is a mismatched Python: dbt-core / dbt-duckdb ship no wheels for 3.14 yet, and an out-of-range interpreter fails far from its cause (at tycoon data transform run).

tycoon setup removes the trap by owning the environment. It seeds a pyproject.toml beside tycoon.yml (if one doesn't already exist), creates one .venv on a supported interpreter via uv sync, pins it with .python-version, and installs tycoon + its dbt/dlt/duckdb stack into it, writing uv.lock so the exact same environment is reproducible later with just uv sync. uv downloads a python-build-standalone CPython if your machine only has an unsupported one, zero manual interpreter installs.

Synopsis

tycoon setup [OPTIONS]

Options:
  --python TEXT    Python version (major.minor) for the .venv. Must be in
                   tycoon's supported range (>=3.12,<3.14). Default: 3.13.
  --from TEXT      Package spec to install. Default: database-tycoon.
                   Pass `-e <absolute-path>` for an editable dev checkout.
  --no-install     Create and pin the .venv but skip installing tycoon.
  --force          Rebuild the .venv if one already exists (re-resolves
                   dependencies fresh, doesn't delete it outright).
  --no-prompt      Skip confirmation prompts (CI / scripted bootstrap).
  -h, --help       Show this message and exit.

Quick start

cd my-project          # a dir with tycoon.yml (run `tycoon init` first)
tycoon setup           # builds .venv on Python 3.13 via uv
source .venv/bin/activate
tycoon doctor          # confirms the interpreter is now in range

The new environment is separate from the interpreter running tycoon right now — setup can't swap Python under its own feet, so activate the .venv before running further commands.

Prerequisites

setup needs uv on your PATH. If it's missing, setup points you at the standalone installer rather than running it for you (a network installer is a deliberate, user-triggered step):

curl -LsSf https://astral.sh/uv/install.sh | sh

Recipes

# Pin a specific supported interpreter
tycoon setup --python 3.12

# Dev checkout, install a working tree editable instead of the published wheel.
# Needs an absolute path: `.` would self-reference the project `setup` just seeded.
tycoon setup --from '-e /abs/path/to/tycoon-cli'

# Recreate a broken/stale environment
tycoon setup --force

# Scaffold the env in CI without installing tycoon into it
tycoon setup --no-install --no-prompt

Relationship to tycoon doctor

tycoon doctor's first check verifies the running interpreter is in range. When it's out of range, tycoon doctor --fix runs this same .venv-build flow for you. setup is the explicit front door; doctor --fix is the in-context repair.