Importing packages¶
By default, marimo searches for packages in the virtual environment it was started in. For example, if you run
you'll be able to import packages installed in the environment you just activated. You'll also be able to install packages into this environment using the marimo editor's package management UI.
Using uv?
See our uv guide for details on how to use marimo as part of uv projects or as self-contained scripts.
Inlining dependencies¶
As an alternative to manually creating and managing a virtual environment, you can let marimo manage virtual environments for you, on a per-notebook basis.
If you create a notebook with the --sandbox flag —
— marimo will start your notebook in an isolated environment and keep track of the dependencies you install from the editor. These dependencies are inlined in the notebook file, so that the next time you run the notebook, marimo will run it in an isolated environment with just those dependencies.
See our guide on inlining dependencies to learn more.
What about kernels?
Unlike Jupyter, marimo does not have a concept of "kernels"; notebooks simply use the active virtual environment.
The main feature of kernels is to allow different notebooks to depend on different packages, even within the same project. marimo's package sandbox provides this functionality, while also being far simpler to use than custom kernels.
Importing local modules¶
marimo resolves imports just as Python does: by searching for packages
in the directories listed in sys.path. That means that in addition to the
virtual environment, marimo will search for modules in the directory in which
the notebook lives. For example, when you run
marimo will look for modules in /path/to/notebook_dir. However, this means
that you may need to take additional steps to import modules that live outside
this directory. What steps you take depends on whether your code is organized
as a Python package.
Remember: notebooks are just Python programs
In the examples below, notebooks are stored in a separate notebooks
directory, which is traditional. However, since marimo notebooks are just
Python modules, you can just as well include them in your src/ directory
alongside other Python modules.
From non-package projects¶
You can configure the Python path to accommodate directory structures that look like this:
In particular, to make import my_module work when running
add the following configuration to your pyproject.toml:
From packages¶
New to Python packages?
A Python package is a
way of structuring Python source files so that the collection of files can
be installed in an environment, imported using "dot" notation like
from my_package.my_module import my_function, and optionally uploaded
to package registries like PyPI.
If you are new to packages, and find you need to create one, we recommend
using uv (uv init --package).
A package has a directory structure like this:
.
├── notebooks
│ └── my_notebook.py
├── pyproject.toml
└── src
└── my_package
├── __init__.py
└── my_module.py
Say my_notebook has a cell with
Provided that
is run from an environment in which your package is installed, marimo
will import my_module without issue.
For example, if you are using uv, simply run