Skillversitas

Installation and Setup

OpenCV for Python installs as a single pip package with prebuilt wheels for every major platform - no compiler, no system libraries to chase. There are three variants and choosing the right one is the entire setup story: opencv-python for normal desktop work, opencv-contrib-python when you need the extra community modules, and opencv-python-headless for servers without a display.

Install

pip install opencv-python

# verify the install and the version
python -c "import cv2; print(cv2.__version__)"

# when you need contrib modules (SIFT in older versions, Saliency, etc.)
pip install opencv-contrib-python

# for servers, containers, and CI - no GUI dependency
pip install opencv-python-headless

Do not install more than one variant in the same environment - they share the cv2 name and will collide. If a project needs contrib modules, use opencv-contrib-python alone; it is a superset of the base package. The wheels bundle the native OpenCV libraries, so there is nothing else to install on a typical machine.

Import and Version Check

import cv2
import numpy as np

print(cv2.__version__)

# the build report: which native dependencies are linked
cv2.printBuildInformation() | head  # (in a terminal; prints the full report)
print(cv2.getBuildInformation().split("\n")[0:5])  # first lines: version, CMake, GCC

Conventions worth locking in now: import as cv2 (universal in the ecosystem), keep NumPy alongside it (OpenCV arrays are NumPy arrays), and check __version__ in requirements - a few functions moved between major versions, and pinning avoids surprises when the stack upgrades.

The Smoke Test

import cv2
import numpy as np

# build a synthetic image - no sample file needed
img = np.zeros((120, 160, 3), dtype="uint8")
img[:] = (60, 120, 200)                       # a flat blue-ish frame
cv2.rectangle(img, (30, 30), (130, 90), (0, 255, 0), 2)

# the classic first pipeline: read -> process -> write
cv2.imwrite("smoke.png", img)
back = cv2.imread("smoke.png")
print(back.shape, back.dtype)                 # (120, 160, 3) uint8

# a filter round-trip to prove the native engine works
blur = cv2.GaussianBlur(back, (5, 5), 0)
print("blur ok:", blur.shape == back.shape)
print("opencV smoke test passed")

Four things just ran: array creation with the exact OpenCV channel model (BGR, uint8), shape/dtype verification, an encode-decode round trip through the disk codecs, and a native C++ filter call. If this prints without error, the installation is honest - the Python bindings, the native libraries, and the image codecs are all working. Ten seconds of setup discipline beats a debugging session about missing DLLs or a silent GUI fallback.

The GUI Caveat

  • imshow and the window functions need a display backend - they work on desktop out of the box, but fail in a plain Linux server or CI runner.
  • On headless machines use opencv-python-headless and write results to files instead of displaying them.
  • On macOS the wheels bring their own HighGUI; on Linux they link the system GTK when available, which is why a stripped container can fail at imshow specifically while everything else works.

Summary

Install with pip install opencv-python (one of the three variants, never more than one), import as cv2, pin the version in requirements, and run the synthetic-image smoke test - create a BGR uint8 array, draw on it, write and re-read a PNG, and push it through a Gaussian blur. If the round trip and the filter both work, the engine is real. Remember the GUI caveat: display functions need a screen, and headless environments should use the headless build with file-based output.