Installation¶

TL;DR: ReDel requires Python 3.10+. You can install ReDel though pip:

$ pip install "redel[all]"

Warning

The default installation without any extras defined is a “thin” configuration - it contains only what’s needed to run a ReDel system, without the web interface or bundled tools. This can be useful to avoid dependency pollution, but we recommend installing the all or web extra if it’s your first time using the library.

Extras¶

To use the bundled web viewer and/or bundled example tools, you’ll need to install a few additional packages. ReDel provides these dependencies as extras, which you can specify with your installation command (e.g. pip install "redel[all]"). ReDel provides the following extras:

all: All extras included below.
web: All the dependencies needed to run the web interface (an HTTP server, ASGI, and websockets)
bundled: The dependencies needed to use the bundled Browsing tool.

If you plan to use the bundled browsing tool, you will also need to run playwright install chromium.

Installing on Conda¶

You may need to install pip in your conda environment first:

$ conda install pip

Then, follow the instructions for installing with pip above.

Caution

In certain cases when using a conda venv, the pip binary may reference a different environment, and ReDel may appear to be uninstalled even if pip assures that it is. Using python -m pip install in place of pip install may mitigate this issue.

Virtual Environment¶

If you’re not using conda, we recommend using a virtual environment to manage your project dependencies. This will help you prevent polluting your global Python installation with all sorts of packages.

macOS/Linux

$ python -m venv ./venv
$ ./venv/bin/activate
$ pip install "redel[all]"

Windows

$ python -m venv venv
$ venv\Scripts\activate.bat
$ pip install "redel[all]"

Development Version¶

If you’d like to install the development version of ReDel, you can install it from GitHub directly:

From source

$ git clone https://github.com/zhudotexe/redel.git
$ cd redel
$ pip install -e ".[all]"
  # alternatively, use `pip install -r requirements.txt` for dev dependencies

pip

$ pip install 'redel[all] @ git+https://github.com/zhudotexe/redel.git@main'

Note

You may need to use pip install --upgrade --no-deps --force-reinstall ... to force pip to re-fetch the latest ReDel from GitHub.

This will install the latest version of ReDel. You’ll then need to build the web frontend yourself (see below).

Caution

Development versions of ReDel may be unstable! We do not recommend using development ReDel in production or in final research experiments; pin a released version of ReDel instead.

Building Web Interface¶

To build the web interface, you’ll need Node 18 or higher. If you don’t have Node installed on your system, we recommend using nvm to install the latest LTS version.

$ cd viz
$ npm run build

Note

We recommend rebuilding the frontend after each update when using a development version. The version distributed over pip will always include the latest frontend version.

Requirements File¶

If you’re running experiments using ReDel, we recommend pinning the version of ReDel to ensure your runs are reproducible. To do this, we recommend storing all your Python requirements in a requirements.txt file.

redel[all]==x.y.z
# ... other dependencies

You can automatically generate this file too, by running pip freeze > requirements.txt.

Later, anyone else running your code can install the same dependency versions by simply running pip install -r requirements.txt.