How to Adjust Webcam Focus in OctoPrint

The short answer

OctoPrint has no focus control of its own. Its built-in webcam settings cover the stream address, snapshot address, image orientation and timelapse options. Focus belongs to the camera and to the software that streams its video to OctoPrint. To change focus, you work at that level. On a USB webcam, that usually means camera controls set from the command line or through a plugin. On a Raspberry Pi camera, it means the camera stack's autofocus settings or the physical lens.

If your image keeps drifting in and out of sharpness, the camera's continuous autofocus is "hunting." It searches for a focus point, loses it and searches again. The usual fix is to turn continuous autofocus off and lock focus at a fixed position that suits the distance between the camera and the print bed.

Which method applies to your camera

• USB webcam with autofocus: switch off continuous autofocus and set a manual focus value with camera controls (see the USB steps below).
• Raspberry Pi camera with autofocus: set the autofocus mode to manual and choose a lens position through the camera stack's controls.
• Fixed-focus camera, either USB or Pi: there are no software focus controls. The only adjustment is physical, and only if the lens is designed to turn.
• Not sure: list the camera's controls (step 2 below). If no focus-related entries appear, the camera does not expose focus to software.

Why autofocus hunts on a printer camera

Autofocus judges sharpness by looking for contrast in the image. A 3D printer is a hard scene for this. The print head and bed move constantly. Enclosures are often dim. Plain build plates and single-color filament offer little contrast to lock onto. The camera is often mounted close to the bed, which may be near the lens's minimum focusing distance. Each of these can make the camera refocus repeatedly. A fixed manual focus avoids the problem because the camera stops searching.

Before you start

• Confirm the camera works in OctoPrint at all. You should see a live image in the Control tab. Getting access to the camera and getting a usable stream are separate steps, and focus only matters once both work.
• Have shell access (SSH) to the machine running OctoPrint, such as a Raspberry Pi running OctoPi.
• Set up your normal printing lighting and put an object with fine detail on the bed, such as printed text or a part with sharp edges. This gives you something to judge focus against.
• Know which streaming software your setup uses. Older OctoPi images use mjpg-streamer. Newer ones use camera-streamer. Where you make settings permanent depends on this.

Adjusting focus on a USB webcam

Most USB webcams follow the UVC (USB Video Class) standard. On Linux, that means you can read and change their controls with the v4l2-ctl tool, which is part of the v4l-utils package. Installed this way, a webcam usually appears as a device such as /dev/video0. Your setup may use a different number.

Step 1: Find the camera's device name.

v4l2-ctl --list-devices

Success check: your webcam is listed with one or more device paths. If v4l2-ctl is not found, install v4l-utils with your system's package manager.

Step 2: List the camera's controls and look for focus entries.

v4l2-ctl -d /dev/video0 --list-ctrls

Look for an autofocus control and a manual focus control. Depending on the camera and Linux kernel version, the autofocus control is usually named focus_automatic_continuous or focus_auto. The manual control is usually focus_absolute. The output shows the minimum, maximum, step and current value for each control. Use these numbers from your own camera. No universal focus value exists, because the range varies from model to model.

Step 3: Turn off continuous autofocus. Use whichever control name your camera reported.

v4l2-ctl -d /dev/video0 --set-ctrl=focus_automatic_continuous=0
# or, on cameras/kernels that use the older name:
v4l2-ctl -d /dev/video0 --set-ctrl=focus_auto=0

Success check: watch the OctoPrint stream. The image should stop pulsing between sharp and soft. It may now be stuck out of focus, which the next step fixes. Many cameras ignore or reject manual focus changes until autofocus is off, so do this step first.

Step 4: Set a manual focus value within the range the camera reported, then watch the stream and adjust.

v4l2-ctl -d /dev/video0 --set-ctrl=focus_absolute=VALUE

Replace VALUE with a number from your camera's range. Try a few values, moving in the steps the camera listed, and refresh or watch the stream each time. Stop when the detail on your test object looks sharpest at the height where printing happens. On many cameras, a higher value focuses closer, but confirm this by watching the image instead of assuming it.

Success check: run the list-ctrls command again and confirm that autofocus shows as off and focus_absolute shows your chosen value. Then watch the stream for several minutes while the print head moves. Focus should stay put.

Making the USB focus setting survive a reboot

Settings applied with v4l2-ctl usually reset when the camera is unplugged, the computer reboots, or the streaming software reopens the camera. To keep them, apply them automatically at startup. Two common approaches:

• A startup command: run the same v4l2-ctl commands from a startup script or a scheduled task that runs at boot. Add a short delay so the camera is ready first, and run the commands after the streaming service has started so the streamer doesn't override them.
• The streamer's own configuration: some streaming setups accept camera options in their configuration files. Check the documentation for the version of mjpg-streamer or camera-streamer on your system before relying on this, because supported options differ between versions.

Success check: reboot the OctoPrint machine, open the stream, and run list-ctrls again. Your autofocus and focus values should match what you set, without any manual step.

If you would rather not use the command line, community OctoPrint plugins exist that expose webcam controls in the OctoPrint interface. Before installing one, read its description to confirm that it supports focus controls on your camera type and your streaming setup.

Adjusting focus on a Raspberry Pi camera

Raspberry Pi camera modules don't use the UVC controls described above. Newer OctoPi images drive them through libcamera, the Raspberry Pi camera software stack. On modules with autofocus, libcamera provides an autofocus mode control (AfMode) with manual, single-shot and continuous settings, plus a lens position control (LensPosition) for manual focus. Lens position is expressed in dioptres, the reciprocal of the focus distance in meters, where zero means infinity.

To stop hunting on an autofocus Pi camera, set the autofocus mode to manual and choose a lens position that makes the bed sharp. How you pass these controls depends on your streaming software and its version. Check the documentation for the camera-streamer build on your OctoPi image for the exact option syntax and the configuration file it reads at startup. That documentation wasn't available for this guide, so no exact command is given here.

Success check: after restarting the stream, the image should hold steady focus while the print head moves. It should still be sharp after a reboot.

Fixed-focus cameras: physical adjustment

If your camera lists no focus controls, its focus is set by the lens itself. Software can't change it. Some lenses, including those on certain Raspberry Pi camera modules and many low-cost USB cameras, can be turned to change focus. Others are glued in place or are not meant to be adjusted. Forcing a glued lens can damage the camera, and opening a housing may void a warranty. If the lens is designed to turn, rotate it in small increments while watching the live stream until the bed is sharp. A lens that won't move with gentle pressure should be left alone.

What these checks confirm, and what they don't

A steady, sharp stream after a reboot shows that focus is locked and that your settings persist. It does not show that the image will look good in every condition. Focus set under bright light can look softer in a dim enclosure, because the camera may lower the frame rate or add noise in low light. Check the stream under the lighting you'll actually print with. Also check one timelapse or snapshot image. Snapshots come from the same camera, but they travel through a separate snapshot address, so they're worth confirming separately.

If focus still won't hold

• Focus returns to auto after a while: something is reapplying camera defaults, often the streaming service restarting. Make sure your startup commands run after the streamer starts.
• Manual focus values have no visible effect: confirm that autofocus is actually off by checking list-ctrls, and that you're adjusting the same device the stream uses.
• The bed never gets fully sharp: the camera may be closer than its minimum focusing distance. Moving the camera farther from the bed is the practical fix.
• The image is sharp but grainy or smeared: this is usually a lighting or exposure problem, not focus. Adding steady light to the print area often helps more than further focus changes.

Gaps in this guide

No camera-specific measurements were available for this guide, so it gives no recommended focus values, distances or other numeric targets. Use the ranges your own camera reports and judge the result by eye on the live stream. Exact configuration syntax for the different versions of camera-streamer and mjpg-streamer was also not confirmed, so check the documentation for the version installed on your system.