# Installation

## Required dependencies

- Python 2.7 [1], 3.4, 3.5, or 3.6
- numpy (1.11 or later)
- pandas (0.18.0 or later)

## Optional dependencies

### 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
- zarr: for chunked, compressed, N-dimensional arrays.
- netcdftime: recommended if you want to encode/decode datetimes for non-standard calendars or dates before year 1678 or after year 2262.

### For accelerating xarray

- bottleneck: speeds up NaN-skipping and rolling window aggregations by a large factor (1.1 or later)
- cyordereddict: speeds up most internal operations with xarray data structures (for python versions < 3.5)

### For parallel computing

- dask.array (0.9.0 or later): required for Parallel computing with dask.

### For plotting

- matplotlib: required for Plotting
- cartopy: recommended for Maps
- seaborn: for better color palettes

## 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 xarray dask netCDF4 bottleneck

We recommend using the community maintained conda-forge channel if you need difficult-to-build dependencies such as cartopy or pynio:

    $ conda install -c conda-forge xarray cartopy pynio

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

## Testing

To run the test suite after installing xarray, first install (via pypi or conda)

- py.test: Simple unit testing library
- mock: additional testing library required for python version 2

and run `py.test --pyargs xarray`.

### Performance Monitoring

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.

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

[1]

Xarray plans to drop support for python 2.7 at the end of 2018. This means that new releases of xarray published after this date will only be installable on python 3+ environments, but older versions of xarray will always be available to python 2.7 users. For more information see the following references:

> - Xarray Github issue discussing dropping Python 2
> - Python 3 Statement
> - Tips on porting to Python 3