| 1 |
============ |
| 2 |
Installation |
| 3 |
============ |
| 4 |
|
| 5 |
Installation of the Fiona package is complicated by its dependency on libgdal |
| 6 |
and other C libraries. There are easy installations paths and an advanced |
| 7 |
installation path. |
| 8 |
|
| 9 |
Easy installation |
| 10 |
================= |
| 11 |
|
| 12 |
Fiona has several `extension modules |
| 13 |
<https://docs.python.org/3/extending/extending.html>`__ which link against |
| 14 |
libgdal. This complicates installation. Binary distributions (wheels) |
| 15 |
containing libgdal and its own dependencies are available from the Python |
| 16 |
Package Index and can be installed using pip. |
| 17 |
|
| 18 |
.. code-block:: console |
| 19 |
|
| 20 |
pip install fiona |
| 21 |
|
| 22 |
These wheels are mainly intended to make installation easy for simple |
| 23 |
applications, not so much for production. They are not tested for compatibility |
| 24 |
with all other binary wheels, conda packages, or QGIS, and omit many of GDAL's |
| 25 |
optional format drivers. If you need, for example, GML support you will need to |
| 26 |
build and install Fiona from a source distribution. |
| 27 |
|
| 28 |
Many users find Anaconda and conda-forge a good way to install Fiona and get |
| 29 |
access to more optional format drivers (like GML). |
| 30 |
|
| 31 |
Fiona 1.9 (coming soon) requires Python 3.7 or higher and GDAL 3.2 or higher. |
| 32 |
|
| 33 |
Advanced installation |
| 34 |
===================== |
| 35 |
|
| 36 |
Once GDAL and its dependencies are installed on your computer (how to do this |
| 37 |
is documented at https://gdal.org) Fiona can be built and installed using |
| 38 |
setuptools or pip. If your GDAL installation provides the ``gdal-config`` |
| 39 |
program, the process is simpler. |
| 40 |
|
| 41 |
Without pip: |
| 42 |
|
| 43 |
.. code-block:: console |
| 44 |
|
| 45 |
GDAL_CONFIG=/path/to/gdal-config python setup.py install |
| 46 |
|
| 47 |
With pip (version >= 22.3 is required): |
| 48 |
|
| 49 |
.. code-block:: console |
| 50 |
|
| 51 |
python -m pip install --user -U pip |
| 52 |
GDAL_CONFIG=/path/to/gdal-config python -m pip install --user . |
| 53 |
|
| 54 |
These are pretty much equivalent. Pip will use setuptools as the build backend. |
| 55 |
If the gdal-config program is on your executable path, then you don't need to |
| 56 |
set the environment variable. |
| 57 |
|
| 58 |
Without gdal-config you will need to configure header and library locations for |
| 59 |
the build in another way. One way to do this is to create a setup.cfg file in |
| 60 |
the source directory with content like this: |
| 61 |
|
| 62 |
.. code-block:: ini |
| 63 |
|
| 64 |
[build_ext] |
| 65 |
include_dirs = C:/vcpkg/installed/x64-windows/include |
| 66 |
libraries = gdal |
| 67 |
library_dirs = C:/vcpkg/installed/x64-windows/lib |
| 68 |
|
| 69 |
This is the approach taken by Fiona's `wheel-building workflow |
| 70 |
<https://github.com/sgillies/fiona-wheels/blob/master/.github/workflows/win-wheels.yaml#L67-L74>`__. |
| 71 |
With this file in place you can run either ``python setup.py install`` or ``python |
| 72 |
-m pip install --user .``. |
| 73 |
|
| 74 |
You can also pass those three values on the command line following the |
| 75 |
`setuptools documentation |
| 76 |
<https://setuptools.pypa.io/en/latest/userguide/ext_modules.html#compiler-and-linker-options>`__. |
| 77 |
However, the setup.cfg approach is easier. |