Build a Raspberry Pi Camera Motion Detector with Python

Learn how to configure a Raspberry Pi camera, compare frames with Python, detect visual motion, and save timestamped photos while managing compatibility, thresholds, and storage.

A Raspberry Pi Camera Module can act as a basic visual motion detector. The program repeatedly captures images, compares a new frame with an earlier reference frame, and saves a photograph when the scene changes enough to exceed a configured threshold.

This is image-based motion detection. It is different from a PIR sensor, which detects changes in infrared radiation from warm objects. A camera detector can respond to people, animals, vehicles, shadows, and lighting changes because all of these can alter the image.

For this project, the expected result is simple: when someone or something moves through the camera's view, the Python program records a still image in a dedicated directory.

Prerequisites: You should be comfortable using the Raspberry Pi terminal, installing packages with apt, creating a Python file, and working with directories and file paths. See Terminal in Raspbian and Set Up Raspberry Pi if you need preparation help.

Required hardware

A Raspberry Pi with a supported camera connector or a compatible USB camera.
A Raspberry Pi Camera Module and suitable ribbon cable when using the original CSI camera workflow.
A reliable power supply. Unstable power can cause camera failures or unexpected restarts.
Network access or a display and keyboard for initial setup. Remote administration can be done with SSH after the system is configured.
Storage space for captured JPEG files and the operating system.

Choose a stable camera position aimed at a doorway, hallway, or other clearly defined area. Avoid pointing directly at windows, moving foliage, television screens, or reflective surfaces because they commonly create false triggers.

Connect and validate the camera

Connect the ribbon camera

Turn the Raspberry Pi off before connecting or disconnecting a ribbon cable. Insert the cable into the camera connector with the contacts facing the correct direction for the board and connector. Lock the connector tab, then check that the cable is straight and fully seated at both ends.

A USB camera normally needs only a suitable USB port, but it still must be supported by the operating system and accessible to the selected Python library.

Match the camera software to Raspberry Pi OS

Raspberry Pi camera software has changed over time. Older installations commonly used the legacy firmware camera system and the Picamera Python library. Current Raspberry Pi OS releases commonly use libcamera, the modern Linux camera software stack, with Picamera2 as a Python interface.

These interfaces are not interchangeable. A script written for legacy Picamera may fail even though the camera is physically connected correctly. Select the library, commands, and examples that match the operating system and camera stack installed on your Pi.

On some older systems, the camera had to be enabled through configuration tools. The relevant setup may be described in Enable Camera in raspi-config. On current systems, camera configuration is generally managed by the libcamera stack rather than the old enable-camera switch.

Test still capture first

Do not begin with motion detection. First prove that the camera can take an ordinary still image.

rpicam-still -o test.jpg

Some systems provide libcamera-still instead of rpicam-still. Use the command available on the device. Open test.jpg or inspect it from another computer. A successful still capture confirms much more than a software version check: it verifies the cable, camera recognition, permissions, and basic camera operation.

Prepare the operating system and Python packages

Refresh the package lists and install normal operating-system updates before adding project dependencies.

sudo apt update
sudo apt full-upgrade

Use the update guidance in Update Raspbian when working with an older installation. Keep a backup before major system changes.

Current Picamera2 and Pillow approach

For a compatible modern Raspberry Pi OS installation, a typical package preparation command is:

sudo apt update && sudo apt install python3-picamera2 python3-pil

Pillow is the actively used Python image-processing library in this workflow. It provides functionality historically associated with PIL, including opening, converting, resizing, comparing, and saving images.

Legacy package names

Older Python 2-era Raspberry Pi environments used package names such as:

sudo apt-get install python-picamera
sudo apt-get install python-imaging-tk

python-picamera refers to the legacy Picamera library, while python-imaging-tk is an old package associated with the Python Imaging Library workflow. These packages may not exist on a current Raspberry Pi OS release. Do not force a legacy installation onto a modern system; use a Picamera2 and Pillow-based implementation when the installed camera stack requires it.

sudo rpi-update is also a legacy firmware-testing command, not a routine update recommendation:

sudo rpi-update

Prefer normal package and operating-system updates. Use firmware testing tools only for a specific, supported reason and with an appropriate recovery plan.

Legacy and current camera choices

System or camera stack — Python interface — Typical image-processing option — Compatibility notes

Legacy firmware camera stack — Picamera — PIL or older imaging packages — Intended for older Raspberry Pi OS and Python environments; old examples may require Python 2.

Current libcamera stack — Picamera2 — Pillow — Common choice on current Raspberry Pi OS; use current camera configuration and API conventions.

USB camera through Linux video support — A camera library compatible with the device, often through a video capture interface — Pillow or another Python image library — Camera controls and supported resolutions depend on the USB device and driver.

Design the Python motion detector

Create a source file whose name ends in .py, such as motion_detector.py. Preserve indentation exactly when editing Python. Python uses indentation to define blocks, so mixing tabs and spaces or removing indentation can cause a syntax error or change the program's behavior.

The exact camera calls differ between Picamera and Picamera2. The following structure is the important part of the detector, not a drop-in replacement for every camera stack:

Initialize the camera. Select a still-image or preview configuration, set a useful resolution, and start the camera according to the library's API.
Create a baseline frame. Capture an initial image representing the scene before motion occurs. A baseline frame is the earlier reference image used for comparison.
Wait briefly. A frame delay prevents the loop from consuming unnecessary CPU and gives the scene time to change.
Capture a current frame. Take another image using the same size and format as the baseline.
Normalize the images. Convert both images to a comparable format. Grayscale conversion removes color information, and reduced-resolution images require less processing.
Compare the frames. Use image differencing to identify changed pixels or calculate a numerical difference score.
Apply a threshold. If the score is greater than the configured motion threshold, treat the change as an event.
Save a still image. Create a timestamped filename in the capture directory and save the current or newly captured full-quality frame.
Update the baseline deliberately. Depending on the design, keep a stable reference or replace it after an event. A continuously updated baseline adapts to gradual changes but can eventually absorb a stationary object.
Stop safely. Catch an interrupt such as Ctrl+C, stop the camera, close any resources, and exit cleanly.

Pseudocode for the control flow looks like this:

start camera
create capture directory
baseline = capture frame

repeat until interrupted:
    wait for comparison interval
    current = capture frame
    comparison_a = normalize(baseline)
    comparison_b = normalize(current)
    score = compare(comparison_a, comparison_b)

    if score exceeds motion threshold:
        save timestamped photograph
        optionally wait for cooldown

    update baseline according to the chosen strategy

stop camera and release resources

Important configurable values

Setting — What it controls — Effect of increasing it — Suggested testing approach

Resolution — Size of captured and compared images — More detail, CPU use, memory use, and storage — Begin around 640x480 for a doorway and increase only if small distant movement is missed.

Comparison interval — Seconds between comparisons — Fewer comparisons and lower CPU use, but fast movement may be missed — Try 0.5 seconds, then shorten it for quick events.

Motion threshold — Amount of image change required for an event — Fewer false positives but more missed motion — Calibrate in an empty scene, then test a person crossing the view.

Output directory — Where captured images are stored — No direct detection effect — Use a dedicated directory such as /home/pi/motion-captures.

Filename pattern — Naming scheme for saved files — Better sorting and event identification — Include date and time, for example motion-YYYYMMDD-HHMMSS.jpg.

Cooldown — Minimum time between saved events — Reduces duplicate images — Add a short delay after a trigger when one passage produces many frames.

An illustrative configuration is:

output_directory = /home/pi/motion-captures
filename_pattern = motion-%Y%m%d-%H%M%S.jpg
resolution = 640x480
comparison_interval_seconds = 0.5
motion_threshold = calibrate for the scene

The values must be represented using the syntax of the selected Python camera and image libraries. The filename pattern should be converted into a real timestamp by the program rather than saved literally with percent signs.

How image differencing detects motion

A frame is one image captured from a camera stream. The detector compares a baseline frame with a current frame. If the camera view is unchanged, most corresponding pixels should be similar. If a person enters the view, many pixels change.

With image differencing, the program subtracts or otherwise compares corresponding pixel values. It can count pixels whose difference is above a small per-pixel limit, add the differences into a score, or calculate the proportion of changed pixels. The event threshold then determines whether that result represents meaningful motion.

Grayscale conversion is common because it reduces three color channels to one intensity channel. Comparing a smaller image is another useful optimization. These changes reduce CPU and memory consumption, but they can also remove detail. The saved photograph can still use a larger resolution than the comparison frames if the implementation supports separate analysis and capture sizes.

Why a static scene can trigger

Changing sunlight or indoor lighting alters many pixels.
Auto-exposure changes the brightness of the entire frame.
Shadows move even when the main subject does not.
Sensor noise is more noticeable in low light.
Screen flicker, reflections, rain, traffic, or moving foliage changes the image.
Camera vibration changes the position of every object between frames.

A false positive is an unwanted motion event, such as one caused by a shadow rather than a person. A threshold that is too low is sensitive but noisy. A threshold that is too high suppresses noise but may miss a person, especially when the subject is distant or has low contrast. Threshold tuning is therefore a balance between false triggers and missed events.

Save and run the program

Save the file in a known directory, for example your home directory or a project directory. Make the capture directory before running, or have the program create it if it does not exist.

mkdir -p /home/pi/motion-captures
cd /home/pi/motion-detector
python3 motion_detector.py

The command commonly used on current systems is python3. The topic's generic form is:

python FILENAME

Replace FILENAME with the actual file name and use the interpreter required by the script. Watch the terminal for startup messages, comparison scores, trigger messages, and saved paths. Stop the program with Ctrl+C; safe cleanup should release the camera before the process exits.

Optional executable launch

A shebang is the first line of an executable script and identifies its interpreter. If the file has a suitable shebang, you can grant execute permission:

chmod +x motion_detector.py
./motion_detector.py

chmod changes file permissions. Execute permission is optional when launching with python3 motion_detector.py; it is needed only when starting the file directly with ./motion_detector.py.

Locate saved captures

ls -lh /home/pi/motion-captures

Timestamped names sort naturally and make it easier to identify when events occurred. A typical directory might contain files such as motion-20260818-143012.jpg and motion-20260818-143529.jpg.

Practical tests and calibration

Basic doorway monitor

Aim the camera at a doorway using a moderate resolution. Start the detector with a timestamped output folder. Leave the area empty, then walk through the frame. Confirm that at least one still image is saved and that its timestamp matches the event.

Threshold calibration

Run the detector in an empty room.
Observe whether ordinary lighting changes or camera noise create events.
Increase the threshold until normal idle conditions no longer trigger frequent captures.
Walk through the scene at different distances and speeds.
Lower the threshold gradually if real movement is missed.
Consider requiring motion in multiple consecutive comparisons or adding a cooldown.

Low-light test

Compare daylight, ordinary indoor lighting, and nighttime conditions. Low light often increases noise, while auto-exposure and shadows can produce large frame differences. If the detector becomes unreliable, improve illumination, reduce the comparison resolution, reposition the camera, or adjust the threshold for that lighting condition.

Storage, privacy, and security

Use a dedicated capture directory rather than mixing event images with system files. JPEG images consume storage quickly when saved continuously. Add a retention policy that removes or archives files older than a chosen age, or rotate captures when the directory reaches a size limit.

Monitor free disk space with:

df -h

A full filesystem can prevent new images from being saved and may cause broader system problems. A storage-conscious design saves only detected events, uses a cooldown, and periodically deletes old images.

Do not monitor people without considering consent, privacy expectations, and local surveillance laws. Shared spaces, neighbors, visitors, and public areas may have additional legal requirements. Protect the Pi with a strong password, restrict remote access, and avoid exposing camera feeds or captured images directly to the internet. Guidance on remote access is available in Enable SSH in Raspbian and Access Raspbian Remotely.

Common troubleshooting

Symptom — Likely cause — Recommended correction

Camera cannot be opened or no image is captured — Loose or reversed cable, unrecognized camera, incompatible legacy API, or another application using the device — Reseat the cable, run a standalone still capture, select a library matching the camera stack, and close other camera applications.

Legacy package cannot be found — The system no longer provides Python 2-era package names, package lists are stale, or the system uses libcamera — Refresh package lists and use compatible Python 3 packages such as Picamera2 and Pillow when appropriate.

Indentation or syntax error — Mixed tabs and spaces, missing indentation, or an unsupported Python version — Use an editor that displays indentation, keep each nested block consistent, and run the required interpreter.

Images save constantly with nobody present — Threshold too low, auto-exposure, sunlight, shadows, flicker, noise, or moving scenery — Raise the threshold, reduce unstable areas in the frame, improve placement, and add a cooldown or consecutive-event requirement.

Movement occurs but no image is saved — Threshold too high, comparison interval too long, subject too small, or low contrast — Lower the threshold gradually, compare more frequently, improve framing or illumination, and increase useful resolution.

Pi runs slowly or becomes unresponsive — Excessive resolution or capture frequency, full-size comparisons, or a full storage device — Compare reduced or grayscale frames, lower the rate, save fewer images, and implement retention management.

Exam-relevant points

A camera motion detector identifies visual changes between frames; it does not directly detect infrared radiation like a PIR sensor.
The baseline frame is the reference image, and the current frame is the later image being tested.
Image differencing produces a change measurement; the threshold decides whether that measurement counts as motion.
Lower thresholds increase sensitivity and false positives. Higher thresholds reduce false positives but can miss real movement.
Grayscale and reduced-resolution comparisons reduce processing requirements.
Picamera is a legacy interface, while Picamera2 is commonly used with the modern libcamera stack.
chmod +x is required for direct execution only; it is unnecessary when the script is started with python3 filename.py.
Safe cleanup should stop the camera and release resources when the program is interrupted.

Next steps

Once still capture and frame comparison work reliably, useful extensions include sending an alert after an event, running the detector automatically with a service manager, adding a PIR sensor to reduce camera processing, or creating a web interface. Test each extension separately and keep the camera stack and Python dependencies consistent.