Installation

plenoptic should work on Windows, Linux, or Mac. If you have a problem with installation, please open a bug report!

You can install plenoptic from PyPI (the Python Package Index) or conda-forge, and we provide separate instructions for the two methods.

If you will be contributing to plenoptic, and so need an editable install and Optional dependencies, you should use pip. Otherwise, you can use whichever you are more familiar with, though we have noticed that it tends to be easier to install pytorch with GPU support using conda.

Tip

If you are unfamiliar with python environment management, we recommend Installing with conda.

Our dependencies include pytorch and pyrtools. Installation should take care of them (along with our other dependencies) automatically, but if you have an installation problem (especially on a non-Linux operating system), it is likely that the problem lies with one of those packages. Open an issue and we’ll try to help you figure out the problem!

Installing with conda

Warning

We do not currently support conda installs on Windows, due to the lack of a Windows pytorch package on conda-forge. Therefore, if you are installing on Windows, you must use pip. See this issue for the status of the conda-forge Windows pytorch build.

If you wish to follow these instructions and do not have conda installed on your machine, we recommend starting with miniconda.

Once you have conda correctly installed and on your path, run the following to create a new virtual environment and install plenoptic:

$ conda create --name plenoptic pip python=3.11
$ conda activate plenoptic
$ conda install plenoptic -c conda-forge

Installing with pip

While conda handles both virtual environment management and package installation, pip only installs packages; you’ll need to use some other system to manage your virtual environment.

In order to avoid this problem, here we’ll use python’s built-in venv to manage the virtual environment with pip.

# create the environment
$ python -m venv path/to/environments/plenoptic-venv
# activate the environment
$ source path/to/environment/plenoptic-venv/bin/activate
$ pip install plenoptic

# create the environment
$ python -m venv path\to\environments\plenoptic-venv
# activate the environment
$ path\to\environment\plenoptic-venv\Scripts\activate
$ pip install plenoptic

Note that when using venv, you have to decide where you’d like to place the folder containing all files related to the virtual environment. If the virtual environment is related to the development of a package, as in Installing from source (for developers), it is typical to place them within the repository for that package. Otherwise, it is typical to place them all in a single directory somewhere so they’re easy to keep track of.

Note

You can use conda to manage your virtual environment and pip to install packages, but note that when using pip with a conda environment, all pip commands should come after all the conda commands (e.g., you shouldn’t run conda install matplotlib after pip install plenoptic), because conda is unaware of any changes that pip makes. See this blog post for more details.

Installing from source (for developers)

You can also install plenoptic directly from source in order to have a local editable copy. This is most useful for developing (for more info, see our contributing guide) or if you want to use the most cutting-edge version.

$ git clone https://github.com/plenoptic-org/plenoptic.git
$ cd plenoptic
# create the environment (this is typically placed in the package's root folder)
$ python -m venv .venv
# activate the environment
$ source .venv/bin/activate
# install in editable mode with `-e` or, equivalently, `--editable`
$ pip install -e ".[dev]"

$ git clone https://github.com/plenoptic-org/plenoptic.git
$ cd plenoptic
# create the environment (this is typically placed in the package's root folder)
$ python -m venv .venv
# activate the environment
$ .venv\Scripts\activate
# install in editable mode with `-e` or, equivalently, `--editable`
$ pip install -e ".[dev]"

In this setup, we’re installing the dev optional dependencies as well as the core dependencies. This will allow you to run our tests. They are, as the name implies, optional (you can just run pip install -e . without the [dev]), but if you are developing, you will probably want to be able to run the tests. See the Optional dependencies section for more details and the other sets of optional dependencies.

Note that, with the above setup, all files related to your virtual environment are stored in a hidden directory named .venv within the plenoptic/ directory you cloned. Therefore, if you delete the plenoptic/ directory, you’ll need to rerun the setup above to create a new virtual environment.

Attention

To install plenoptic in editable mode, you need pip >= 21.3 (see pip’s changelog). If you run into an error after running the pip install -e . command, try updating your pip version with pip install --upgrade pip.

Optional dependencies

In addition to installing plenoptic and its core dependencies, you may also wish to install some of our optional dependencies. These dependencies are specified using square brackets during the pip install command and can be installed for either a local, editable install or one directly from PyPI:

  • If you would like to run the jupyter notebooks locally: pip install "plenoptic[nb]" or pip install -e ".[nb]". This includes pooch (for downloading some extra data) torchvision (which has some models we’d like to use), jupyter, and related libraries. See Using Jupyter to Run Example Notebooks for a discussion of several ways to handle jupyter and python virtual environments. Note that you can run our notebooks in the cloud using Binder, no installation required!

  • If you would like to run the tests: pip install -e ".[dev]". This includes pytest and related libraries. (This probably only makes sense if you have a local installation.)

  • If you would like to locally build the documentation: pip install -e ".[docs]". This includes sphinx and related libraries. (This probably only makes sense if you have a local installation.)

These optional dependencies can be joined with a comma, e.g., pip install -e ".[docs,dev]"

Note

Note that conda does not support optional dependencies, though you can view our optional dependencies in the pyproject.toml file, if you wish to install them yourself.