Instalación de OpenCV con pip, conda y verificación

Instalación con pip en entorno virtual

OpenCV se distribuye como paquete Python a través de PyPI, lo que permite instalarlo con un solo comando pip. Existen cuatro variantes del paquete, cada una con un nivel diferente de funcionalidad:

• opencv-python: contiene los módulos principales (core, imgproc, video, calib3d, highgui, dnn). Suficiente para la mayoría de aplicaciones.
• opencv-contrib-python: incluye todos los módulos principales más los módulos contribuidos (xfeatures2d, aruco, text, ximgproc, etc.). Necesario para SIFT en OpenCV < 4.4, ArUco, y algoritmos experimentales.
• opencv-python-headless: igual que opencv-python pero sin soporte de interfaz gráfica (imshow). Ideal para servidores y contenedores Docker.
• opencv-contrib-python-headless: versión completa sin interfaz gráfica.

La forma recomendada de instalar OpenCV es dentro de un entorno virtual Python, lo que evita conflictos entre dependencias de distintos proyectos.

Crear y activar el entorno virtual

# Crear el entorno virtual (Python 3.10, 3.11 o 3.12 recomendado)
python -m venv entorno-opencv

# Activar en Windows (Command Prompt)
entorno-opencv\Scripts\activate

# Activar en Windows (PowerShell)
entorno-opencv\Scripts\Activate.ps1

# Activar en Linux / macOS
source entorno-opencv/bin/activate

Instalar opencv-python

# Versión estándar (módulos principales)
pip install opencv-python

# Versión con módulos contribuidos (SIFT, SURF, algoritmos extra)
pip install opencv-contrib-python

# Instalar junto a las dependencias habituales
pip install opencv-contrib-python numpy matplotlib

Nota: opencv-python y opencv-contrib-python son mutuamente excluyentes. No instales ambos en el mismo entorno.

Verificar la instalación

import cv2
import numpy as np

print(f"OpenCV versión: {cv2.__version__}")
print(f"NumPy versión: {np.__version__}")

# Crear una imagen de prueba (array NumPy)
imagen_prueba = np.zeros((100, 100, 3), dtype=np.uint8)
imagen_prueba[:] = (0, 120, 255)  # Color naranja en BGR

# Verificar que imwrite funciona
resultado = cv2.imwrite("prueba.png", imagen_prueba)
print(f"Imagen de prueba guardada: {resultado}")

# Verificar que imread funciona
img = cv2.imread("prueba.png")
print(f"Imagen leída: shape={img.shape}, dtype={img.dtype}")

Salida esperada:

OpenCV versión: 4.9.0
NumPy versión: 1.26.4
Imagen de prueba guardada: True
Imagen leída: shape=(100, 100, 3), dtype=uint8

Instalación con conda (Anaconda / Miniconda)

Si usas el ecosistema Anaconda, puedes instalar OpenCV desde el canal conda-forge:

# Crear un entorno conda específico para OpenCV
conda create -n entorno-opencv python=3.11

# Activar el entorno
conda activate entorno-opencv

# Instalar OpenCV desde conda-forge
conda install -c conda-forge opencv

# O instalar la versión completa con contrib
conda install -c conda-forge opencv libopencv py-opencv

La ventaja de conda es que gestiona automáticamente las dependencias del sistema (librerías de vídeo, codecs, etc.), lo que puede simplificar la instalación en entornos con restricciones.

# Verificar instalación conda
import cv2
print(cv2.__version__)

# Comprobar soporte de vídeo
cap = cv2.VideoCapture(0)
print(f"Cámara disponible: {cap.isOpened()}")
cap.release()

Paquetes opencv-python vs opencv-contrib-python

Es importante recordar que los cuatro paquetes de OpenCV (opencv-python, opencv-contrib-python y sus variantes headless) son mutuamente excluyentes: instalar dos de ellos en el mismo entorno provocará conflictos de importación. Si se necesita cambiar de uno a otro, primero hay que desinstalar el existente con pip uninstall opencv-python opencv-contrib-python antes de instalar el nuevo.

Para proyectos que van a usar algoritmos como SIFT (incluido en el módulo principal desde OpenCV 4.4), ArUco (módulo aruco), o algoritmos experimentales de procesamiento (ximgproc), se recomienda instalar directamente opencv-contrib-python desde el inicio para evitar tener que migrar más adelante.

Dependencias del sistema en Linux

En sistemas basados en Ubuntu/Debian, puede ser necesario instalar algunas dependencias del sistema antes de que OpenCV funcione correctamente con interfaces gráficas o codecs de vídeo:

# Dependencias de GTK para imshow
sudo apt-get update
sudo apt-get install -y libgtk-3-dev

# Codecs de vídeo
sudo apt-get install -y libavcodec-dev libavformat-dev libswscale-dev

# Herramientas V4L para webcam
sudo apt-get install -y v4l-utils

# Soporte para imágenes
sudo apt-get install -y libjpeg-dev libpng-dev libtiff-dev

Configuración con Jupyter Notebook

Jupyter Notebook es uno de los entornos más populares para trabajar con OpenCV, especialmente en contextos de aprendizaje y prototipado. Sin embargo, OpenCV no puede usar cv2.imshow() dentro de Jupyter porque requiere una ventana de escritorio del sistema operativo que el navegador web no proporciona. La alternativa estándar es utilizar Matplotlib con plt.imshow(), que renderiza las imágenes directamente en la celda de salida del notebook. Es importante recordar que Matplotlib espera imágenes en formato RGB, mientras que OpenCV trabaja en BGR, por lo que es necesario convertir con cv2.cvtColor(img, cv2.COLOR_BGR2RGB) antes de mostrar.

import cv2
import matplotlib.pyplot as plt

def mostrar_imagen(imagen, titulo="Imagen", convertir_rgb=True):
    """Función de utilidad para mostrar imágenes OpenCV en Jupyter."""
    if convertir_rgb and len(imagen.shape) == 3:
        imagen_mostrar = cv2.cvtColor(imagen, cv2.COLOR_BGR2RGB)
    else:
        imagen_mostrar = imagen

    plt.figure(figsize=(8, 6))
    if len(imagen_mostrar.shape) == 2:
        plt.imshow(imagen_mostrar, cmap="gray")
    else:
        plt.imshow(imagen_mostrar)
    plt.title(titulo)
    plt.axis("off")
    plt.show()

# Uso
img = cv2.imread("foto.jpg")
mostrar_imagen(img, "Mi primera imagen con OpenCV")

Información detallada de compilación

Para diagnosticar problemas o verificar qué características están disponibles:

import cv2

# Información completa de la compilación
info = cv2.getBuildInformation()
print(info)

# Verificar soporte específico
print("CUDA disponible:", cv2.cuda.getCudaEnabledDeviceCount() > 0)

# Verificar backends de vídeo disponibles
print("Backends VideoCapture disponibles:")
for backend in [cv2.CAP_ANY, cv2.CAP_V4L2, cv2.CAP_DSHOW, cv2.CAP_FFMPEG]:
    try:
        cap = cv2.VideoCapture(0, backend)
        if cap.isOpened():
            print(f"  Backend {backend}: disponible")
            cap.release()
    except:
        pass

Fichero requirements.txt de referencia

Para proyectos reproducibles, define las dependencias en un fichero requirements.txt:

opencv-contrib-python>=4.8.0
numpy>=1.24.0
matplotlib>=3.7.0

Instalar desde requirements.txt:

pip install -r requirements.txt

Con esta configuración tendrás un entorno listo para trabajar con OpenCV de forma profesional y reproducible.