Installation

Installation#

Required dependencies#

Optional dependencies#

Note

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

  • 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.

  • iris: for conversion to and from iris’ Cube objects

For accelerating xarray#

  • scipy: necessary to enable the interpolation features for xarray objects

  • bottleneck: speeds up NaN-skipping and rolling window aggregations by a large factor

  • numbagg: for exponential rolling window operations

For parallel computing#

For plotting#

Alternative data containers#

  • sparse: for sparse arrays

  • pint: for units of measure

  • 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: 30 months (NEP-29)

  • numpy: 18 months (NEP-29)

  • all other libraries: 12 months

This means the latest minor (X.Y) version from N months prior. 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:

pydata/xarray

Instructions#

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:

$ python -m pip install xarray

We also maintain other dependency sets for different subsets of functionality:

$ python -m pip install "xarray[io]"        # Install optional dependencies for handling I/O
$ python -m pip install "xarray[accel]"     # Install optional dependencies for accelerating xarray
$ python -m pip install "xarray[parallel]"  # Install optional dependencies for dask arrays
$ python -m pip install "xarray[viz]"       # Install optional dependencies for visualization
$ python -m 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 [project.optional-dependencies] section in pyproject.toml:

[project.optional-dependencies]
accel = ["scipy", "bottleneck", "numbagg", "numba>=0.54", "flox", "opt_einsum"]
complete = ["xarray[accel,etc,io,parallel,viz]"]
dev = [
  "hypothesis",
  "jinja2",
  "mypy",
  "pre-commit",
  "pytest",
  "pytest-cov",
  "pytest-env",
  "pytest-xdist",
  "pytest-timeout",
  "ruff",
  "sphinx",
  "sphinx_autosummary_accessors",
  "xarray[complete]",
]
io = ["netCDF4", "h5netcdf", "scipy", 'pydap; python_version<"3.10"', "zarr", "fsspec", "cftime", "pooch"]
etc = ["sparse"]
parallel = ["dask[complete]"]
viz = ["cartopy", "matplotlib", "nc-time-axis", "seaborn"]

[project.urls]
Documentation = "https://docs.xarray.dev"
SciPy2015-talk = "https://www.youtube.com/watch?v=X0pAhJgySxk"
homepage = "https://xarray.dev/"
issue-tracker = "https://github.com/pydata/xarray/issues"
source-code = "https://github.com/pydata/xarray"

[project.entry-points."xarray.chunkmanagers"]
dask = "xarray.namedarray.daskmanager:DaskManager"

Development versions#

To install the most recent development version, install from github:

$ python -m pip install git+https://github.com/pydata/xarray.git

or from TestPyPI:

$ python -m pip install --index-url https://test.pypi.org/simple --extra-index-url https://pypi.org/simple --pre xarray

Testing#

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 repository.

Performance Monitoring#

To run these benchmark tests in a local machine, first install

and run asv run  # this will install some conda environments in ./.asv/envs

Contents