Installation

UXarray itself is a pure Python package, but its dependencies are not. The easiest way to get everything installed is to use conda or pip.

Conda versus Pip

Conda installs UXarray with all optional dependencies. Pip installs only the minimal required dependencies by default, but it is also easy to include any/all optional dependencies too, if desired.

Installing with Conda

To install UXarray with its recommended dependencies using the conda command line tool:

conda install -c conda-forge uxarray

Installing with pip

For a lightweight installation with only required dependencies:

pip install uxarray

For a complete installation which also includes all optional dependencies:

pip install "uxarray[complete]"

For an installation including only some optional dependencies, consider using one of the following extras:

• pip install "uxarray[dev]" includes development tools (e.g. pytest, ruff)

• pip install "uxarray[geo]" includes geospatial packages (e.g. geopandas, healpix)

• pip install "uxarray[viz]" includes plotting packages (e.g. matplotlib, hvplot)

It is also possible to combine extras, for example:

• pip install "uxarray[geo,viz]" includes all geospatial and plotting packages.

To see the full lists of which optional dependencies are included with each extra group, take a look at the [project.optional-dependencies] section in pyproject.toml:

[project.optional-dependencies]
all = ["uxarray[dev,geo,viz]"]
complete = ["uxarray[dev,geo,viz]"]  # alias to "all"
dev = [
    'asv',
    'pooch',
    'pre_commit',
    'pytest',
    'pytest-cov',
    'ruff',
]
geo = [
    "cartopy>=0.23",  # in both geo and viz because it is needed by to_geodataframe() and by plotting routines.
    # (0.23 is the first release that works with numpy 2.)
    "geopandas>=1.0",  # 1.0 is the first release requiring pyogrio, the file-IO backend read_file needs. See #1693.
    "healpix>=2024.2",  # older releases are built against numpy 1 and fail to import under numpy 2.
    "pyproj",
    "spatialpandas>=0.4.10",  # PolygonArray.from_exterior_coords() is new in 0.4.10.
]
viz = [
    "cartopy>=0.23,<0.26",  # cartopy 0.26.0 breaks some geoviews plots; see issue #1780.
    # (cartopy pin intentionally here but not in "geo" extras because geoviews is only in "viz".)
    "datashader",
    "matplotlib>=3.8.4,<3.11",  # 3.11.0 breaks some plots (see issue #1542); older releases without a numpy<2 cap fail under numpy 2.
    "geoviews>=1.11.0",  # older releases use np.NaN, removed in numpy 2. No upper pin; newer should support any cartopy; see holoviz/geoviews#884.
    "holoviews>=1.19.0",  # older releases import panel.depends.param_value_if_widget, which current panel removed.
    "hvplot>=0.8.3",  # older releases use param's .params(), removed in param 2.
]

Installing from source

Installing from source is intended mainly for developers.

1. Clone the repo

   git clone https://github.com/UXARRAY/uxarray.git
   cd uxarray
   

2. Create a dev environment

   A ready-made file is provided at ci/environment.yml:

   conda env create -f ci/environment.yml
   conda activate uxarray_build
   

3. Install UXarray

   pip install ".[complete]"   # test suite relies on optional dependencies
   

4. Optional: run the test suite

   Running the test suite is a good way to verify that the installation is working correctly. It should take roughly a minute to run on modern machines.

   pytest test
   

Verifying your installation

After installing UXarray, you can verify the installation by running the following in a Python shell or script:

import uxarray as ux

print(ux.__version__)

This should print the installed version of UXarray without errors.