How to Add a Webcam to OctoPrint: USB and Pi Camera

Here is how to add a webcam to OctoPrint on a Raspberry Pi: plug in a USB webcam (or connect a Pi camera ribbon), boot OctoPi, and the camera is detected automatically and streamed on port 8080. Then open Settings, Webcam & Timelapse and confirm the stream URL is /webcam/?action=stream. Pi Camera Module 3 owners need the “new camera stack” OctoPi image.

Everything past that point is about picking the right image, getting a resolution the host can sustain, and fixing the black box that shows up when one of those is wrong.

Which OctoPi image do you need for your camera?

Use the stable OctoPi image for USB webcams and older Pi cameras (v1, v2), and the “new camera stack” image for the Pi Camera Module 3, newer Arducams, or anything else that only works through libcamera. Both are offered in Raspberry Pi Imager. Choose before you flash, because switching stacks later means reflashing.

OctoPi shipped mjpg-streamer for a decade, until the Camera Module 3 arrived requiring libcamera, which the old stack cannot drive. The replacement, built on camera-streamer, supports every current Pi camera module, libcamera sensors and USB webcams, and adds hotplug, multi-camera support, H.264 streaming, WebRTC, and separate snapshot and video resolutions.

The catch: the author of the companion WebRTC plugin states that “the new camera stack is not fully stable yet”. For a USB webcam with no need for WebRTC, the stable image is the lower-friction path.

Host choice matters too. OctoPrint’s download page recommends a Pi 3B, 3B+, 4B or Zero 2 and warns of print artifacts and slow loading on weaker boards, “especially when adding a webcam.” Our Raspberry Pi setup guide covers power supply and storage, both of which a camera stresses.

USB webcam or Raspberry Pi camera?

Pick a USB webcam if you want flexible mounting and a long cable run; pick a Pi camera if you want the cheapest, smallest module and do not mind a ribbon cable. Functionally both end up as the same stream in OctoPrint. The differences are physical placement, cable routing, and which software stack drives them.

Things that trip people up with Pi cameras:

• Connector size. The Raspberry Pi camera documentation notes that the Pi 5, all Zero models and Compute Module IO boards use the mini 22-pin connector and need a Standard-Mini cable. The Pi 4 and earlier use the standard 15-pin connector with a Standard-Standard cable.
• Autofocus. The Camera Module 3 (Sony IMX708, 4608 x 2592) has powered autofocus, which tends to hunt as the toolhead crosses the frame. The default libcamera config enables continuous autofocus; more on locking it below.
• Ribbon routing. Keep flat flex cables off anything that moves, which rules out a Y-carriage mount on a bed-slinger.

USB webcams draw power from the Pi’s USB bus, so an undersized supply can show up as dropped frames or a serial disconnect. If prints stall at random points after adding a camera, check the supply first, then read the mid-print disconnect guide.

Setting up a webcam on the stable (mjpg-streamer) image

On the stable image the camera is detected on boot and OctoPrint is preconfigured to use it. The OctoPi README lists the stream as http://octopi.local/webcam/?action=stream, or directly at http://octopi.local:8080/?action=stream. If that URL shows video in a browser tab, the camera side works and any remaining problem is in OctoPrint’s settings.

To change resolution or frame rate, edit /boot/octopi.txt. You can do it over SSH or by mounting the SD card’s boot partition on another computer. The relevant line is camera_usb_options, which defaults to "-r 640x480 -f 10": 640x480 at 10 fps. For a first-layer check camera, -r 1280x720 -f 10 is a reasonable next step on a Pi 4, but only if your webcam actually offers that mode. Verify with:

v4l2-ctl --list-formats-ext -d /dev/video0

Some webcams reject the -f frame-rate flag entirely. The same octopi.txt file carries an additional_brokenfps_usb_devices list for these, with several (including the Logitech C170) already preconfigured. If your camera produces no stream at all, add its vendor:product ID from lsusb to that list.

After editing, restart the streamer with sudo systemctl restart webcamd, or reboot.

Setting up a webcam on the new camera stack

On the camera-streamer image, each camera gets its own config file and its own port. The stack’s USB default config sets:

The libcamera config splits video and snapshot resolution, which is the practical win here: a 720p live view that stays light on bandwidth, and 1080p stills for timelapses. Per the config comments, the camera on port 8080 is treated as the primary camera.

To stop a Camera Module 3 hunting focus, replace the OPTIONS autofocus line with a fixed manual focus set for your mounting distance.

Adding a second USB camera uses the bundled script:

sudo add-usb-camera bedcam

With no port given, the script picks the next free port starting at 8080, prompts you to select a device from /dev/v4l/by-id/, writes usb-bedcam.conf to /etc/camera-streamer.conf.d/, and restarts that camera. Using the by-id path matters: /dev/video0 numbering can change between boots when two cameras are attached.

For WebRTC in the OctoPrint UI, install the Camera-Streamer Control plugin. It needs OctoPrint 1.9.0 or later, falls back to MJPEG if WebRTC fails, and its author recommends a Pi 4 for 1080p at 30 fps and warns that a Pi Zero may struggle at high resolutions. If WebRTC stutters, the plugin page’s advice is to drop resolution and frame rate.

Configuring the webcam in OctoPrint’s settings

Since OctoPrint 1.9.0, webcam support lives in a bundled plugin called Classic Webcam, which handles MJPG, HLS, beta WebRTC and snapshots. The settings are still under Settings, Webcam & Timelapse. Fill in:

• Stream URL: /webcam/?action=stream. A relative URL means it works both on the LAN and through a reverse proxy.
• Snapshot URL: http://127.0.0.1:8080/?action=snapshot. This one is fetched by the OctoPrint server itself, so it should point at localhost, not the Pi’s LAN address. The mjpg-streamer HTTP output docs document both the ?action=stream and ?action=snapshot endpoints on port 8080.
• Path to FFMPEG: required for timelapse rendering. The config.yaml reference notes timelapse support is disabled if either the snapshot URL or the ffmpeg path is unset.
• Flip horizontally, flip vertically, rotate 90°: fix orientation here rather than physically remounting the camera.

If the Control tab shows an empty box while the stream URL works in a browser, check in the Plugin Manager that Classic Webcam is enabled; as a bundled plugin it cannot be uninstalled but can be disabled. OctoPrint 1.9.0 also added camera switching in the Control tab when more than one webcam plugin provides a view.

Why is my OctoPrint webcam stream black or not showing?

A black or missing stream almost always means one of four things: the streamer service is not running, the requested resolution or format is not one the camera supports, the camera is not detected at all, or OctoPrint’s stream URL is wrong. Work through them in that order, testing the raw port 8080 URL in a browser first to split camera problems from OctoPrint problems.

1. Service not running. Check journalctl -u webcamd on the stable image, or journalctl -u camera-streamer* on the new stack (the command OctoPrint’s maintainer asks for in bug reports).
2. Unsupported mode. Compare your configured resolution against v4l2-ctl --list-formats-ext. Many USB webcams only reach higher frame rates in MJPG and fall back to low rates in YUYV.
3. Not detected. Run lsusb for USB cameras. For a Pi camera, a reversed or half-seated ribbon is the usual cause; check contact orientation at both ends.
4. Wrong image. A Camera Module 3 on the stable image will not stream. Reflash with the new camera stack image.

A stream that works on the LAN but not remotely is a network question, not a camera one. Do not forward port 8080 to the internet: an open mjpg-streamer port is an unauthenticated window into your room. Use one of the options in the OctoPrint remote access guide instead.

Placement and lighting

Aim the camera at the nozzle from roughly bed height with the full bed in frame, and add dedicated lighting, because auto-exposure on cheap sensors pumps when room light changes and ruins timelapses. Once the stream is stable, see our list of OctoPrint plugins worth installing for which camera-based plugins justify the CPU load.

FAQ

can you use any usb webcam with octoprint

Most UVC-compliant USB webcams work with OctoPrint on OctoPi, since both the mjpg-streamer and camera-streamer stacks drive standard Video4Linux devices. The practical limits are the resolutions and formats the camera exposes, which you can list with v4l2-ctl, and some models that reject frame-rate settings and need adding to the broken-fps list.

does octoprint support the raspberry pi camera module 3

Yes, but only on the OctoPi “new camera stack” image built on camera-streamer. The Camera Module 3 requires libcamera, which the older mjpg-streamer stack in the stable image cannot drive. Flash the new camera stack image from Raspberry Pi Imager, and consider disabling continuous autofocus so the focus does not hunt mid-print.

what is the octoprint webcam stream url

The default OctoPrint stream URL on OctoPi is /webcam/?action=stream, and the snapshot URL is http://127.0.0.1:8080/?action=snapshot. The stream is also reachable directly at port 8080 on the Pi. Set both under Settings, Webcam & Timelapse, and keep the snapshot URL pointed at localhost because the server fetches it itself.

can octoprint use two webcams at once

Yes. The new camera stack supports multiple cameras, each on its own port starting at 8080, added with the add-usb-camera script. Since OctoPrint 1.9.0 the Control tab can switch between cameras when more than one webcam plugin provides a view, so a second camera needs its own webcam provider plugin.

Related across the network

• Best Webcam for Remote Work Meetings: Key Specs — homedeskguide.com
• Klipper Hardware Requirements: SBC, MCU, and Sensors — klipperlab.com