Getting Started#

Installing marimo gets you the marimo command-line interface (CLI), the entry point to all things marimo.

Installation#

Before installing marimo, we recommend creating and activating a Python virtual environment.

Setting up a virtual environment

Python uses virtual environments to minimize conflicts among packages. Here’s a quickstart for pip users. If you use conda, please use a conda environment instead.

Run the following in the terminal:

  • create an environment with python -m venv marimo-env

  • activate the environment:

    • macOS/Unix: source marimo-env/bin/activate

    • Windows: marimo-env\Scripts\activate

Make sure the environment is activated before installing marimo and when using marimo. Install other packages you may need, such as numpy, pandas, matplotlib, and altair, in this environment. When you’re done, deactivate the environment with deactivate in the terimnal.

Learn more from the official Python tutorial.

To install marimo, run the following in a terminal:

pip install marimo

conda install -c conda-forge marimo

To check if the install worked, run

marimo tutorial intro

A tutorial notebook should open in your browser.

Installation issues?

Having installation issues? Reach out to us at GitHub or on Discord.

Tutorials#

marimo tutorial intro opens the intro tutorial. List all tutorials with

marimo tutorial --help

Notebooks#

Create and edit notebooks with marimo edit.

  • create a new notebook:

marimo edit

  • marimo saves notebooks as Python files, which you can edit using:

marimo edit your_notebook.py

(If your_notebook.py doesn’t exist, marimo will create a blank notebook named your_notebook.py.)

Apps#

Use marimo run to serve your notebook as an app, with Python code hidden and uneditable.

marimo run your_notebook.py

Convert Jupyter notebooks#

Automatically translate Jupyter notebooks to marimo notebooks with marimo convert:

marimo convert your_notebook.ipynb > your_notebook.py

Because marimo is different from traditional notebooks, your converted notebook will likely have errors that you’ll need to fix. marimo will guide you through fixing them when you open it with marimo edit.

GitHub Copilot#

The marimo editor natively supports GitHub Copilot, an AI pair programmer, similar to VS Code.

Get started with Copilot:

  1. Install Node.js.

  2. Enable Copilot via the settings menu in the marimo editor.

Note: Copilot is not yet available in our conda distribution; please install marimo using pip if you need Copilot.

VS Code extension#

If you prefer VS Code over terminal, try our VS Code extension. Use this extension to edit and run notebooks directly from VS Code, and to list all marimo notebooks in your current directory.