Installation¶

We strongly recommend installing xHydro in an Anaconda Python environment. Furthermore, due to the complexity of some packages, the default dependency solver can take a long time to resolve the environment. If mamba is not already your default solver, consider running the following commands in order to speed up the process:

conda install -n base conda-libmamba-solver
conda config --set solver libmamba

If you don’t have pip installed, this Python installation guide can guide you through the process.

Note

Some libraries used by xHydro or its dependencies may not function correctly unless the appropriate environment is activated. To avoid potential issues, it is strongly recommended to always activate your environment before running any Python code. You can do this with the following command:

conda activate name_of_your_environment

This recommendation also applies to certain GUI applications, such as PyCharm, which may not automatically activate the project environment. In such cases, be sure to activate the environment before launching the application.

On Windows, this can be done by running the command above in the Anaconda Prompt, and then launching the application from that same prompt. Alternatively, you can launch the application via Anaconda Navigator, ensuring the correct environment is selected beforehand.

Stable release (Anaconda)¶

Some of the dependencies of xHydro can be difficult to install using pip. For this reason, we strongly recommend installing xHydro using Anaconda. This will ensure that all dependencies are met and that the package will work as expected.

conda install -c conda-forge xhydro

This will install the latest stable release of xHydro with all its dependencies, with two exception:

If you wish to use the extreme_value_analysis module, which relies on the Extremes.jl Julia package, you will need to install the julia extra:

pip install xhydro[julia]

If you wish to use the frequency_analysis.regional module, you will need to install the lmoments3 library yourself. This library is available on both PyPI or conda-forge, but has a restricted license. Note that if you installed xHydro using conda, you will need to install lmoments3 using conda as well. If you installed xHydro using the environment-dev.yml file, lmoments3 will have been added automatically.

conda install -c conda-forge lmoments3

Stable release (PyPI)¶

Although not recommended, you can also install xHydro from PyPI using pip:

pip install xhydro

Some dependencies of xHydro may not be fully functional when installed via pip. For example, packages like xESMF may require additional system-level configuration to work correctly.

The considerations mentioned above regarding the extreme_value_analysis and frequency_analysis.regional modules also apply to the PyPI installation, but with a few additional notes:

The julia extra requires a working C++ compiler. Some users have reported segmentation faults when using the juliacall library with xHydro installed from PyPI, which we believe is due to the Julia environment not being launched with the correct C++ compiler. If you encounter this issue, we recommend using the conda installation method instead.
The raven extra relies on the ravenpy and raven-hydro packages, which can be challenging to install in standard pip environments due to complex system-level dependencies. See the note below for more details. Unless you are familiar with the installation of these packages, we recommend using the conda installation method instead.

Note

We have not currently done extensive testing for installing the raven extra using pip, but the following commands are known to work on some Linux systems:

apt-get update && apt-get upgrade -y
apt-get install -y git gdal-bin python3-gdal libgdal-dev libnetcdf-dev build-essential
pip install xhydro[raven]

This will install ravenpy and raven-hydro from PyPI. Alternatively, you can replace the last line and install ravenpy only, provided that you have your own Raven executable. For further guidance on installing these packages, refer to the official documentation of ravenpy and raven-hydro.

Warning

On Windows, installing all the dependencies for ravenpy may require Administrator privileges, as some packages must be added to the system PATH. If you encounter issues, consider using the Anaconda installation method instead.

From sources¶

xHydro is still under active development and the latest features might not yet be available on PyPI or conda-forge. If you want to use the latest features, or if you want to contribute to the development of xHydro, you can install it from the sources.

The sources for xHydro can be downloaded from the Github repo.

Download the source code from the Github repo using one of the following methods:
- Clone the public repository:
  git clone git@github.com:hydrologie/xhydro
- Download the tarball:
  curl -OJL https://github.com/hydrologie/xhydro/tarball/main
Once you have a copy of the source, you can install it with:
conda env create -f environment-dev.yml conda activate xhydro-dev make development
If you are on Windows, replace the make development command with the following:
python -m pip install --group dev python -m pip install --no-user --editable . prek install
Even if you do not intend to contribute to xHydro, we favor using environment-dev.yml over environment.yml because it includes additional packages that are used to run all the examples provided in the documentation. If for some reason you wish to install the PyPI version of xHydro into an existing Anaconda environment (not recommended if requirements are not met), only run the last command above.
When new changes are made to the Github repo, you can update your local copy using the following commands from the root of the repository:
git fetch git checkout main git pull origin main conda env update -n xhydro-dev -f environment-dev.yml conda activate xhydro-dev make development
These commands should work most of the time, but if big changes are made to the repository, you might need to remove the environment and create it again.