Picamera2 beta release

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.

Picamera2 can detect and segment dogs with help from TensorFlow
Picamera2 can detect and segment dogs with help from TensorFlow

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

Typing Picamera2 commands into the Python interpreter
Typing Picamera2 commands into the Python interpreter


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!


petro avatar

Is it possible to run two cameras in parallel (not necessarily timesynced like needed for stereo vision) using the picamera2 beta? This feature was missing at some earlier stages where i tried the lib. Thanks!

David Plowman avatar

You should be able to run Picamera2 with dual cameras by running two separate Python processes. This does give you some ability to take simultaneous, if not precisely synchronised, captures. It’s the same restriction that we have generally with libcamera at the moment.

thagrol avatar

Am I the only ongetting a 404 error on the documentation link?

Nick avatar

The “documentation” link under “Future plans” is indeed broken, because it includes “-draft” in the URL. You can remove that manually, or follow the “manual” link in the final section of the article, “Tips” – it looks like the same documentation to me.

Ashley Whittaker avatar

Fixed it!

Aardappeltaart avatar

Does it run fine on a Zero?

David Plowman avatar

Hi, it will run on a Pi Zero but I would strongly advise using Raspberry Pi OS Lite without X-Windows if you want to display preview images. Trying to render at (for example) 30fps through the X-Windows display stack is not going to be a great experience – previews will be an order of magnitude better if you can avoid X-Windows and render through DRM/KMS (which Picamera2 will do automatically).

Depending on what camera you’re using (especially the higher megapixel ones like the HQ cam), you may find that you need to allocate more CMA memory (section 8.3 of the manual, as listed at the bottom of the article). It will rather depend on the use case – memory is of course not so plentiful on some of there platforms.

S George McVeigh avatar

Do you think there will be a GUI for Module3 Camera for novices like me ?

Appreciated. Best wishes

Arthur Dent avatar

I am running a remote Pi4 8G 64bit rpiOS , using venv for python3.9.2
Some observations: picamera2/examples/preview.py
You need to change ‘pyvenv.cfg’ to (true not false):
include-system-site-packages = true
or ‘from picamera2 import Picamera2, Preview’ fails.
If you are running the OS headless and try to throw the X, that is as far as you will get as the QT GUI complains and dies.
>>> picam2.start_preview(Preview.QTGL)
Exception in thread Thread-1:….

* Can I make a suggestion. Can you test on headless rpi’s? Most professional Unix/Linux people will almost always work on remote headless machines, logging in via ssh pi@machinename -Y and when they need/want a GUI, throw a X GUI back to their desktop PC/Mac/RPI. You designed an ideal remote I-o-t server, so people will use it that way. There are many other errors, but I won’t detail them, if you build a rpi headless with venv python and try running your examples you will see them yourselves.

This is not criticisms, its only bug reports. Thanks.

David Plowman avatar

Hi, thank you for reporting these. Could I ask you to report them on our Github page (https://github.com/raspberrypi/picamera2/issues), that way they can be logged and investigated. Thanks!

Comments are closed