# Installation

## Requirements

- Python >= 3.10

- GDAL >= 3.6

- Reading to GeoDataFrames requires `geopandas>=0.12` and `shapely>=2`. Additionally, installing `pyarrow` enables a further speed-up when specifying `use_arrow=True`.

## Installation

### Conda-forge

This package is available on conda-forge for Linux, MacOS, and Windows.

    conda install -c conda-forge pyogrio

This requires compatible versions of `GDAL` and `numpy` from `conda-forge` for raw I/O support and `geopandas` and their dependencies for GeoDataFrame I/O support. By default, the `GDAL` package on conda-forge already supports a wide range of vector formats. If needed, you can install additional drivers by installing the associated conda-forge package. The following packages are currently available to install extra vector drivers:

- `libgdal-arrow-parquet` ((Geo)Parquet and (Geo)Arrow IPC)

- `libgdal-pg` (PostgreSQL / PostGIS)

- `libgdal-xls` (XLS - MS Excel format)

### PyPI

This package is available on PyPI for Linux, MacOS, and Windows.

    pip install pyogrio

This installs binary wheels that include GDAL.

If you get installation errors about Cython or GDAL not being available, this is most likely due to the installation process falling back to installing from the source distribution because the available wheels are not compatible with your platform.

Note that the GDAL version included in the binary wheels is not always the latest version and is likely to be a different version than the system GDAL. Please use `pyogrio.__gdal_version_string__` to get the GDAL version being used by pyogrio. Also note that the wheels include the most common GDAL vector drivers (GeoJSON, ESRI Shapefile, GPKG, FGB, OpenFileGDB, etc), but not all drivers. Use `pyogrio.list_drivers()` to list the drivers available in pyogrio.

If you need drivers that are not included in the wheels, or if you need pyogrio to use a newer version of GDAL, consider using `conda-forge` to install pyogrio as explained above.

### Troubleshooting installation errors

If you install GeoPandas or Fiona using `pip`, you may encounter issues related to incompatibility of the exact GDAL library pre-installed with Fiona and the version of GDAL that gets compiled with Pyogrio.

This may show up as an exception like this for a supported driver (e.g., `ESRI Shapefile`):

    pyogrio.errors.DataSourceError: Could not obtain driver ...

To get around it, uninstall `fiona` then reinstall to use system GDAL:

    pip uninstall fiona
    pip install fiona --no-binary fiona

Then restart your interpreter. This ensures that both Pyogrio and Fiona use exactly the same GDAL library.

## Development

Clone this repository to a local folder.

Install an appropriate distribution of GDAL for your system. Either `gdal-config` must be on your system path (to automatically determine the GDAL paths), or either the `GDAL_INCLUDE_PATH`, `GDAL_LIBRARY_PATH`, and `GDAL_VERSION` environment variables need to be set. Specific instructions on how to install these dependencies on Windows can be found below.

Building Pyogrio requires requires `Cython`, `numpy`, and `pandas`.

Pyogrio follows the GeoPandas Style Guide and uses `Ruff` to ensure consistent formatting.

It is recommended to install `pre-commit` and register its hooks so the formatting is automatically verified when you commit code.

    pre-commit install

Run `python setup.py develop` to build the extensions in Cython.

Tests are run using `pytest`:

    pytest pyogrio/tests

### Windows

There are different ways to install the necessary dependencies and setup your local development environment on windows.

#### vcpkg

vcpkg is used to build pyogrio from source as part of creating the Pyogrio Python wheels for Windows. You can install GDAL and other dependencies using vcpkg, and then build Pyogrio from source.

See `.github/workflows/release.yml` for details about how vcpkg is used as part of the wheel-building process.

We do not yet have instructions on building Pyogrio from source using vcpkg for local development; please feel free to contribute additional documentation!

#### OSGeo4W

You can also install GDAL from an appropriate provider of Windows binaries. We’ve heard that the OSGeo4W works.

To build on Windows, you need to provide additional environment variables or command-line parameters because the location of the GDAL binaries and headers cannot be automatically determined.

Assuming GDAL 3.8.3 is installed to `c:\GDAL`, you can set the `GDAL_INCLUDE_PATH`, `GDAL_LIBRARY_PATH` and `GDAL_VERSION` environment variables and build as follows:

    set GDAL_INCLUDE_PATH=C:\GDAL\include
    set GDAL_LIBRARY_PATH=C:\GDAL\lib
    set GDAL_VERSION=3.8.3
    python -m pip install --no-deps --force-reinstall --no-use-pep517 -e . -v

Alternatively, you can pass those options also as command-line parameters:

    python -m pip install --install-option=build_ext --install-option="-IC:\GDAL\include" --install-option="-lgdal_i" --install-option="-LC:\GDAL\lib" --install-option="--gdalversion=3.8.3" --no-deps --force-reinstall --no-use-pep517 -e . -v

The location of the GDAL DLLs must be on your system `PATH`.

`--no-use-pep517` is required in order to pass additional options to the build backend (see https://github.com/pypa/pip/issues/5771).

#### Conda

It is also possible to install the necessary dependencies using conda.

After cloning the environment, you can create a conda environment with the necessary dependencies like this:

    conda env create -f environment-dev.yml

Before being able to build on Windows, you need to set some additional environment variables because the location of the GDAL binaries and headers cannot be automatically determined.

After activating the `pyogrio-dev` environment the `CONDA_PREFIX` environment variable will be available. Assuming GDAL 3.8.3 is installed, you will be able to set the necessary environment variables as follows:

    set GDAL_INCLUDE_PATH=%CONDA_PREFIX%\Library\include
    set GDAL_LIBRARY_PATH=%CONDA_PREFIX%\Library\lib
    set GDAL_VERSION=3.8.3

Now you should be able to run `python setup.py develop` to build the extensions in Cython.

## GDAL and PROJ data files

GDAL requires certain files to be present within a GDAL data folder, as well as a PROJ data folder. These folders are normally detected automatically.

If you have an unusual installation of GDAL and PROJ, you may need to set additional environment variables at runtime in order for these to be correctly detected by GDAL:

- set `GDAL_DATA` to the folder containing the GDAL data files (e.g., contains `header.dxf`) within the installation of GDAL that is used by Pyogrio.

- set `PROJ_LIB` to the folder containing the PROJ data files (e.g., contains `proj.db`)