A preview release of the Picamera2 library

We’re really pleased to announce the very first preview release of the Picamera2 Python library, the replacement for the Picamera library deprecated during the release of Bullseye back in November.

A Raspberry Pi 4 with the Raspberry Pi HQ Camera.

If you’ve used any of the Raspberry Pi cameras you’re probably familiar with Picamera, an excellent Python library designed to provide easy access to imaging capabilities on Raspberry Pi. But you might also know that, with our recent move to more open and standard Linux APIs, the Picamera library — built on top of a proprietary Broadcom camera stack — isn’t going to be supported in the future.

The original Picamera library was third-party software, developed by Dave Jones and not worked on by us here at Raspberry Pi. However, the library proved immensely popular with our users, so we’ve undertaken to provide a replacement. Imaginatively named Picamera2, the new library is being developed in-house here in Cambridge by Raspberry Pi, and will eventually be an officially supported package.

So today we’re announcing a first preview release of Picamera2.

One of the new Picamera2 example applications running on the Bullseye desktop.

What do we mean by a preview release?

By preview release, we mean something that’s very much a work in progress. It has quite a lot of functionality already that you can try, but there are still some important things missing, and in some cases things that are not quite working as well as we might like. It’s also highly likely, in fact pretty certain, that a number of aspects of the functionality and of the public-facing APIs are going to change before we release the library more generally.

Among the features supported in today’s release:

  • You can configure and start the camera, and receive multiple image streams.
  • Picamera2 supports preview windows, either standalone or embedded within Qt applications.
  • You can query and set camera parameters.
  • You can capture full-resolution still images as JPEGs or PNGs.
  • Or you can capture them as numpy arrays for feeding to image analysis applications.

However, there is a rather obvious missing feature, which is that we’re still working on video recording using the Raspberry Pi’s hardware h.264 encoder. If you want to record video from Python using Picamera2 that’s something you can’t do today, and it probably remains “a few weeks” away.

If you’re interested in taking a look at what is a very early release of the new Picamera2 library we’d be interested to hear how folks get on with it, and whether there is any useful functionality that we’ve overlooked, or that could be made easier to use.

What can I do with it?

The best explanation might be just to show a few snippets of code! The first example starts a preview window and then does a full-resolution JPEG capture:

from qt_gl_preview import *
from picamera2 import *
import time

picam2 = Picamera2()
preview = QtGlPreview(picam2)

preview_config = picam2.preview_configuration()
capture_config = picam2.still_configuration()


picam2.switch_mode_and_capture_file(capture_config, "capture.jpg")

In this next example, we capture preview images and pass them to OpenCV to see if it can detect any faces in the image using a Haar cascade.

Our own Alasdair Allan with a green box drawn around his head!

It then draws detection boxes around any faces it finds and again displays the image in a preview window:


import cv2

from null_preview import *
from picamera2 import *

# Grab images as numpy arrays and leave everything else to OpenCV.

face_detector = cv2.CascadeClassifier("/usr/local/lib/python3.9/dist-packages/cv2/data/haarcascade_frontalface_default.xml")

picam2 = Picamera2()
preview = NullPreview(picam2)
picam2.configure(picam2.preview_configuration(main={"size": (640, 480)}))

while True:
    im = picam2.capture_array()

    grey = cv2.cvtColor(im, cv2.COLOR_BGR2GRAY)
    faces = face_detector.detectMultiScale(grey, 1.1, 5)

    for (x, y, w, h) in faces:
        cv2.rectangle(im, (x, y), (x + w, y + h), (0, 255, 0))

    cv2.imshow("Camera", im)

Beyond these two, we’ve created over twenty small example scripts to act as an informal tutorial, and to help folks explore what functionality is available in this preview release. In due course, and once the rate at which things are changing settles down, we’ll work to expand this information and add some more formal documentation and tutorials.

How do I try it?

You can find the preview version of Picamera2 on Github, and the repository README.md gives full installation instructions.

However, installation is not for the faint of heart. As Picamera2 is built on top of libcamera’s own Python bindings which are currently in a prototype phase, for the time being installation involves checking out a special Raspberry Pi-curated version of the libcamera library, and compiling it manually.

There is no way to install the preview version of Picamera2 via a package manager, or via other mechanisms. For now, you’ll have to build it from the source. If you don’t feel comfortable doing that, it’s probably better that you wait for a more stable version.

However, if you do take a look at the preview, once you’ve had a chance to look through the example code and maybe have a play with the library yourself, we’d very much appreciate hearing any useful suggestions. I’ll keep an eye on this page, and on discussions over on the camera forum so that I can try and answer any questions you might have around today’s release.


Michael Horne avatar

Is it roughly compatible with picamera? I.e. have efforts been made to keep the commands/functions roughly similar? It doesn’t look like it to me, but then I haven’t been through it all yet.

Gordon Hollingworth avatar

Unfortunately, that was not possible, there are significant amounts of functionality that just isn’t available in the libcamera interface that was previously available in the closed source firmware and this makes it very difficult.

Claude Pageau avatar

I am very disappointed in the non compatibility. A lot of good projects will be left behind. Some developers may not want to modify/rewrite their code. Only other option is for users to use legacy image or a work around. All ready had to deal with users expecting things to work on Bullseye.

Supra avatar

How do I install Picamera2 library?

Alasdair Allan avatar

Installation instructions can be found in the Github repo’s README.md file. However, installation is pretty complex at this time as this release is intended for early adopters to take the new library for a spin and give feedback. This isn’t a general release.

Jon avatar

Installation instructions here, on GitHub.


W. H. Heydt avatar

Not precisely germane to the software to test…but I’d like to see the particulars on the tripod in the top image… Source, item name, and price.

Brian avatar

The tripod is an off-brand version of this Manfrotto mini tripod. As it was summarily nicked off of an engineer’s desk, I’m unclear as to the exact model!


Joakim Eriksson avatar

Is it possible to integrate a camera connected to a raspberry pi with Home Assistant using this new library?

David Plowman avatar

Hi, I’m afraid I don’t know anything about “Home Assistant”. Maybe having a look at some of the examples would help you to understand what the API looks like? Please feel free to post again if you have any questions after that.

dedSyn4ps3 avatar

If you are looking for a way to integrate camera feeds into HassIO using Raspberry Pi’s, check out motionEyeOS! Super easy to install on multiple Pi versions. There is a main integration you can install via the Home Assistant dashboard, which allows you to add the various ‘client’ cameras on your network using their IP address (you can set a static address once you log into the client via it’s web interface).

Jon Witts avatar

Is it possible to get a preview on the CLI only as it was with the previous PiCamera library?

David Plowman avatar

Hi, I’m not quite sure what you mean by “a preview on the CLI”. Do you mean a preview window using a Python script without any kind of GUI code? Or do you mean a preview window when you’re not running X Windows at all? In any case, the answer to both questions is “yes”. But please post back if I haven’t answered the right question.

Jon Witts avatar

Yes to both really! I used to often use the old PiCamera library on the Lite OS with no X Server running at all…

Junxiao Shi avatar

My Picamera code makes use of GPU-based image processing, like this:

camera.video_denoise = False
camera.image_effect = ‘blur’

Would these be possible with Picamera2?

David Plowman avatar

Hi, the image effects from the old proprietary stack are no longer available through libcamera, and would need re-implementing on the ARM cores. For example, I’m sure OpenCV will have a blur function, maybe that would work?

Alasdair Allan avatar

Yup! OpenCV has several blur options,

  • Simple blurring with cv2.blur
  • Weighted Gaussian blurring with cv2.GaussianBlur
  • Median filtering with cv2.medianBlur
  • Bilateral blurring with cv2.bilateralFilter
Ton van Overbeek avatar

Does this work when legacy camera support is enabled? I guess not.
Related: does it require the KMS driver or does it also work with the FKMS driver?

David Plowman avatar

Picamera2 won’t work with the legacy stack, you would of course have to go back to the original Picamera library.
I would expect Picamera2 to work with the FKMS driver, though I haven’t tried it.

Geoff Gartside avatar

Will the full version implement motion-JPEG recording, and if so will the Quality setting be functional (unlike PiCamera)?

Geoff Gartside avatar

Will motion-jpeg still be available and, if so, will the quality of the compressed images be adjustable (this did not function with picamera)?

David Plowman avatar

We will be supporting mjpeg, though we’ll be doing h264 first. Mjpeg will be implemented using software encode, so you’ll be able to adjust whatever you want. You can already do mjpeg, though it’s a little less automatic for the moment – try the mjpeg streaming example.

Geoff Gartside avatar

Thanks David.
I see what you mean from the example but it’s a bit testing for my skills just yet!. I’m using the mjpeg format to record a 2018 x 1512 pi frame to selectively crop down to 1080 for output. H264 is not a great edit codec so it’s good news to know that mjpeg will be there.

Secret-chest avatar

Thanks! I just needed to start up the camera and take photos.

Secret-chest avatar

I have tried to install it, but it says “module libcamera has no attribute Transform”

David Plowman avatar

Perhaps you could post an issue on the picamera2 GitHub repository? Please be sure to include: the type of Pi, what image you are using (include the output of “uname -a” and “vcgencmd version”), also the exact command you used that didn’t work and all the console output.

Jason avatar

Thanks for your hard work on this! Just went through the rather complex install on a fresh 64 bit Rpi OS image… tried a few of the examples, and …. it works! With OpenCV 4.5.5 and latest Numpy installed by pip3. So far so good – now to see to converting my old picamera code. Hope the combination of 64bit os and libcamera can speed things up a bit. :)

Realizator avatar

I know libcamera-apps already have two cameras support (early stage, but it works) for CM-based solutions. Any plans to add this feature to Picamera2 soon?

David Plowman avatar

Hi, certainly we plan to include that and given that libcamera already supports it to a certain extent, you might find that you can already get somewhere by opening two separate processes running Picamera2, passing each instance a different camera number. But I haven’t tried anything like that myself yet, and it’ll be at least a little while before I get round to it as there’s quite a lot else to do as well!

Stewart F. avatar

How well does this work with CSI connected devices, the HDMI-to-CSI boards specifically?
Projects such as Dicaffeine, Raspberry Ninja, and others doing video streaming, will be extremely negatively impacted if such devices are left out.

Lars Rasmussen avatar

Hello David & Alasdair,
I really don’t want to sound negative here. The Raspberry org has done fantastic work and enabled many like myself to create embedded solutions and devices that are used all over the world. But… I do wonder if you are aware of the problems we as developers face due to this “misstep” by releasing Bullseye without a working (compatible) Python camera interface. I myself have 3 projects on hold waiting for some kind of solution and from what I can read we cannot expect the same level of functionality from the open source stack. Was it really necessary to go open source before you were ready ? Also I worry that people like Claude Pageau and Stewart F. are not getting any answers from you. To me their questions and comments are valid. Finally what are we talking about here ETA wise… weeks, months or maybe a year ?
Best regards

JL avatar

Any update on when PyCamera 2 will be in production release?

Phil H avatar

Hi David,
Any eta on a preview refresh that includes h264 video?

Mitch Bogart avatar

Yes. That’s quite a library, including blurring. I see the old picamera supports Sony MIPI Sony IMX477. Do think the new picamera2 would support a new 48MP IMX586?
Tnx – Mitch

Comments are closed