# Installation of ProgressiVis

## Installation for users

To start, you probably want `ProgressiVis` with it's `Jupyter` visualizations.
If you only need the `ProgressiVis` core, install the `progressivis` package, without options.

Currently these installations are continually tested with `Linux`. They should also work on `MacOS` and `Windows`.

### With pip

(progressivis-jupyter-install)=

#### Installing `ProgressiVis` with it's `Jupyter` extension:

Be careful, if you use a shell such as `zsh`, to put quotes around the package name because of the brackets.
```
pip install 'progressivis[jupyter]'
```

#### Installing `ProgressiVis` core:

```
pip install progressivis
```

## Installation for developers

```{eval-rst}
.. note::
   To use all the capabilities of `ProgressiVis`, including visualizations, you must install both the `progressivis` repository and it's `Jupyter` extension repository (named `ipyprogressivis`), as outlined below. It’s recommended to clone both repositories into a shared directory. We assume you are connected to this directory.
```

### Installing `ProgressiVis`

1. Clone the [ProgressiVis repository](https://github.com/progressivis/progressivis/):

```
git clone https://github.com/progressivis/progressivis.git
```

It is not mandatory, but it is preferable to install `ProgressiVis` in a dedicated `Python` environment, created for example with `conda`. If you don't want to work in a `conda` environment, skip the following 2 steps.

2. Create a `conda` environment (named below `pvenv`):

```
conda create -n pvenv python=3.13
```


3. Activate this environment:

```
conda activate pvenv
```
4. Execute:

```
cd progressivis
pip install -e .[typing]
```
#### Getting updates

```
cd progressivis
git pull
```

### Installing the `Jupyter` extension for `ProgressiVis`:

1. Clone the repository named [ipyprogressivis](https://github.com/progressivis/ipyprogressivis/):

```
cd (back to your main directory, e.g. ..)
git clone https://github.com/progressivis/ipyprogressivis.git
```

2. If you choose to work in a conda environment, activate the environment you have created for  `progressivis` (previously called `pvenv`).

3. Install `yarn v1` in your environment

If you are using a conda environment do:

```
conda install yarn=1
```

Otherwise use the means specific to your environment to install `yarn v1`

4. Execute:

```
cd ipyprogressivis
pip install -e .[dev]
```
Installing a package in edit mode (the `-e` option) allows you to execute the latest changes in your source code without reinstalling the package.

However, this option only affects the Python part of the package. To obtain a similar effect for the JavaScript part (i.e. be able to execute the modified code without having to reinstall the package), you must run:

```shell
jupyter labextension develop . --overwrite
```

This way, whenever you modify `.js` files, you can run the modified code after running `yarn run build` in the `ipyprogressivis/js/` directory. The modified code will be available in your notebook after you restart the Jupyter server.

#### Getting updates

```
cd ipyprogressivis
git pull
```

then:

```
cd ipyprogressivis/js
yarn run build
```

If `jupyter` is running, you should restart it.

```{eval-rst}
.. note::
   At this stage, the user guide examples should work in the jupyter lab environment. `ProgressiVis` notebook relies on jupyter lab rather than the traditional notebook because progressive programs are not linear by nature and need special navigation tools in the notebook, easier to design and deploy on jupyter lab.
```