# Rerun Python examples
The simplest example is [`minimal`](minimal/minimal.py). You may want to start there!

Read more about our examples at <https://www.rerun.io/examples>.

## Setup
First install the Rerun Python SDK with `pip install rerun-sdk` or via [`conda`](https://github.com/conda-forge/rerun-sdk-feedstock).

> Note: Make sure your SDK version matches the code in the examples.
For example, if your SDK version is `0.15.1`, check out the matching tag
for this repository by running `git checkout v0.15.1`.

## Installing the example
Each example is packaged as a regular Python package, with a `pyproject.toml` file specifying its required dependencies. To run an example, it must first be installed.

For example, to install dependencies and run the toy `minimal` example (which doesn't need to download any data) run:

```sh
pip install -e examples/python/minimal
```

**Note**: it is import to install example in editable mode, which is done using the `-e` flag (short for `--editable`).

Once installed, the example can be run as a regular Python module:

```shell
python -m minimal
```

Examples also declare console script, so they can also be run directly:

```shell
minimal
```


## Running the examples
By default, the examples spawn a Rerun Viewer and stream log data to it.

For most examples you can instead save the log data to an `.rrd` file using `plots --save data.rrd`. You can then view that `.rrd` file with `rerun data.rrd`.

(`rerun` is an alias for `python -m rerun`).

NOTE: `.rrd` files do not yet guarantee any backwards or forwards compatibility. One version of Rerun will likely not be able to open an `.rrd` file generated by another Rerun version.

## Running examples with Pixi

The Rerun project makes extensive use of [Pixi](https://pixi.sh/latest/) for various developer tasks, and Pixi can be used to run examples as well. For this, you need to install Pixi as per the installation instructions on their website.

### Running examples with Pixi from source

You can build Rerun from source, and install it in the uv environment managed by Pixi. Note that this requires a Rust toolchain to be installed on your system.

Before running examples, build the SDK:
```shell
pixi run py-build
```

Now you can run examples via uv:
```shell
pixi run uv run examples/python/minimal/minimal.py
```

### Installing and running examples
You can install all of the rerun python examples into the uv managed environment with:
```shell
pixi run py-build-examples
```

Then you can just examples based on their installed name, for example:
```shell
pixi run uv run plots
```

## Datasets
Some examples will download a small datasets before they run. They will do so the first time you run the example. The datasets will be added to a subdir called `dataset`, which is in the repo-wide `.gitignore`.

## Contributions welcome
Feel free to open a PR to add a new example!

If you add an example, please make sure to add the corresponding entry to the top-level `pixi.toml` file as well, otherwise it will not be picked up.

See [`CONTRIBUTING.md`](../../CONTRIBUTING.md) for details on how to contribute.