Setting Up a CSI Camera and Its Driver on Linux

The short answer

A CSI camera on Linux needs two drivers. One is a sensor driver for the specific image sensor on the module. The other is a receiver driver for the camera interface built into your board's processor. The kernel does not discover a CSI sensor on its own. The board's device tree has to declare it, usually through an overlay. Once both drivers load, the camera shows up as Video4Linux (V4L2) and media controller devices. On many platforms, libcamera then turns the sensor's raw output into a usable image.

• Power the board off, then seat the ribbon cable in the CSI connector with the orientation your board's documentation shows.
• Use a kernel that includes a driver for your sensor and for your board's CSI receiver. Vendor OS images usually include drivers for officially supported modules.
• Enable the sensor in the device tree, through auto-detection or an overlay for that sensor.
• Reboot and check the kernel log for messages from the sensor driver.
• Confirm the device with V4L2 and libcamera listing tools, then take a test capture before you configure any other application.

How a CSI camera reaches userspace

CSI here means MIPI CSI-2, a serial interface that carries image data from the sensor to the processor over one or more data lanes. A separate I2C bus carries control traffic: the driver uses it to identify the sensor and set modes, exposure and gain. A USB webcam works differently. It handles its own processing and uses the generic UVC driver. A CSI module depends on drivers written for that exact sensor and for that exact board.

The kernel represents the hardware as a pipeline: the sensor, the CSI-2 receiver, and on many systems an image signal processor (ISP). The media controller framework exposes this chain as a media device, typically /dev/mediaN, with sub-devices for individual blocks and one or more /dev/videoN capture nodes. Most CSI sensors output raw Bayer data. That data still needs demosaicing, white balance and exposure control before it looks like a normal picture. libcamera configures the pipeline and runs these image-processing algorithms on platforms it supports.

Some details change between kernels, distributions and board generations. These include driver names, which sensors are supported in the mainline kernel, overlay names and the location of boot configuration files. Treat any specific name as something to confirm against your platform's current documentation.

Enabling and verifying the camera

On Raspberry Pi OS, the firmware reads a camera_auto_detect setting in config.txt. When it is enabled, official camera modules are detected and the matching overlay is applied automatically. For a third-party or unrecognised module, the usual approach is to turn auto-detection off and add a dtoverlay line naming the sensor driver. The location of config.txt differs between OS releases, so check which file your release actually uses. Other boards, such as NVIDIA Jetson, Rockchip or NXP-based systems, use their own overlay mechanisms or configuration tools. Supported sensors and connector ports also vary by board.

After rebooting, read the kernel log with dmesg and search for the sensor name. A successful probe usually logs the sensor being found. I2C errors or a failed chip ID read usually point to the cable, the connector port or the wrong overlay, not to software in userspace.

• v4l2-ctl --list-devices (from the v4l-utils package) lists video nodes and the drivers behind them.
• media-ctl -p prints the media pipeline, so you can confirm the sensor entity is linked to the receiver.
• cam -l from the libcamera tools lists the cameras libcamera can use.
• On Raspberry Pi OS, rpicam-hello --list-cameras lists detected cameras and their sensor modes. Older releases named this tool libcamera-hello.

Before setting up another program, run a short capture with the libcamera tools. If the test capture works but another application does not, the problem is how that application reaches the camera, not the driver. Applications written for plain V4L2 may see only raw formats or no usable device. libcamera offers a V4L2 compatibility layer, and on recent desktops PipeWire can expose libcamera cameras to browsers and video-call apps. Support for both depends on your distribution and application versions.

For video calls, two more checks apply. The browser or app must have camera permission, and the selected camera in its settings must be the CSI device, not another input. Test tools may write captures to disk. Check where a tool saves files and remove test images you do not want to keep.

Limits and related questions

Driver availability is the main constraint. Not every sensor has a mainline kernel driver. Some third-party modules rely on vendor drivers that are tied to particular kernel versions, so an OS upgrade can break them. A camera that works with one board's ISP and libcamera pipeline may still be unsupported on another board.

The hardware has its own limits. Connect or disconnect the ribbon cable only with the board powered off. Connector sizes differ: for example, the Raspberry Pi 5 and Zero boards use a narrower 22-pin connector than the 15-pin one on many camera modules, so they need an adapter cable. Long or damaged cables can cause unreliable detection.

The sensor modes the driver exposes, together with the number of CSI-2 lanes in use, determine the available resolutions and frame rates. Selecting a higher resolution can lower the maximum frame rate. In poor lighting, automatic exposure may lengthen exposure time, which can also reduce the effective frame rate. Better lighting usually helps more than changing driver settings.

Ordinary desktop PCs usually have no CSI connector, so the Linux CSI camera question mostly concerns single-board computers and embedded boards. Some recent laptops connect their built-in camera over MIPI CSI instead of USB. On Linux, these cameras depend on platform-specific drivers and libcamera support, which can still be limited depending on the hardware and distribution version.