Installation Guide

Whether you are a user or developer we recommend installing dataretrieval in a virtual environment. This can be done using something like virtualenv or conda. Package dependencies are declared in pyproject.toml: the core runtime dependencies under [project.dependencies], and optional extras (test, doc, nldi) under [project.optional-dependencies].

User Installation

Via pip:

To install the latest stable release of dataretrieval from PyPI, run the following commands:

$ pip install dataretrieval

Via conda:

To install the latest stable release of dataretrieval from the conda-forge channel, run the following commands:

$ conda install -c conda-forge dataretrieval

Developer Installation

To install dataretrieval for development, we recommend first forking the repository on GitHub. This will allow you to develop on your own feature branch, and propose changes as pull requests to the main branch of the repository.

The first step is to clone your fork of the repository:

$ git clone https://github.com/DOI-USGS/dataretrieval-python.git

Then, set the cloned repository as your current working directory in your terminal and run the following commands to get an “editable” installation of the package for development:

$ pip install -e ".[test,doc,nldi]"

This installs dataretrieval in editable mode along with the development extras: test (test runner), doc (documentation build), and nldi (geopandas, required by the NLDI module).

To check your installation you can run the tests with the following commands:

$ cd tests
$ pytest

In order to fetch the latest version of dataretrieval, we recommend defining the main repository as a remote upstream repository:

$ git remote add upstream https://github.com/DOI-USGS/dataretrieval-python.git

You can also build the documentation locally by running the following commands:

$ cd docs
$ make docs

This both tests the documentation (runs code blocks and checks links), and also locally builds the documentation, placing the HTML files within the docs/build/html directory. You can then open the index.html file in your browser to view the documentation.