Installation and building

Simple installation

The simplest way to install improv is with pip:

pip install improv

Warning

Due to this pyzmq issue, if you’re running on Ubuntu, you may need to specify

pip install improv --no-binary pyzmq

to build pyzmq from source if you’re running into ZMQ errors.

Optional dependencies

In addition to the basic improv installation, users who want to, e.g., run tests locally and build docs should do

pip install improv[tests,docs]

(on bash) or

pip install "improv[tests,docs]"

(on zsh for newer Macs).

Building from source

Users who want to run the demos or contribute to the project will want to build and install from source.

You can either obtain the source code from our current releases (download and unzip the Source code (zip) file) or via cloning from GitHub:

git clone https://github.com/project-improv/improv.git

With the code downloaded, you’ll then need to build and install the package. For installation, we recommend using a virtual environment so that improv and its dependencies don’t conflict with your existing Python setup. For instance, using mamba:

mamba create -n improv python=3.10

will create an improv environment running Python 3.10 that you can activate via

mamba activate improv

Other options, such as virtualenv will also work. (conda is largely superseded by mamba.)

Currently, we build using Setuptools via a pyproject.toml file as specified in PEP 518. This may allow us to switch out the build backend (or frontend) later.

For now, the package can be built by running

pip install --editable .

from within the project directory. this will install the package in editable mode, which means that changes in the project directory will affect the code that is run (i.e., the installation will not copy over the code to site-packages but simply link the project directory).

When uninstalling, be sure to do so from outside the project directory, since otherwise, pip only appears to find the command line script, not the full package.

Building documents locally

Currently, we have GitHub Actions set up to build the Jupyter Book automatically. But for previewing changes locally, you will want to build the documents and check them yourself.

To do that, you’ll first need to install the docs dependencies with

pip install improv[docs]

or

pip install -e .[docs]

Then simply run

jupyter-book build docs

and open docs/_build/html/index.html in your browser.