Debian Codegraph @

docs/install.rst

raw
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.