1. Installation

1.1. Raspbian installation

If you are using the Raspbian distro, it is best to install picamera using the system’s package manager: apt. This will ensure that picamera is easy to keep up to date, and easy to remove should you wish to do so. It will also make picamera available for all users on the system. To install picamera using apt simply:

$ sudo apt-get update
$ sudo apt-get install python-picamera python3-picamera

To upgrade your installation when new releases are made you can simply use apt’s normal upgrade procedure:

$ sudo apt-get update
$ sudo apt-get upgrade

If you ever need to remove your installation:

$ sudo apt-get remove python-picamera python3-picamera

Note

If you are using a recent installation of Raspbian, you may find that the python-picamera package is already installed (it is included by default in recent versions).

1.2. Alternate distro installation

On distributions other than Raspbian, it is probably simplest to install system wide using Python’s pip tool:

$ sudo pip install picamera

If you wish to use the classes in the picamera.array module then specify the “array” option which will pull in numpy as a dependency (be warned that building numpy takes a long time on a Pi):

$ sudo pip install "picamera[array]"

To upgrade your installation when new releases are made:

$ sudo pip install -U picamera

If you ever need to remove your installation:

$ sudo pip uninstall picamera

1.3. Firmware upgrades

The behaviour of the Pi’s camera module is dictated by the Pi’s firmware. Over time, considerable work has gone into fixing bugs and extending the functionality of the Pi’s camera module through new firmware releases. Whilst the picamera library attempts to maintain backward compatibility with older Pi firmwares, it is only tested against the latest firmware at the time of release, and not all functionality may be available if you are running an older firmware. As an example, the annotate_text attribute relies on a recent firmware; older firmwares lacked the functionality.

You can determine the revision of your current firmware with the following command:

$ uname -a

The firmware revision is the number after the #:

Linux kermit 3.12.26+ #707 PREEMPT Sat Aug 30 17:39:19 BST 2014 armv6l GNU/Linux
                        /
                       /
  firmware revision --+

On Raspbian, the standard upgrade procedure should keep your firmware up to date:

$ sudo apt-get update
$ sudo apt-get upgrade

Warning

Previously, these documents have suggested using the rpi-update utility to update the Pi’s firmware; this is now discouraged. If you have previously used the rpi-update utility to update your firmware, you can switch back to using apt to manage it with the following commands:

$ sudo apt-get update
$ sudo apt-get install --reinstall libraspberrypi0 libraspberrypi-{bin,dev,doc} raspberrypi-bootloader
$ sudo rm /boot/.firmware_revision

You will need to reboot after doing so.

Note

Please note that the PiTFT screen (and similar GPIO-driven screens) requires a custom firmware for operation. This firmware lags behind the official firmware and at the time of writing lacks several features including long exposures and text overlays.

1.4. Development installation

If you wish to develop picamera itself, it is easiest to obtain the source by cloning the GitHub repository and then use the “develop” target of the Makefile which will install the package as a link to the cloned repository allowing in-place development (it also builds a tags file for use with vim/emacs with Exuberant’s ctags utility). The following example demonstrates this method within a virtual Python environment:

$ sudo apt-get install lsb-release build-essential git git-core \
    exuberant-ctags python-virtualenv python3-virtualenv python-dev \
    python3-dev libjpeg8-dev zlib1g-dev libav-tools \
    texlive-latex-recommended texlive-latex-extra texlive-fonts-recommended
$ virtualenv -p /usr/bin/python3 sandbox
$ source sandbox/bin/activate
(sandbox) $ git clone https://github.com/waveform80/picamera.git
(sandbox) $ cd picamera
(sandbox) $ make develop

To pull the latest changes from git into your clone and update your installation:

$ source sandbox/bin/activate
(sandbox) $ cd picamera
(sandbox) $ git pull
(sandbox) $ make develop

To remove your installation blow away the sandbox and the clone:

$ rm -fr ~/sandbox/ ~/picamera/

For anybody wishing to hack on the project, I would strongly recommend reading through the PiCamera class’ source, to get a handle on using the mmalobj layer. This is a layer introduced in picamera 1.11 to ease the usage of libmmal (the underlying library that picamera, raspistill, and raspivid all rely upon).

Beneath mmalobj is a ctypes translation of the libmmal headers but my hope is that most developers will never need to deal with this directly (thus, a working knowledge of C is hopefully no longer necessary to hack on picamera).

Various classes for specialized applications also exist (PiCameraCircularIO, PiBayerArray, etc.)

Even if you don’t feel up to hacking on the code, I’d love to hear suggestions from people of what you’d like the API to look like (even if the code itself isn’t particularly pythonic, the interface should be)!

1.5. Test suite

If you wish to run the picamera test suite, follow the instructions in Development installation above and then make the “test” target within the sandbox:

$ source sandbox/bin/activate
(sandbox) $ cd picamera
(sandbox) $ make test

Warning

The test suite takes a very long time to execute (at least 1 hour on an overclocked Pi 3). Depending on configuration, it can also lockup the camera requiring a reboot to reset, so ensure you are familiar with SSH or using alternate TTYs to access a command line in the event you need to reboot.