Geographic Information Systems Stack Exchange is a question and answer site for cartographers, geographers and GIS professionals. It's 100% free, no registration required.

Sign up
Here's how it works:
  1. Anybody can ask a question
  2. Anybody can answer
  3. The best answers are voted up and rise to the top

I asked this question on Stack Overflow before I realised this site existed. As this site it more appropriate, I'll ask it here too.

I'm trying to install gdal from pip pip install gdal inside a virtual environment (Ubuntu). It fails because it cannot find cpl_port.h

extensions/gdal_wrap.cpp:2853:22: fatal error: cpl_port.h: No such file or directory
compilation terminated

However GDAL is installed correctly and the header file is located at /usr/include/gdal/cpl_port.h. Is there some environment variable for GDAL that needs to be set in order for pip to find the header files?

share|improve this question

12 Answers 12

selimnairb's answer is close but you wont have the headers unless you've installed libgdal-dev:

sudo apt-get install libgdal-dev

with that done,

export CPLUS_INCLUDE_PATH=/usr/include/gdal

export C_INCLUDE_PATH=/usr/include/gdal

and then

pip install GDAL

The compilation ran to completion and I have GDAL in my virtual env. Phew!

share|improve this answer
Seems to be the only solution that worked. – bozdoz Mar 25 '14 at 16:46
Tried this on another system, and I think the combination of this plus @nickves answer is what actually does it. – bozdoz Mar 31 '14 at 23:33
This worked for me. – jaranda Nov 26 '14 at 10:55
Very good. In case, installed version of GDAL in system and python package differs, it fails. The solution is to find version of GDAL in system and instruct pip to install relevant python package version. In my case (Ubuntu 14.04) both are 10.0, so it helped $ pip install GDAL==10.0 – Jan Vlcinsky Dec 3 '14 at 22:17

Τhe header files cannot be found for some reason. Maybe you you are operating inside a Virtual Enviroment or they are not where they should be for some reason. In any case you can specify the include dirs when installing gdal via pip.

first download python's gdal :

pip install --no-install GDAL

then specify where the headers are:

python build_ext --include-dirs=/usr/include/gdal/

then install it:

pip install --no-download GDAL

Here's another way to install gdal python:

$ sudo apt-add-repository ppa:ubuntugis/ubuntugis-unstable
$ sudo apt-get update
$ sudo apt-get install python-gdal

after that open IDLE:

from osgeo import gdal

and you're good to go!

share|improve this answer
Hi thanks for you answer but I really need a way to install via pip as I will be creating isolated environments using virtualenv during CI process. – kevin Jul 8 '12 at 22:26
what is the output when you run 'gdal-config --version' and 'gdal-config --libs' ? – nickves Jul 9 '12 at 9:40
GDAL v1.9.1. gdal-config --libs -> -L/usr/lib -lgdal – kevin Jul 9 '12 at 17:35
@nickves I am trying to install GDAL using virtualenvwrapper in Ubuntu, and when I try your first line: pip install --no-install GDAL, I get the error: __main__.gdal_config_error: [Errno 2] No such file or directory Any idea? – theJollySin Mar 23 '13 at 18:36
Yes, It seems that gdal bindings are trying to find gdal-confing within your virtualenv, and it fails because it's not there. A possible solution (I haven't test it!) is to create a symbolic link of your gdal-config to your virtualenv directory ( ls -s /path/to/gdal/gdal-config /path-to-virtualenvs/your-env/bin/gdal-config ). – nickves Mar 25 '13 at 18:50

Yes, doing the following before running PIP appears to work:

export CPLUS_INCLUDE_PATH=/usr/include/gdal

export C_INCLUDE_PATH=/usr/include/gdal

share|improve this answer

The problem with the pip installing gdal is that it only gets the bindings, not the entire library, so it can get tricky. One way to solve it is to use the pip command to download - but not install. Then you tweak the header location from the config file. Then you pip install that. meh.

I was having the same problem but realized that writing a fabric script to recompile gdal and generate the python bindings was going to take less time. You even get the benefit of filegdb with that. Go ahead and use tha gist I wrote or tweak it to your hearts content.

share|improve this answer

After following a subset of this advice, this is how I got the Python GDAL 1.11.0 (the solution should be version-independent, see below) install to work on Ubuntu 14.04 with pip:

Install dependencies:

sudo apt-get install libgdal-dev libgdal1h

pip install by passing along the include path (prefix with sudo for system-wide install) and instructing pip to install the version matching the system installed GDAL version:

pip install --global-option=build_ext --global-option="-I/usr/include/gdal" GDAL==`gdal-config --version`

share|improve this answer
The higher rated answers from selimnairb and Paul Whipp didn't work for me on Ubuntu 15.10 and this one did. – rhunwicks Nov 17 '15 at 10:34

Installing Python package gdal into virualenv on Linux

GDAL provides nice toolkit for GEO related operations. However, installing it to virtualenv on Linux is not trivial task.

This recipe describes, how to do that.


here I use lowercase gdal for Python package and upper case GDAL for general system wide library.


  • allow using osgeo libraries (installed via gdal Python package) into virtualenv
  • allow installing on Linux Ubuntu

Installation methods

There are multiple methods for installation. One requires compilation and takes few minutes more.

The other is using wheel package of pygdal package and is very quick. Anyway, to create the wheel package one needs to create it once and the creation includes the compilation step anyway.

About GDAL packages and versions

GDAL is general C(++) based library for GEO related calculations.

GDAL utilities can be installed system wide what makes shared libraries available, but does not install Python package itself.

GDAL comes in different versions and each Linux distribution may by default install different version.

Python package gdal requires compilation and is not trivial to install on Linux based systems as it expects few environmental variables to be set. This makes installation into virtualenv more difficult.

Each gdal version might assume different version of GDAL and will fail installing if expected version is not present in the system.

Python package pygdal is alternative to gdal, which installs exactly the same stuff as gdal, but does it in much more virtualenv friendly manner.

pygdal comes in versions reflecting related GDAL version. So having GDAL version 1.10.1 in the system you shall install pygdal version 1.10.1.

Python package gdal (as well as pygdal) uses root python package named osgeo and has set of submodules, one being osgeo.gdal.

If needed, other than default versions of GDAL can be installed and used. This is out of scope of this description.

Wheel packages can be cross-compiled, this is also out of scope.

Installing GDAL into system

As pygdal requires GDAL shared libraries to be present, we must install them first.

Assuming GDAL is not yet installed, calling gdal-config will complain and give you a hint how to follow up:

$ gdal-config --version
The program 'gdal-config' is currently not installed. You can install it by typing:
sudo apt-get install libgdal-dev

Follow the hint and install it:

$ sudo apt-get install libgdal-dev

Each distribution may use different version of GDAL. To find out which we use:

$ gdal-config --version

Now you know, GDAL is installed and the version is 1.10.1 (the version can vary).

Install pygdal from source package (requires compilation)

Currently pygdal is provided only in tar.gz package, which contains package sources and requires compilation.

Assuming, the version of GDAL is 1.10.1 and that our virtualenv is already activated:

$ pip install pygdal==1.10.1

It may take a while to complete, is it needs numpy, which may also require some compilation. Just wait.

Check, it is installed:

$ pip freeze|grep pygdal

From now on, you may use osgeo package in your Python code as you like in exactly the same manner as if you would install it by gdal Python package.

Creating wheel package for pygdal

Note, that wheel packages must be created for exactly the same architecture, namely must match:

  • CPU architecture
  • OS (Linux/Windows)

In our case, it must also match the version of GDAL installed.

Following steps can be done in virtualenv or not, as you like.

First, make sure, wheel package is installed:

$ pip install wheel

Assuming, you have GDAL installed and it has version 1.10.1:

$ pip wheel pygdal==

and wait, until it completes.

After this, you shall find subdirectory wheelhouse and it shall contain packages with extension `whl`:

$ ls wheelhouse

Install pygdal from wheel packages

Installation from wheel formatted packages is much faster (a second compared to minutes), as it does not require compilation.

Note, that directory with wheel packages can have any name, we will use just the name wheelhouse.

Activate virtualenv first.

Ensure, you have in wheelhouse directory both required wheel packages (for pygdal and numpy).

Ensure, GDAL is installed and the version matches version of pygdal.

Install pygdal from wheel package:

$ pip install pygdal== -f wheelhouse

The -f wheelhouse shall point to the directory with whl files.

There is no need to install numpy, it gets installed automatically.

share|improve this answer
this anwser builds on other great answers here, tries to give complete instructions for the details, where I got stuck and adds steps for using wheel package format for speeding up repeated installs into virtualenv. – Jan Vlcinsky Dec 4 '14 at 9:52

While a while later, this provides the include path without having to bail out of pip installation: One can set the include path using an environment variable.

Assuming the headers are in /usr/include/gdal, issue an

export CPLUS_INCLUDE_PATH=/usr/include/gdal

before running pip.

share|improve this answer
Using this, I get "extensions/gdalconst_wrap.c:2732:18: fatal error: gdal.h: No such file or directory" even though gdal.h is present in /usr/include/gdal – anand.trex May 26 '13 at 1:14
Does using C_INCLUDE_PATH instead/additionally helps=? – Crischan Jun 13 '13 at 11:34

After looking right and left for a solution, here is something that works for me on Ubuntu 14.04, even from within a virtualenv with no access to the system packages :

  • Install dependencies :

    sudo apt-get install libgdal-dev libgdal1h libgdal1-dev
  • Set the compiler flags :

    export CFLAGS=$(gdal-config --cflags)
  • Install the version corresponding to the system libraries (at the time of writing Ubuntu Trusty is using the 1.10 headers) :

    pip install GDAL==1.10.0
share|improve this answer

Now you can use virtualenv and setuptools friendly version of standard GDAL python bindings pygdal.

share|improve this answer

I was having similar problems on a Mac. This is how I resolved it:

Firstly, I set up a virtual Python 2.7 environment using virtualenv. The Python distribution was installed in a directory called 'env'.

I then used fink to install gdal

fink selfupdate
fink update-all
fink install gdal

I also installed gdal-dev but this may not have been required since it might have already been installed with gdal.

I checked the version installed using:

gdal-config --version

On my installation, it produced the result 1.11.1

The fink installation of gdal installed the cpl_port.h header file in /sw/include/gdal1. Check your own installation. I then entered:

export CPLUS_INCLUDE_PATH=/sw/include/gdal1
export C_INCLUDE_PATH=/sw/include/gdal1
env/bin/pip install pygdal==1.11.1

That seemed to work for me but I haven't tested installation yet.

share|improve this answer

To answer the virtualenv specific aspect of the question:

pip3 search gdal
GDAL                      - GDAL: Geospatial Data Abstraction Library
pygdal                    - Virtualenv and setuptools friendly version of
                            standard GDAL python bindings

Beware that pygdal may require a different version of GDAL, compared to what the GDAL package of python bindings requires.

Below is what I used to get it on recent versions of Fedora (20 and 23).

CPPFLAGS=-I/usr/include/gdal pip install gdal
share|improve this answer

Your Answer


By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.