We welcome contributions. You don't need to be an expert in frontend or Python development to help out.
Contributions are made through pull requests. Before sending a pull request, make sure to do the following:
- Obtain maintainer approval
- Lint, typecheck, and format your code (
make check) - Write and run tests
- Provide visual evidence for changes made
- Read and sign the CLA by commenting on the PR:
I have read the CLA Document and I hereby sign the CLA
Contributors must obtain maintainer approval before making pull requests with substantial changes. Substance is not measured only in lines of code. Here is a non-exhaustive list of changes we consider substantial:
- changes to the public API;
- changes to required or optional dependencies;
- changes to CI workflows;
- changes with large internal refactors;
- changes to our documentation architecture;
- changes to default configuration;
- opinionated changes to the user interface or user experience;
- changes to the semantics of marimo's runtime;
- changes to marimo's file format;
- changes with many lines of code.
To obtain approval, open a GitHub issue describing the change you would like to make and discuss it with a maintainer. If you would like to make a PR for an issue that already exists, join the conversation in that issue.
Labels. We use GitHub labels to categorize issues into two states:
needs discussion— not ready for a PRready— ready for a PR
If an issue does not have one of these two labels, assume it is not ready for a PR and requires discussion.
Deliberate design. marimo is an intentionally designed project. We put just as much thought into the features we exclude as the ones we include, in order to provide our users with a simple, consistent, delightful, and powerful experience.
For examples of the thought we put in, see our MEPs repo and read our founding essays.
Consistency. Each feature affects the whole product. A change that seems locally helpful can make the system less consistent and therefore harder to learn, explain, or evolve.
Small changes can have large consequences. Unlike traditional software, in open source, some changes are irreversible. Even seemingly minor changes — like adjusting a function signature or adding “just one more option” — can have long-lasting consequences.
Maintenance burden. New features create new work. What may seem like a small change in lines of code can have a disproportionately large maintenance cost when integrated over time.
Review burden. Though the cost of writing code has decreased, the cost of reviewing code has not (in fact, it has increased). Asking a maintainer or community member to review your changes imposes a cost on their time. Building consensus before making the pull request shows respect.
Early consensus prevents wasted effort. Seeking approval before implementing a substantial change increases the chance that your work will be merged.
Note: We recommend that Windows developers use WSL and clone the marimo repository into the WSL environment and not the Windows mount.
make fe && make py
make devThis will build the frontend, install Python dependencies in editable mode, and launch the dev server (backend on port 2718, frontend on port 3000).
make dev will suit most development needs: it serves the frontend from Vite, which is faster to iterate on but not identical to production. Use pnpm --dir frontend build:watch when you want a production-like frontend, and marimo -d edit --no-token when you want backend debug logs.
make help lists every development command. The targets are defined in the Makefile.
For changes to host contracts, generated bindings, or client libraries, start with the host protocol contributor guide. It links the Effect definitions, generation commands, and conformance checks.
You can optionally install pre-commit hooks to automatically run the validation checks when making a commit:
uvx pre-commit installWe have frontend unit tests, Python unit tests, and end-to-end tests. Code changes should be accompanied by unit tests. Some changes should also be accompanied by end-to-end tests.
To run all tests:
make testThis can take some time. To run just frontend tests, just Python tests, or just end-to-end tests, read below.
make fe-testmake py-testWe use pytest syntax for Python tests.
Run a specific test
uv run --python 3.13 --group test pytest tests/_ast/Run all changed tests
uv run --python 3.13 --group test pytest --pickedRun tests with optional dependencies
uv run --python 3.13 --group test-optional pytest tests/_ast/Build the frontend first with make fe so Playwright runs against your latest changes.
make e2eFrom frontend/, run pnpm playwright test --ui to run interactively, pnpm playwright test $FILENAME for one file, or add --debug to step through it. See the Playwright best practices.
All PRs require visual evidence for user-facing changes. For broad changes, check that other features and components do not regress, including different user flows and edge cases.
For example, if you are adding a new API plugin, ensure the UI shows how different parameters combine together to produce the expected output.
When submitting a pull request, marimo will run: lint, typecheck, and test jobs.
We have some labels which can influence which tests are run:
test-all: Run all tests across unchanged files as well.