Installation

Marivo requires Python 3.10 or newer.

Choose an installation path

Choose one path. Use the installer for the shortest setup; use manual installation when the project must control its Python environment and datasource dependencies.

Option 1: Use the installer

Enter the directory that will contain the Marivo project, then run:

curl -fsSL https://marivo.io/install.sh | bash

The installer first ensures uv, uses it to install a managed Python 3.10 and create or reuse .venv, installs marivo[duckdb,trino,clickhouse], and runs marivo init in the current directory. It supports macOS, Linux, WSL, and Windows through Git Bash, MSYS2, or Cygwin. MySQL is intentionally not part of the default install; add marivo[mysql] manually after installing its native client prerequisites. On Windows, PowerShell is needed only when the installer must install uv. Continue directly to Verify the installation; do not also follow the manual steps below.

Option 2: Install manually

To control the environment and datasource backends, complete these steps in order.

1. Use uv to create a Python 3.10 or newer virtual environment:

uv venv --python 3.10 --seed
source .venv/bin/activate

On Windows Bash shells, activate it with source .venv/Scripts/activate.

2. Install the extra for the datasource backend the project will use:

Backend	Install command
DuckDB	uv pip install "marivo[duckdb]"
SQLite	uv pip install "marivo[sqlite]"
MySQL	uv pip install "marivo[mysql]"
Postgres	uv pip install "marivo[postgres]"
ClickHouse	uv pip install "marivo[clickhouse]"
Trino	uv pip install "marivo[trino]"
All packaged backends	uv pip install "marivo[all]"

3. Verify the installed version:

marivo --version

4. Initialize the current project directory once:

marivo init

When the current working directory is not the project root, use marivo init --project-root <project-directory>.

Run marivo init separately only for manual installation.

marivo init is idempotent: it leaves existing files untouched and reports them as skipped, so it is safe to re-run after an upgrade. Re-running adds only what is missing. Use marivo init --force to delete the generated artifacts and recreate them from scratch.

Note

init refuses to silently skip a marivo.toml that contains invalid TOML. Fix or remove it, or pass --force. Skill links are best-effort symlinks: if the platform cannot create a symlink, init prints a warning and continues.

What the agent can use

Path	Purpose
marivo.toml	Project manifest. The project name defaults to the directory name; local telemetry defaults to enabled = "on".
models/	Datasource and semantic declarations.
.marivo/	Project-local sessions, evidence, and cached metadata.
.agents/skills/	Links to the marivo-semantic and marivo-analysis skills for compatible agents.
.claude/skills/	Links to the same skills for Claude Code.
.codex/skills/	Links to the same skills for Codex.

your-project/
  marivo.toml
  models/
  .marivo/
  .agents/skills/
  .claude/skills/
  .codex/skills/

Verify the installation

After initialization, give the agent this bounded preparation request:

Check whether this Marivo project is initialized correctly and tell me what is missing before I use its existing semantic layer or create a new one. For credentials, check only environment-variable names and configuration status. Do not request, display, or commit credential values.

This separates project setup from access to business data and from decisions about business meaning.

When an agent is launched by another runtime, that runtime must provide the selected project interpreter. Marivo skills only verify that interpreter and marivo doctor; they do not choose a Python installation, create a virtual environment, or install dependencies.

What to review before continuing

Before choosing a project path, confirm that:

• marivo.toml, models/, and .marivo/ are present;
• the expected skill paths under .agents/skills/, .claude/skills/, and .codex/skills/ are present, or the initialization warning explains why a symlink could not be created;
• the required datasource backend extra is installed; and
• credentials are supplied through approved environment-backed fields, not committed as plaintext in project files.

When those checks pass, continue to Quick Start and choose whether to reuse an existing semantic layer or create one. After the selected project path is ready and its business meaning is approved, continue to the first analysis.