If you are using pip to install xarray, optional dependencies can be installed by specifying extras. Instructions for both pip and conda are given below.
For netCDF and IO¶
netCDF4: recommended if you want to use xarray for reading or writing netCDF files
scipy: used as a fallback for reading/writing netCDF3
pydap: used as a fallback for accessing OPeNDAP
h5netcdf: an alternative library for reading and writing netCDF4 files that does not use the netCDF-C libraries
PyNIO: for reading GRIB and other geoscience specific file formats. Note that PyNIO is not available for Windows and that the PyNIO backend may be moved outside of xarray in the future.
zarr: for chunked, compressed, N-dimensional arrays.
cftime: recommended if you want to encode/decode datetimes for non-standard calendars or dates before year 1678 or after year 2262.
PseudoNetCDF: recommended for accessing CAMx, GEOS-Chem (bpch), NOAA ARL files, ICARTT files (ffi1001) and many other.
rasterio: for reading GeoTiffs and other gridded raster datasets.
iris: for conversion to and from iris’ Cube objects
cfgrib: for reading GRIB files via the ECMWF ecCodes library.
For accelerating xarray¶
Alternative data containers¶
sparse: for sparse arrays
pint: for units of measure
At the moment of writing, xarray requires a highly experimental version of pint (install with
pip install git+https://github.com/andrewgsavage/pint.git@refs/pull/6/head). Even with it, interaction with non-numpy array libraries, e.g. dask or sparse, is broken.
Any numpy-like objects that support NEP-18. Note that while such libraries theoretically should work, they are untested. Integration tests are in the process of being written for individual libraries.
Minimum dependency versions¶
xarray adopts a rolling policy regarding the minimum supported version of its dependencies:
Python: 42 months (NEP-29)
setuptools: 42 months (but no older than 38.4)
numpy: 24 months (NEP-29)
dask and dask.distributed: 12 months (but no older than 2.9)
sparse, pint and other libraries that rely on NEP-18 for integration: very latest available versions only, until the technology will have matured. This extends to dask when used in conjunction with any of these libraries. numpy >=1.17.
all other libraries: 12 months
The above should be interpreted as the minor version (X.Y) initially published no more than N months ago. Patch versions (x.y.Z) are not pinned, and only the latest available at the moment of publishing the xarray release is guaranteed to work.
You can see the actual minimum tested versions:
xarray itself is a pure Python package, but its dependencies are not. The easiest way to get everything installed is to use conda. To install xarray with its recommended dependencies using the conda command line tool:
$ conda install -c conda-forge xarray dask netCDF4 bottleneck
If you require other Optional dependencies add them to the line above.
We recommend using the community maintained conda-forge channel, as some of the dependencies are difficult to build. New releases may also appear in conda-forge before being updated in the default channel.
If you don’t use conda, be sure you have the required dependencies (numpy and pandas) installed first. Then, install xarray with pip:
$ pip install xarray
We also maintain other dependency sets for different subsets of functionality:
$ pip install "xarray[io]" # Install optional dependencies for handling I/O $ pip install "xarray[accel]" # Install optional dependencies for accelerating xarray $ pip install "xarray[parallel]" # Install optional dependencies for dask arrays $ pip install "xarray[viz]" # Install optional dependencies for visualization $ pip install "xarray[complete]" # Install all the above
The above commands should install most of the optional dependencies. However,
some packages which are either not listed on PyPI or require extra
installation steps are excluded. To know which dependencies would be
installed, take a look at the
[options.extras_require] section in
[options.extras_require] io = netCDF4 h5netcdf scipy pydap zarr fsspec cftime rasterio cfgrib ## Scitools packages & dependencies (e.g: cartopy, cf-units) can be hard to install # scitools-iris accel = scipy bottleneck numbagg parallel = dask[complete] viz = matplotlib seaborn nc-time-axis ## Cartopy requires 3rd party libraries and only provides source distributions ## See: https://github.com/SciTools/cartopy/issues/805 # cartopy complete = %(io)s %(accel)s %(parallel)s %(viz)s docs = %(complete)s sphinx-autosummary-accessors sphinx_rtd_theme ipython ipykernel jupyter-client nbsphinx scanpydoc
To run the test suite after installing xarray, install (via pypi or conda) py.test and run
pytest in the root directory of the xarray
A fixed-point performance monitoring of (a part of) our codes can be seen on this page.
To run these benchmark tests in a local machine, first install
airspeed-velocity: a tool for benchmarking Python packages over their lifetime.
asv run # this will install some conda environments in ./.asv/envs