Skip to content

Commit

Permalink
Update installation docs (#67)
Browse files Browse the repository at this point in the history
  • Loading branch information
giswqs authored Sep 23, 2024
1 parent 3caf4a8 commit 1cc572d
Showing 1 changed file with 8 additions and 33 deletions.
41 changes: 8 additions & 33 deletions docs/installation.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,59 +6,34 @@ The geospatial package has many dependencies, such as [GeoPandas](https://geopan

[![Introducing geospatial](images/thumbnail.png)](https://youtu.be/Y1xB7d2VbFY "Introducing geospatial")

### Installing using uv
## Installing using uv

[uv](https://docs.astral.sh/uv/) is an extremely fast Python package and project manager, written in Rust. It is designed to be a drop-in replacement for pip. You can install `geospatial` using `uv` as follows:

```bash
uv pip install geospatial
uv pip install --find-links https://girder.github.io/large_image_wheels gdal pdal pyproj
```

## Installing with Anaconda/Miniconda

To install geospatial and all its dependencies, we recommend you use the [conda](https://conda.io/en/latest) package manager. This can be obtained by installing the [Anaconda Distribution](https://www.anaconda.com/distribution) (a free Python distribution for data science), or through [Miniconda](https://docs.conda.io/en/latest/miniconda.html) (minimal distribution only containing Python and the conda package manager). See also the [installation docs](https://conda.io/docs/user-guide/install/download.html) for more information on how to install Anaconda or Miniconda locally.

### Using the conda-forge channel

Geospatial is available on the [conda-forge](https://anaconda.org/conda-forge/geospatial) channel, a community effort that provides [conda packages](https://conda-forge.org) for a wide range of software.
If you are on Linux and want to install GDAL, you can use the following command:

```bash
conda install -c conda-forge geospatial
```

### Creating a new conda environment

Creating a new environment is not strictly necessary, but given that some geospatial dependencies might have a version conflict with other geospatial packages in an existing conda environment, it is a good practice to install geospatial and its dependencies in a clean environment starting fresh.

The following commands create a new conda environment with the name `geo` and install geospatial and its dependencies (e.g., GeoPandas, localtileserver) in it:

```bash
conda create -n geo python=3.9
conda activate geo
conda install geopandas
conda install geospatial -c conda-forge
uv pip install --find-links https://girder.github.io/large_image_wheels gdal pdal pyproj
```

**Important note:** If you are using Windows, we advise you to closely follow the installation instructions above to install GeoPandas from the default conda channel (`conda install geopandas`) rather than from the conda-forge channel. This can avoid a potential `spatialindex_c-64.dll` error when using GeoPandas ([source](https://github.com/geopandas/geopandas/issues/1812)). If you are using Linux or macOS, it is okay to install all geospatial dependencies from the conda-forge channel with the following command:

```bash
conda install -c conda-forge geospatial
```
For windows and macOS users, you can install GDAL using mamba as shown in the following section.

### Using Mamba
## Installing using conda

When installing packages using the conda package manager, sometimes it can take a while for conda to resolve dependencies. If it takes too long or fails to resolve dependencies, you can try using the [Mamba](https://mamba.readthedocs.io/en/latest) package manager to install geospatial and its dependencies. Mamba is a fast, robust, and cross-platform package manager. It runs on Windows, macOS, and Linux, and is fully compatible with conda packages and supports most of conda’s commands. Once Mamba is installed in a conda environment, you can then simply replace any `conda` command with `mamba`. For example, to install geospatial and its dependencies with Mamba, you can use the following commands:
To install geospatial and all its dependencies, we recommend you use the [mamba](https://mamba.readthedocs.io/en/latest/user_guide/mamba.html) package manager. This can be obtained by installing the [Anaconda Distribution](https://www.anaconda.com/download) (a free Python distribution for data science), or through [Miniconda](https://docs.anaconda.com/miniconda/) (minimal distribution only containing Python and the conda package manager).

```bash
conda create -n geo python=3.9
conda create -n geo python
conda activate geo
conda install -c conda-forge mamba
mamba install geopandas
mamba install -c conda-forge geospatial
```

## Installing with pip
## Installing using pip

geospatial is also available on [PyPI](https://pypi.org/project/geospatial). It can be installed with pip using the following command:

Expand Down

0 comments on commit 1cc572d

Please sign in to comment.