Raspberry Pi Camera Setup and Troubleshooting: rpicam and Picamera2

Many Raspberry Pi camera tutorials still use raspivid, raspistill, or the original Picamera library. Current Raspberry Pi OS uses the rpicam-* tools and Picamera2 instead. This guide shows the supported workflow for Camera Module 3, HQ Camera, Global Shutter Camera, and AI Camera, then fixes the problems that most often prevent a camera from working.

Choose the right camera workflow

Goal	Recommended tool
Confirm that the camera works	rpicam-hello
Capture a still image or video from the shell	rpicam-jpeg, rpicam-still, rpicam-vid
Build a Python application	Picamera2
Run on-camera AI inference	AI Camera with IMX500 post-processing
Run a larger AI model on Pi 5	AI HAT+/Hailo or the Hailo-8L guide

The examples assume current 64-bit Raspberry Pi OS. Update first so firmware, camera drivers, and applications are compatible:

sudo apt update
sudo apt full-upgrade -y
sudo reboot

1. Connect the camera correctly

Power the Raspberry Pi off before attaching the ribbon cable. Raspberry Pi 5 uses smaller 22-pin camera connectors, while many earlier boards use 15-pin connectors; use the correct cable or adapter.

Insert the cable fully and make sure it is connected to a port labelled CSI, not DSI. The connectors look similar, but only CSI is intended for camera input. Then power the Pi on.

2. Test with rpicam-apps

Raspberry Pi OS includes rpicam-apps by default. If the commands are missing, install them:

sudo apt install -y rpicam-apps

On a desktop installation, launch a five-second preview:

rpicam-hello -t 5000

On Raspberry Pi OS Lite or another headless environment, capture a JPEG instead:

rpicam-jpeg -o test.jpg
file test.jpg

Record a ten-second H.264 clip:

rpicam-vid -t 10000 -o test.h264

If these commands work, the hardware and basic camera stack are ready. Do not enable the old raspi-config camera option simply because an older tutorial says to do so; modern Raspberry Pi OS detects supported cameras automatically.

3. Capture dependable images and video

For a still image with a short warm-up period:

rpicam-jpeg -t 2000 --width 1920 --height 1080 -o image.jpg

For continuous segmented recording, useful for a simple event recorder:

mkdir -p recordings
rpicam-vid -t 60000 --segment 10000 -o recordings/clip%03d.h264

Use reliable storage for long recordings. If the Pi 5 boots from NVMe, the NVMe boot and PCIe guide helps validate the storage setup.

4. Use Picamera2 from Python

Install distribution packages rather than pip for Picamera2. They include versions matched to the Raspberry Pi camera stack.

sudo apt install -y python3-picamera2 python3-opencv

Create capture.py:

from picamera2 import Picamera2

camera = Picamera2()
camera.configure(camera.create_still_configuration(main={"size": (1920, 1080)}))
camera.start()
camera.capture_file("image.jpg")
camera.stop()

Run it with the system Python:

python3 capture.py

If the application needs a virtual environment, create it with access to system packages so it can use the APT-provided camera bindings:

python3 -m venv --system-site-packages .venv
source .venv/bin/activate
python capture.py

5. Run object detection with Raspberry Pi AI Camera

The AI Camera runs compatible neural-network inference on its IMX500 sensor. This reduces the work performed by the Pi and differs from sending frames to a Hailo NPU or TensorFlow model.

After the normal camera test succeeds, run the supplied object-detection profile:

rpicam-hello -t 0s \
  --post-process-file /usr/share/rpi-camera-assets/imx500_mobilenet_ssd.json \
  --viewfinder-width 1920 --viewfinder-height 1080 --framerate 30

To record detection overlays instead of showing a preview:

rpicam-vid -t 10000 -o detected.h264 \
  --post-process-file /usr/share/rpi-camera-assets/imx500_mobilenet_ssd.json

For a smart-camera project that sends alerts, see the YOLOv8 AI security camera guide.

Troubleshooting

raspivid: command not found

That command belongs to the unsupported legacy stack. Replace it with rpicam-vid; replace raspistill with rpicam-jpeg or rpicam-still. Migrate Python code from the original Picamera library to Picamera2.

rpicam-hello reports no cameras available

Work through these checks in order:

rpicam-hello --list-cameras
uname -a
vcgencmd get_camera 2>/dev/null || true
dmesg | grep -Ei 'imx|camera|csi|unicam'

1. Shut down the Pi and reseat the ribbon cable.
2. Check that the cable is in CSI and its contacts face the correct direction.
3. Update the OS and reboot.
4. Try another known-good ribbon cable or camera.

Preview window is blank or fails over remote desktop

Run rpicam-jpeg -o test.jpg first to separate camera capture from desktop-preview issues. On a headless server, use file output rather than expecting a GUI window. For browser desktop access, configure Raspberry Pi Connect on a Wayland desktop.

The image has a strong colour cast

Remove protective film from a new lens, check lighting, and let auto white balance settle. NoIR modules need their matching tuning file; for example, on Raspberry Pi 5 an IMX219 NoIR camera can use:

rpicam-hello --tuning-file /usr/share/libcamera/ipa/rpi/pisp/imx219_noir.json

The Pi reboots or capture is unreliable

Use an official or adequately rated power supply, especially with Pi 5, SSDs, AI accelerators, or USB disks attached. Check for voltage warnings with:

vcgencmd get_throttled

Next steps

Once basic capture is reliable, choose one focused project: time-lapse recording, a motion-triggered archive, plant monitoring, or local object detection. Start with the smallest test that proves camera and storage work, then add AI acceleration and networking one layer at a time.