A pure Python interface for the camera module: meet picamera!

If you have a Raspberry Pi camera module, you’ve probably used raspistill and raspivid, which are command line tools for using the camera. Dave Jones, a Database Admin, software developer and SQL know-it-all based in Manchester has been working on an equivalent, feature complete implementation of these in Python. This means you can access the camera module directly from a Python script, without using os.system or executing a subprocess.

At Oggcamp I set up a big TV with a Pi and camera taped on top. I SSH’d in to the Pi from my laptop and entered commands in to iPython using picamera.

Speaking as an avid Pythonist, picamera’s implementation is beautiful and it really is a wonderful library to use. It works really well for demonstrations using the Pi camera, and for real world applications. Part of the appeal of the Raspberry Pi is that you can work on embedded electronics projects without needing to know low-level languages or have to program a microprocessor – instead you have the choice of a range of accessible high-level languages such as Python – and this is an extension of that kind of abstraction, which open up a world of possibilities to a wider diversity of makers.

Example usage:

import picamera
from time import sleep

camera = picamera.PiCamera()

camera.vflip = True
camera.hflip = True
camera.brightness = 60


Also you can do things like this:

for i in range(100):
    camera.brightness = i

and watch the preview flow through the brightness levels.

The library has many configurations – you can change the brightness, contrast, saturation, image effects, exposure modes and such, as well as optionally show a live preview of the camera’s view. You can capture single images and sequences of images as well as video streams.

Here’s a presentation of picamera Dave gave at Manchester Raspberry Jam XVI – where he demonstrates the basic usage of the module by typing commands in to a Python prompt on his laptop, with a monitor displaying the camera output (unfortunately out of shot in the video):

Dave’s wife Holly works in the Palaeontology department at Manchester University (Interesting fact: when Dave and Holly got married, they picked a new surname to take (Dave was previously a Hughes) – so Holly could become Dr. Jones, and he would become Davy Jones) where they regularly capture images from microscopes. Rather than mount a huge camera on top of a microscope, Dave suggested attaching the Pi’s camera module to the lens.

An early version of the crudely mounted Picroscope

He ended up writing a web app to support its use. This allows the user to control camera configuration settings through a web page, and capture photographs at the click of a button, as well as archive pictures taken in to a database along with metadata and extra information entered in a web form.

The web app showing pictures taken (smaller field of view due to temporary mounting setup)

Single view of image taken through the web app, with metadata fields

Picroscopy configuration settings

Dave gave another presentation at the Manchester Jam, this time demonstrating a simple version of a Python web app for such an application (please excuse the numerous technical hiccups):

As Dave says in the video:

This is where having a library is particularly useful. If we were doing this with, say, raspistill and raspivid, when you want to alter the brightness of your preview, you’d have to shut down the program, regenerate the command line, restart the program. Here we’re just saying “set a property”. This is why a library is better for an interactive application like this. There’s nothing wrong with raspistill and raspivid as far as they go, but they’re not ideal for building this sort of application. If you have interactivity, you want a library.

See more videos from the Manchester Jam: Jam #16 Videos.

picamera has been available in pypi since October (v0.5), so it’s already in the wild – but now it’s hit the v1.0 milestone Dave considered feature complete, it’s packaged in the Raspbian archives so you install with apt-get (remember to run apt-get update first):

apt-get install python-picamera


apt-get install python3-picamera

depending on your taste.

Dave also mentioned to me that this is by far the most popular project he’s ever published – and he’s been impressed by how brilliant the feedback has been from the Pi community. He’s had a great response on the forums, detailed bug reports provided by users and plenty of help from James Hughes, the author of raspistill, and from Alex Bradbury in getting it packaged for Raspbian.

See the source for picamera and the picroscopy web app on github. Thanks to Dave for his hard work in building this library. Enjoy!


JamesH avatar

Great job Dave!

Bantammenace avatar

What else does he have in his locker ?
Perhaps he can give some further examples of his monkeying around ?

I look forward to using this with my Pi Camera attached to my bird watching scope.

Dave Jones avatar

At the moment the only thing on github which I’ve used picamera for is the picroscopy project (which Ben linked to at the end of the post). However, the docs contain a fairly extensive “Recipes” section, and there’s been some interesting snippets of code in the the forum post (including a rudimentary bit of motion detection using numpy!).

Terry R avatar

Best of luck with the scope I have tried a PI camera on a Nikon ED80 with Swarovski camera adapter I use with a Samsung and Nikon Camera but Pi lens is so wide you just have to much black ring in the picture. If you get success I would love to hear about it. Terry

Michael Horne avatar

Brilliant stuff – no more tedious mucking about with os.system – thanks Dave!

RaspberryPiIvBeginners avatar

^^ What he said.

The Other Peter Green avatar

Minister: “If any of you can show just cause why they may not lawfully be married, speak now or…”

Short Round: “Hey, Dr. Jones, no time for love!”

Elbert avatar

Excellent work :D

azaden avatar

Great Job !!!

Don Michael avatar

Hey. good job. Can I use the same for USB Web Cams ? Or Is there any other pure python modules for accessing USB Web cams?

Dave Jones avatar

I’m afraid picamera’s purely focused on the Raspberry Pi’s camera (under the hood it uses libmmal, just like raspistill and raspivid so it’s similarly specific in the hardware it’ll handle). That said, there’s plenty of Python interfaces for dealing with USB webcams – OpenCV has an interface for dealing with them, and there are Python bindings for GStreamer (which is a bit more complex but allows you to build whole image processing pipelines).

meltwater avatar

Looks to be very useful.
Shall try this out as soon as I get a chance, was after something like this a few months ago (although may be useful still…).

Great work.

meltwater avatar

Q: Is the preview friendly with tkinter? i.e. is it possible to embed it within a tkinter frame/canvas?


Dave Jones avatar

I’m afraid not. The preview is written directly to the screen (there’s not much I can do about this I’m afraid; that’s just the way the camera’s preview system works). That said, you can configure the position and size of the preview so if you could react to window positioning and sizing events you could move the preview to within the window’s borders.

meltwater avatar

No problem, I half expected that to be the case. For my purpose a basic work around is fine.

Krishna avatar

I like the Microscope + Raspberry PI + Camera idea, the commercial ones starts at 200$.

If we can connect Motor controller and able to adjust the lens that will be awesome project.

Looks like the Microscope + Raspberry Pi Case has the option to add the camera module, wonder where can I get that one?


Dave Jones avatar

The case I’m using in the photo is the “Proto Armor for Raspberry Pi and Camera”. It’s rather expensive, but at the time it was the only case I could find that housed the Pi and the camera module, and provided a tripod attachment (which combined with a gorillapod makes it great for demonstrations). However, as can be seen from the images, it’s not that great for mounting on a microscope. For that I’m betting more on something like Dave Cox’s superb Picroscope mount. Unfortunately, as noted on that page, this’ll involve replacing the lens – thankfully Santa bought me a PiNoir this year, which’ll come in handy as a backup in case I trash my camera module!

yvonnezoe avatar

Does it able to do live streaming of the camera on a browser?

Dave Jones avatar

Not directly, no. The library basically produces the same output as raspivid (unsurprisingly: they both use libmmal under the hood), so the video output is a raw H.264 stream. That said, it should be possible to add the necessary headers / containers in code (not that I’m familiar enough with HLS or RTMP to suggest how to go about this!)

ian smith avatar

the raspberry pi becomes a bit difficult to handle when it has an HDMI cable attached. It’s much easier if it can be run headless.

What possibility is there for putting the image into an X window? This would allow the window to appear on a remote networked workstation

This would be particularly useful for using it with a telescope.



Dave Jones avatar

It *might* be possible to take a video feed from the camera and render it in an X window but it’d probably chew up quite a bit of CPU. The camera’s preview window, however, is rendered directly to the screen (it just overlays whatever’s there – there’s not much I can do about this; it’s just how the camera’s preview works). That said, you can control the position, size, and transparency of the window, so a crude workaround (suggested above) is to react to window position and sizing events and position the preview accordingly.

Bantammenace avatar

Logistically I cannot attach a monitor to the RPi. One thought I had was to attach a WHDI device to the HDMI port: something like the Nyrius ARIES™ Pro Wireless HD for Laptops NPCS550.
But before I spend money on that I want to see if Raspicam Remote can give me an adequate streaming preview on my smartphone (The video loop feature in Picamera will probably help me get over latency issues).
If I change the resolution of the Picamera Preview does this also change the resolution of the recorded image on the RPi? Ideally I want to be able to reduce the Preview resoution so that Raspicam Remote can handle the data but I want to record photos/video on the Pi at the highest resolution. Could the processing power of the smartphone (HTC Desire) also be a consideration I will need to make ?

JBeale avatar

The quickest way to get live streaming (at low-res) to a browser is RPi Cam Web Interface http://www.raspberrypi.org/phpBB3/viewtopic.php?f=43&t=63276 which could probably also be re-written using the Python library, if you wanted to.

Bob avatar

Wonderful job, many thanks!

Any possibility to preview to a different device? Specifically, Adafruit’s PiTFT display, which installs as /dev/fb1

Dave Jones avatar

Interesting question. I’ve got one of texy’s mini-tft touch-screen displays (which looks similar to the pitft and runs off the GPIO as well), but I must admit I haven’t had the opportunity to try out the camera preview on it yet (mostly because it requires custom firmwares, and I’ve been closely following the main firmware for all the camera fixes that’ve been landing).

However, I can say that the preview doesn’t care about the frame-buffer – I think I’m right in saying it just gets the GPU to render over its output. It’s certainly it’s possible to start the preview without anyone logged into the console at which point access to the frame-buffer would usually be limited to root, so I don’t think it’s involved at all.

All that leads me to suspect it won’t work, but I won’t know for certain until I give it a whirl!

james avatar

i runned the program and it says that


AttributeError: ‘module’ object has no attribute ‘Picamera’.

Can anyone please help me

Dave Jones avatar

You need picamera.PiCamera, not picamera.Picamera (note the capital C on the latter component)

ExploWare avatar

Also: Your OWN filename for your script should NOT be picamera.py ! :)
Python first tries to import a module from the current location… Thats what took me

Dave Jones avatar

This is interesting – I was just reading through the code for adafruit’s awesome little camera project (http://learn.adafruit.com/diy-wifi-raspberry-pi-touch-cam) where it appears they’re using a PiTFT touchscreen in the way you describe. However, having dug into the code they’re not using the preview functionality to render to the screen – instead they’re doing rapid video-port-based raw captures, and using pygame to render them. My guess is this is partially because preview may not work on the PiTFT, and partially because this allows them an easy way to render their user interface over the top. Still, it’s a great demonstration that the camera can be made to work with such a screen, and rapidly enough to be interactive.

liz avatar

Serendipitously, I hit the publish button on a post about that very project about ten seconds ago – check out http://www.raspberrypi.org/archives/5773!

Dave avatar

Good stuff. Did you have to modify the camera or microscope at all, eg. remove lens/eyepiece ?


Dave Jones avatar

The camera hasn’t been altered yet, but I’m anticipating the final version (whenever I get around to sorting out a proper mount) will almost certainly involve removal of the camera lens (in order to achieve a decent field of view). Thankfully I’ve now got a backup camera (in the form of a pinoir) so I’m less worried about trashing my camera module :)

Dave W avatar

Hi, great work!

Is it possible to take photos, triggered by an external hardware clock pin, and collate them as a video file at a set bit-rate?

I’m thinking something along the lines of stop-motion animation.


Dave Jones avatar

Absolutely – you can have it capture pictures in response to … well … whatever you can code (which given the Pi’s GPIO pins means just about anything!). The library itself provides no facilities for collating images into a video file, but ffmpeg will do that quite happily (see http://hamelot.co.uk/visualization/using-ffmpeg-to-convert-a-set-of-images-into-a-video/ for an example).

For long sequences, I’d recommend doing the video conversion step on something with a bit more ooomph than a Pi, unless you’re particularly patient!

Dave Jones avatar

Actually, I’ve just remembered, one of the early users of picamera had something like this in mind and posted me a link to his github project … let me see if I can dig it out …

(rummages in github’s starred list …)

Here we go: https://github.com/russb78/pi-mation

Dave W avatar

Thanks for that, very helpful!

Andy avatar

Being a python beginner, how can I find the bits that matter in picamera.PiCamera(), like camera.rotate – or is it camera.rot?
Forgive me, I did see a way somewhere to find these (some form of help command, but lost my notes).

As to the case, would a Pice be an easier fit to the microscope?

Dave Jones avatar

The API reference in the docs lists all the available properties and methods of the class.

Alternatively, if you want to interactively explore the library on the command line I’d highly recommend installing ipython (sudo apt-get install ipython) and using that instead of the regular python interpreter. The ipython interpreter adds tab-completion (which is great when you can’t remember whether it’s “rot” or “rotate”) and easier doc-querying (append ? to the property or method you want to view the docs for – you can do the same in the regular python interpreter by wrapping the method or property in a help() call, but the ipython way is much more intuitive once you’ve used it a couple of times).

Thanks for the mention of the Pice – I hadn’t seen that before, and it certainly looks like a nice camera-integrated case!

james avatar

when i typed”apt-get install python camera” it says that it could not open lock file/var/lib/dpkg/lock-open

please help.

Matt Hawkins avatar

Did you mean to type :

apt-get install python-picamera

ti laprimera avatar

You can’t install two things simultaneously.

Dave Jones avatar

You need this instead:

sudo apt-get install python-picamera

Firstly, you need “sudo” as you’re installing software which is a privileged operation (requires root privileges). Secondly you’d specified the two packages “python” (which is installed already) and “camera” (which probably doesn’t exist). Contrary to another comment on here you can installed two (or a hundred!) things in one command, but they do need to exist :)

Victor Guerra avatar

Thanks for an excellent piece of technology. An as i think, TECHNOLOGY is one of the very few thing that define human advancement.


Brickart avatar

Wonderful tool, many thanks!

But I have already found a bug:

capture(streamRGB, 'rgb')

works fine with Pythgon 2.7 but not with Python 3.2
After I had previously also been problems with Python 3 (import cv2; jpeg in tkinter …), this was crucial for me to switch completely to Python 2.

Dave Jones avatar

I can’t seem to reproduce this with picamera 1.2 on python 3.2 under Raspbian. If you’re still having the issue, please feel free to open an issue on the GitHub site – I tend to monitor that more closely than this particular blog post.

Ben avatar

Has anyone follow the instructions and successfully implemented this, I cannot get microscopy to work

Ben avatar

Keep getting .. Template not found: layout.pt

Dave Jones avatar

My apologies – I still haven’t found the time to properly document (or package, or even release) picroscopy. I’ll try and find the time to do something towards this in the next couple of weeks. If you do run into any issues, please feel free to file issues on the GitHub site for the project – I tend to monitor that more closely than I do this particular blog entry.


ahmed avatar

nice job its awesome. but i want this to work with switches,how can i use switches in Picamera, can you pleas let me know..
thank you

Dave Jones avatar

Hi Ahmed,

It’s pretty easy – assuming you can react to GPIO events (with something like the RPi.GPIO library) then you can have the camera do something in response to GPIO events too. Firstly, I’d try and get a simple “print” statement working in response to a GPIO event, and then just replace the “print” statement with a capture() call, for example.

This is probably something I ought to add to the recipes in the documentation for the next release…


bhoobalan avatar


can u just let me know how to disable auto white balance , what command is needed for that .
thank you.

Dave Jones avatar

Ahh, theoretically setting awb_mode to something other than ‘auto’ ought to do this, but it appears there are underlying firmware issues that mean this isn’t the case. Have a look at the following thread for more detail than you ever wanted regarding this issue:


Basically, it’s out of my hands at the moment (it’s a problem common to raspistill, raspivid, and picamera – or any camera client for that matter – we’ll just have to wait for a fix upstream).


Nino avatar

Hi Dave,
great job, it’s really awesome.
I’ve only a simple question, would be great if you have any suggestions:

I’m working on install PI on board a drone, with camera module managed with two axis servos, also connected to PI. I’m currently writing a python server socket that run on the PI side to control it, and should use also your picamera library to remote control image and video recording. What i’m trying to do is streaming the video preview in low quality on socket and eventually (on received command) record video in HD on PI local file.
From your point of view how could I address that? May it be possible?

Thanks Dave.

Dave Jones avatar

Hi Nino,

Release 1.3 introduced a new “splitter_port” parameter to start_recording which permits multiple video recordings to be performed simultaneously with different parameters (e.g. resize). That’s probably your best bet for the use-case you’ve described. Do feel free to e-mail me if you need further info on this – it’s a relatively complex area and I don’t tend to monitor this page terribly closely (given it’s a fairly old post!)


Sunbae Yim avatar

I want to that Raspberry Pi can do Real time streaming and Video recording at the same time.
My toy has it, and I control moving of toy using smart phone. It connected through WiFi.

Toy can do recording video in real time,
and I can see streaming video in real time using smart phone.

So, I’m studing Python Recipes of Picamera.
But I can not implement that Raspberry Pi can do streamig and recording at the same time.

Please commant and make recipe for [mjpeg-streamer] and recording at the same time for making my Toy.

If python of Picamera can be make that simutaneously Recording and Mjpeg-Streaming…

Please help me,

marcel avatar

Hi, I’m trying to set a shutter speed, but it keeps not working. Maybe someone has an idea/workaround for me…

File “/usr/lib/python2.7/dist-packages/picamera/camera.py”, line 1819, in _set_shutter_speed
prefix=”Failed to set shutter speed”)
File “/usr/lib/python2.7/dist-packages/picamera/exc.py”, line 112, in mmal_check
raise PiCameraMMALError(status, prefix)
picamera.exc.PiCameraMMALError: Failed to set shutter speed: Function not implemented

code snip looks like so:

camera = picamera.PiCamera();

camera.led = False
camera.awb_mode = weissabgleich
camera.meter_mode = meterMode
camera.iso = iso
camera.exposure_mode = exposureMode
camera.resolution = (bildw,bildh)

camera.shutter_speed = somevalue;

forgive me if I’m at the wrong place for asking

Paul O avatar

Loving the PiCamera interface to the Pi Camera.

I’m using the camera together with the PiFace Control & Display module, and I can trigger a video stream on demand from a button press (interrupt-driven), but stopping the video stream on demand is another matter. While the stream is active (camera.start_recording …) interrupt processing appears to be held (i.e. the interrupt is processed only after the call to camera.stop_recording).

I’d like to be able to designate a button to Stop the recording, but if interrupts are held then I have to poll the button status, forcing me to wake the process every half-second or so.

Is there a way to receive the button interrupt during the camera.wait_recording() call?

Monty Myers avatar

We have an application where we want simple button controls overlaying the full screen live video. This should be straightforward in Python if we could associate video with the parent frame. However, from reading your comments it sounds like your library directly overwrites whatever is on the screen – correct? This will make it difficult to have control buttons on top of the live video. Any comments or suggestions on how we could accomplish this?

Thanks so much for the great work!

Monty Myers
Austin, Texas

James Hughes avatar

Use dispmanx – search the forum for more information.

Nathan avatar

Hi When i run i have importerror: No module named picamera
i want to record video using picamera

please help me

James Hughes avatar

Please post any technical questions in the forum where they will be seen by more people who may be able to answer your question.

Nathan avatar

I want to record video on RPI using python picamera
I installed
sudo apt-get install python3-picamera

then start Python environment
following code
import time
import picamera
with picamera.PiCamera() as camera:

Then save and run script
run error show me as
IMPORT ERROR : no module named picamera
please help me

Comments are closed