Installing the InVEST Python Package¶
Attention
Most users will want to install the InVEST app (Mac disk image or Windows installer) from the InVEST download page. The instructions here are for more advanced use cases.
Note
To install the natcap.invest
package, you must have a C/C++ compiler
installed and configured for your system. MacOS and Linux users should
not need to do anything. Windows users should install Microsoft Visual
Studio, or at least the Build Tools for Visual Studio, if they have
not already. See the python wiki page on compilation under Windows for more information.
Suggested method¶
Pattern:
conda create -y -c conda-forge -n <name> python=<python version>
conda activate <name>
conda install -y -c conda-forge gdal=<gdal version>
pip install natcap.invest==<invest version>
Replace <name>
with any name you’d like to give your environment.
Replace <python version>
with a python version known to be compatible with the desired invest version.
Replace <gdal version>
with a GDAL version known to be compatible with the desired invest version.
Replace <invest version>
with the desired invest version.
Most of the time, it is not really necessary to specify the versions of python
, gdal
, and natcap.invest
. If you do not specify a version, the latest version will be installed. Usually the latest versions are compatible with each other, but not always. Specifying versions that are known to work can prevent some problems. You can find the supported range of GDAL versions in the requirements.txt (be sure to switch to the desired release tag in the dropdown).
Example for InVEST 3.9.1:
conda create -y -c conda-forge -n invest391 python=3.9.7
conda activate invest391
conda install -y -c conda-forge gdal=3.3.1
pip install natcap.invest==3.9.1
Condensed into one line:
conda create -y -c conda-forge -n invest391 python=3.9.7 gdal=3.3.1 && conda activate invest391 && pip install natcap.invest==3.9.1
Details¶
Here is an explanation of what the commands are doing:
Create a brand-new environment with the correct python version.
conda create -y -c conda-forge -n <name> python=<python version>
To be safe, you should always install
natcap.invest
into a brand-new virtual environment. This way you can be sure you have all the right versions of dependencies. Many issues with installing or using thenatcap.invest
package arise from dependency problems, and it’s a lot easier to create a new environment than it is to fix an existing one.Activate the brand-new environment just created.
conda activate <name>
If you run
conda list
after this, you’ll see the specified python version is there along with around 15 other packages that are included with python by default. None of these are specific to invest. You’re now in an isolated environment so you can control which versions of dependencies are available to invest.Install GDAL before installing invest
conda install -y -c conda-forge gdal=<gdal version>
This is important because GDAL is not an ordinary python package. When you install the
natcap.invest
package in step 4,pip
will also install all the dependencies ofnatcap.invest
. Whenpip
tries to install GDAL, you will get an error unless the underlying GDAL binaries are already installed. That’s because thegdal
package thatpip
installs is just a python wrapper that depends on the GDAL binaries. GDAL itself is not a python package and can’t be installed withpip
. Luckily, it can be installed withconda
!Install invest
pip install natcap.invest=<invest version>
pip
will also install the correct versions of all dependencies ofnatcap.invest
.Since sometimes we don’t need to use the UI at all, the basic
natcap.invest
package does not include the dependencies required for the UI. If you try to use the UI without having installed the UI dependencies, you’ll get an error. If you do want to use the invest UI via the python package, installnatcap.invest
with the UI package extra:pip install natcap.invest[ui]=<invest version>
The
[ui]
tellspip
to also install all the dependencies needed for the UI.
Python Dependencies¶
Dependencies for natcap.invest
are listed in requirements.txt
:
GDAL>=3.1.2,!=3.3.0 # 3.3.0 had a bug that broke our windows builds: https://github.com/OSGeo/gdal/issues/3898
Pyro4==4.77 # pip-only
pandas>=1.2.1
numpy>=1.11.0,!=1.16.0
Rtree>=0.8.2,!=0.9.1
Shapely>=1.7.1,<2.0.0
scipy>=1.6.0 # pip-only
pygeoprocessing>=2.3.2 # pip-only
taskgraph[niced_processes]>=0.11.0 # pip-only
psutil>=5.6.6
chardet>=3.0.4
openpyxl
pint
Babel
Additional dependencies for the UI are listed in requirements-gui.txt
:
qtpy>1.3 # pip-only
qtawesome # pip-only
requests
PySide2!=5.15.0 # pip-only
Flask
Please use conda
and pip
to install the correct versions of these dependencies automatically as described above.
Binary Dependencies¶
InVEST itself depends only on python packages, but many of these package
dependencies, such as numpy, scipy, and GDAL, depend on low-level libraries
or have complex build processes. Precompiled binaries of all these dependencies
are now available through conda
and/or pip
. We recommend using conda
to manage these dependencies because it simplifies the install process and
helps ensure versions are compatible. However, they may also be available through
your system package manager.
Installing the latest development version¶
Pre-built binaries¶
Pre-built installers and wheels of development versions are available from http://releases.naturalcapitalproject.org/?prefix=invest/, along with other distributions of InVEST. Once downloaded, wheels can be installed locally via pip.
Installing from source¶
The latest development version of InVEST can be installed from our git source tree if you have a compiler installed:
$ pip install "git+https://github.com/natcap/invest@main#egg=natcap.invest"