One of the new features in the latest set of Raspberry Pi OS images is, for the first time, pre-installed beta release versions of the new Picamera2 Python camera library.

For those not familiar with Picamera2, it’s the replacement for the old PiCamera Python library. PiCamera proved hugely popular with users, as it provided a much more approachable way of accessing the Raspberry Pi’s camera system. But as we’ve discussed on this blog a number of times (An open source camera stack for Raspberry Pi, Bullseye camera system and A preview release of the Picamera2 library), we’re moving away from proprietary and closed camera APIs (Broadcom’s in this case) to an open framework based on libcamera.

Picamera2 features

There’s a lot to dig into here, but headline features of Picamera2 include:

• A command-driven paradigm where you can type Picamera2 commands straight into a Python interpreter, or into your Python scripts
  
• Preview windows that use OpenGL acceleration for hardware-assisted rendering or DRM/KMS for efficient rendering when X Windows is not running
  
• Additional support for embedding ready-made Picamera2 widgets into your Qt applications
  
• Native use of numpy, making it very natural to use with OpenCV, TensorFlow and other Python libraries.
  
• All the source code is available on the Picamera2 GitHub page, or as part of the libcamera project
  
• Supports all official Raspberry Pi cameras, and a number of third party cameras too

And there are many more features such as video encoding and recording (with customisable output objects), the ability to record audio and video together, drawing display overlays on top of the camera images and so forth. To find out more please consult the numerous example scripts and apps, and also consult our Picamera2 user manual.

Installation and upgrading

Picamera2 is supported only on recent Bullseye images. It is not supported on Buster or earlier images, nor on Raspberry Pi OS Legacy; nor is it supported on Bullseye images where the legacy camera stack has been re-enabled. All those users should continue with the old PiCamera library.

On the latest Bullseye images, Picamera2 is of course already installed, and this is what we would recommend to most people.

Users can update their installation either as part of a general system update, or by entering:

sudo apt install -y python3-picamera2

Raspberry Pi OS

Raspberry Pi OS users will find that Picamera2 is installed with the full set of dependencies, including Qt and OpenGL. All the advertised features of Picamera2 will work as expected.

If you are using an earlier version of Bullseye on which Picamera2 is not installed, the above command will also install it.

Raspberry Pi OS Lite

Raspberry Pi OS Lite will by default come installed with Picamera2, but without the Qt and OpenGL dependencies. The reason is that lower-powered Pi devices, typically using Raspberry Pi OS Lite, will find it more difficult to run X Windows based applications, or to render through the X Windows display stack. 

Picamera2 will still work normally, with the exception of features that rely on Qt or X Windows. You can still use DRM/KMS to display preview images, however. Should you want to install the missing dependencies anyway, please use:

sudo apt install -y python3-pyqt5 python3-opengl

If you are using an earlier version of Bullseye on which Picamera2 is not installed, the command to install it without the extra Qt and OpenGL dependencies is

sudo apt install -y python3-picamera2 –-no-install-recommends

Users who have previously installed Picamera2 via pip

Some users may have installed Picamera2 previously using pip. If you are in this category you may need to uninstall Picamera2 (pip3 uninstall picamera2) before reinstalling with apt (or you can continue to update for yourself using pip). If you are not comfortable managing your installation in this way it may be easier to start over with the newly updated OS images.

Future plans

Picamera2 was developed here at Raspberry Pi, and we will be continuing to maintain and improve it in the future. For now, our principal plans include:

• Fixing bugs and problems that our users uncover. Please report any such issues on our GitHub page.
• Enhancing the documentation and examples, including inline source code documentation.
• Answering questions and helping people out in the Camera forum and the GitHub page.

There is ongoing development too, of course. One such example is improving the frame-by-frame control of exposure and gain, but as this is now a beta release we will in all cases be trying very hard to avoid breaking any existing public APIs.

How do I try Picamera2?

Once you’ve flashed the new OS image onto your SD card, you’re ready to go. You may find some of the example scripts helpful. You could download and run them like this:

git clone https://github.com/raspberrypi/picamera2.git

python picamera2/examples/preview.py

Tips

Here are a few things to look out for or to check if you experience any difficulties:

• Users of Raspberry Pi 3 or earlier devices will need to re-enable Glamor (if they have not done so previously) in order to use any X Windows/OpenGL preview functionality.
  
• libcamera can be quite “chatty” in the console window. If this bothers you, type export LIBCAMERA_LOG_LEVELS=*:3 before running Python (or put it in your .bashrc or equivalent).
  
• Picamera2, and in fact libcamera in general on the Pi, uses a particular type of Linux system memory known as CMA memory. Being a system resource, this can come under pressure in certain use cases. If you see error messages about failing to allocate buffers then you may need more of it – please consult section 8.3 of the manual for more information.
  
• Please be aware that if you have downloaded versions of libcamera or Picamera2 from a third party, then we probably won’t be able to help you and you will need to go to that third party for support.

If you have any other problems or questions, please feel free to ask below or to join the discussion on the Camera forum!