A reactive notebook for Python — run reproducible experiments, query with SQL, execute as a script, deploy as an app, and version with git. Stored as pure Python. All in a modern, AI-native editor.
Python artificial-intelligencedagdata-sciencedata-visualizationdataflowdeveloper-toolsmachine-learningnotebookspipelinepythonreactivesqlweb-app
# Makefile for marimo - Development and build tasks
# Prerequisites:
# - uv: for Python dependency management, testing, and building
# - pnpm: for frontend development
# - Node.js: for frontend development
DENO_VERSION := 2.7.14
DENO ?= uv tool run --from deno==$(DENO_VERSION) deno
DESIGN_MD_DENO_FLAGS := --no-config --no-lock --node-modules-dir=none
DESIGN_MD_READ_PATHS := frontend/src/css/app/App.css,frontend/src/css/app/Cell.css,frontend/src/core/codemirror/theme/dark.ts,frontend/src/core/codemirror/theme/light.ts,frontend/src/core/config/config-schema.ts,frontend/src/plugins/impl/data-editor/themes.ts,frontend/src/css/globals.css,frontend/src/components/editor/renderers/grid-layout/plugin.tsx,frontend/tailwind.config.cjs
DESIGN_MD_DENO_RUN_FLAGS := $(DESIGN_MD_DENO_FLAGS) --allow-read=$(DESIGN_MD_READ_PATHS) --allow-env=CI
DESIGN_MD_LINTER ?= pnpm --silent dlx @google/[email protected]
.PHONY: help
# 📖 Show available commands
help:
@printf "\nMarimo Development Commands:\n\n"
@awk '/^#/{c=substr($$0,3);next}c&&/^[[:alpha:]][[:alnum:]_-]+:/{printf " \033[36m%-20s\033[0m %s\n", substr($$1,1,index($$1,":")-1),c}1{c=0}' $(MAKEFILE_LIST)
@printf "\nRun 'make check-prereqs' and 'make install-all' to get started!\n\n"
###############
# Setup Tasks #
###############
.PHONY: install-all
# 🚀 First-time setup: Install all dependencies (frontend & Python)
install-all: fe py
.PHONY: check-prereqs
# ✓ Check if all required tools are installed
check-prereqs:
@command -v pnpm >/dev/null 2>&1 || { echo "pnpm is required. See https://pnpm.io/installation"; exit 1; }
@pnpm -v | grep -vq "^[0-9]\." || { echo "pnpm v12+ is required. Current version: $(shell pnpm -v)"; exit 1; }
@command -v uv >/dev/null 2>&1 || { echo "uv is required. See https://docs.astral.sh/uv/getting-started/installation/"; exit 1; }
@command -v node >/dev/null 2>&1 || { echo "Node.js is required. See https://nodejs.org/en/download/"; exit 1; }
@node -v | grep -q "v2[0-9]" || { echo "Node.js v20+ is required. Current version: $(shell node -v)"; exit 1; }
@echo "✅ All prerequisites are installed!"
.PHONY: py
# 🐍 Install Python dependencies in editable mode
py:
@command -v uv >/dev/null 2>&1 || { echo "uv is required. See https://docs.astral.sh/uv/getting-started/installation/"; exit 1; }
uv pip install --group=dev -e .
######################
# Development Tasks #
######################
.PHONY: fe
# 🔧 Build frontend assets
fe: marimo/_static marimo/_lsp
# 🔧 Install/build frontend if anything under frontend/
marimo/_static: $(shell find frontend/src) $(wildcard frontend/*)
./scripts/buildfrontend.sh
# 🔧 Install/build lsp if anything in lsp/ has changed
marimo/_lsp: $(shell find packages/lsp)
./scripts/buildlsp.sh
.PHONY: dev
dev: fe-codegen
@echo "Starting development servers..."
@# Start both processes, with marimo in background
@(trap 'kill %1; exit' INT; \
uv run marimo edit --no-token --headless /tmp --port 2718 & \
pnpm dev)
dev-sandbox:
@echo "Starting development servers..."
@# Start both processes, with marimo in background
@(trap 'kill %1; exit' INT; \
uv run marimo edit /tmp/notebook.py --no-token --headless --sandbox & \
pnpm dev)
#############
# Testing #
#############
.PHONY: test
# 🧪 Run all tests (frontend, Python, end-to-end)
test: fe-test py-test e2e
.PHONY: check
# 🧹 Run all checks
check: fe-check py-check
.PHONY: fe-check
# 🧹 Check frontend (lint, typecheck)
fe-check: fe-lint fe-typecheck
.PHONY: fe-test
# 🧪 Test frontend
fe-test:
CI=true pnpm turbo --filter @marimo-team/frontend test -- --run
.PHONY: e2e
# 🧪 Test end-to-end
e2e:
cd frontend; pnpm playwright install; pnpm playwright test
.PHONY: visual-test
# 🖼️ Test visual baselines in the pinned Playwright container
visual-test: fe
./scripts/run-visual-regression.sh
.PHONY: visual-update
# 🖼️ Update visual baselines in the pinned Playwright container
visual-update: fe
./scripts/run-visual-regression.sh --update-snapshots
.PHONY: fe-lint
# 🧹 Lint frontend
fe-lint:
cd frontend/src && uv run typos && cd - && pnpm --filter @marimo-team/frontend lint
.PHONY: fe-typecheck
# 🔍 Typecheck frontend
fe-typecheck:
pnpm turbo --filter @marimo-team/frontend typecheck
.PHONY: fe-codegen
# 🔄 Generate frontend API
fe-codegen:
uv run --isolated --python=3.12 --with-editable . marimo development openapi > packages/openapi/api.yaml
pnpm run codegen
pnpm format packages/openapi/
.PHONY: host-protocol-codegen
# Generate host protocol Python bindings
host-protocol-codegen:
uv run --no-config --locked --script protocols/host/generate.py --include-experimental
.PHONY: host-protocol-check
# Check host model generation and portable protocol fixtures
host-protocol-check:
@tmp=$$(mktemp -d); trap 'rm -rf "$$tmp"' EXIT; \
uv run --no-config --locked --script protocols/host/generate.py --output-dir "$$tmp"
uv run --no-config --locked --script protocols/host/generate.py --include-experimental --check
uv run --locked --project protocols/host/conformance pytest -c protocols/host/conformance/pyproject.toml protocols/host/conformance protocols/host/experimental
.PHONY: fe-plugin-schema
# 🔄 Generate frontend plugin API schema
fe-plugin-schema:
pnpm --filter @marimo-team/frontend plugins:generate-schema
.PHONY: design-md
# 🔄 Generate DESIGN.md
design-md:
$(DENO) run $(DESIGN_MD_DENO_RUN_FLAGS) scripts/generate-design-md.ts > DESIGN.md
.PHONY: design-md-check
# 🔍 Check DESIGN.md generation
design-md-check:
$(DENO) check $(DESIGN_MD_DENO_FLAGS) scripts/generate-design-md.ts
$(DENO) lint --no-config scripts/generate-design-md.ts
@tmp=$$(mktemp); \
trap 'rm -f "$$tmp"' EXIT; \
$(DENO) run $(DESIGN_MD_DENO_RUN_FLAGS) scripts/generate-design-md.ts > "$$tmp"; \
diff -u DESIGN.md "$$tmp" || { \
echo "DESIGN.md is not up to date. Run 'make design-md' to update it."; \
exit 1; \
}
$(DESIGN_MD_LINTER) lint DESIGN.md
.PHONY: py-check
# 🔍 Typecheck, lint, format python
py-check:
./scripts/pycheck.sh
.PHONY: typos
# 🔍 Check for typos
typos:
uv run typos
.PHONY: py-test
# 🧪 Test python
py-test:
uv run typos
./scripts/pytest.sh --optional $(ARGS)
.PHONY: py-test-narwhals
# 🧪 Test narwhals-related tests (used externally by narwhals repo)
py-test-narwhals:
uv run --group test pytest \
tests/_data/ \
tests/_plugins/ui/_impl/ \
tests/_utils/test_narwhals_utils.py
.PHONY: py-snapshots
# 📸 Update snapshots
py-snapshots:
uv run --group test pytest \
tests/_server/templates/test_templates.py \
tests/_server/api/endpoints/test_export.py \
tests/test_api.py
##############
# Packaging #
##############
.PHONY: wheel
# 📦 Build wheel
wheel:
uv build
#################
# Documentation #
#################
.PHONY: docs
# 📚 Build docs
docs:
uv run --group docs mkdocs build
.PHONY: docs-serve
# 📚 Serve docs
docs-serve:
uv run --group docs mkdocs serve --clean
.PHONY: docs-llms
# 📚 Build docs + generate per-page .md files and the llms.txt index into site/
docs-llms: docs
uv run --group docs python docs/scripts/html_to_markdown.py \
--input-dir site --base-url https://docs.marimo.io
uv run --group docs python docs/scripts/generate_llms_txt.py \
--input-dir site --base-url https://docs.marimo.io \
--output-index site/llms.txt
.PHONY: storybook
# 🧩 Start Storybook for UI development
storybook:
pnpm --filter @marimo-team/frontend storybook