Installation

Prerequisites

meridian-tools requires Python 3.11 or later and a working installation of Google Meridian with schema support.

Install Meridian first

Meridian is the upstream modelling engine. Install it before meridian-tools:

pip install "google-meridian[schema]==1.5.3"

If you are working from a local Meridian checkout:

pip install -e "/path/to/meridian[schema]"

Verify the install:

from meridian import version
print(version.__version__)

Install meridian-tools

From the source tree (recommended for development)

cd /path/to/meridian-tools
pip install -e ".[dev]"

The [dev] extra installs pytest, ruff, and mypy for running the test suite and linter.

Editable install without dev extras

pip install -e .

Verify the install

meridian-tools --help

You should see the CLI help output listing the run and demo subcommands. This command is deliberately lightweight — it does not import TensorFlow, NumPy, or Meridian.

You can also verify in Python:

import meridian_tools
print(meridian_tools.__version__)

Runtime dependencies

The following are declared in pyproject.toml and installed automatically:

TensorFlow is not a direct dependency of meridian-tools. It comes transitively through google-meridian.

Development extras

pip install -e ".[dev]"

This adds:

Troubleshooting

If meridian-tools --help fails with an import error, check that:

1. You are in the correct virtual environment.
2. Meridian is installed with the [schema] extra.
3. Python version is 3.11 or later: python --version.

If pip install -e . fails, ensure setuptools>=68.0.0 is available:

pip install --upgrade setuptools

See the troubleshooting guide for more common issues.

Quickstart

This guide takes you from a fresh install to your first completed run in under five minutes using the bundled demo data.

1. Run a bundled demo

List the available demos:

meridian-tools demo --list

Output:

timeseries
geo_panel

Run the timeseries demo:

meridian-tools demo timeseries

When run from the source checkout, this creates a dated run directory under runs/demos/. When run from an installed package, the default output root is ./runs/demos/ relative to your current working directory. Each demo produces a full staged output layout.

2. Inspect the run directory

After the demo completes, find the created run directory:

ls runs/demos/

You will see a directory like demo-timeseries_20260402_073500/. The name comes from the demo’s project.name (demo-timeseries) plus a timestamp. The bundled demos now default to full-sample fits, so LOO and WAIC outputs are available in the assessment stage by default. Inside:

demo-timeseries_20260402_073500/
  run_manifest.json
  00_run_metadata/
    config.source.yaml
    config.resolved.yaml
  20_model_fit/
    meridian_model.binpb
    fit_metadata.json
  30_model_assessment/
    diagnostics_bundle.json
    model_results_summary.html
    loo_summary.json
    waic_summary.json
  40_decomposition/
    summary_metrics.csv
    summary_metrics.nc
  60_response_curves/
    response_curves.csv
    response_curves.nc
  70_optimisation/
    optimisation_summary.html
    optimised_data.csv

3. Read the key outputs

Start with the manifest:

cat runs/demos/demo-timeseries_*/run_manifest.json | python -m json.tool | head -20

Check the diagnostics bundle:

cat runs/demos/demo-timeseries_*/30_model_assessment/diagnostics_bundle.json | python -m json.tool

View the model results summary by opening the HTML file in your browser:

# Linux
xdg-open runs/demos/demo-timeseries_*/30_model_assessment/model_results_summary.html

# macOS
open runs/demos/demo-timeseries_*/30_model_assessment/model_results_summary.html

Inspect the decomposition CSV:

head runs/demos/demo-timeseries_*/40_decomposition/summary_metrics.csv

4. Run your own config

Create a YAML config file (e.g. project.yml):

project:
  name: my-first-run

data:
  path: ./my_data.csv
  kpi_type: revenue
  coord_to_columns:
    time: week
    geo: market
    kpi: revenue
    media: [impressions_tv, impressions_search]
    media_spend: [spend_tv, spend_search]

fit:
  n_chains: 4
  n_adapt: 500
  n_burnin: 500
  n_keep: 1000
  seed: 42

validation:
  strategy: blocked_tail
  holdout_size: 8

exports:
  export_predictive_accuracy: true
  export_review_summary: true
  export_model_selection: true

Run it:

meridian-tools run --config project.yml --output-dir runs

5. Next steps

• Read the configuration guide to understand every YAML section.
• Read the validation guide to choose the right validation strategy.
• Read the workflow guide for the full end-to-end agency workflow.
• Read the demo guide for more detail on the bundled reference workflows.