Ora

How to install OpenCV in a virtual environment?

Published in OpenCV Virtual Environment Installation 6 mins read

To install OpenCV in a virtual environment, you typically follow a process that involves creating the environment, installing necessary system-level and Python dependencies, cloning the OpenCV repositories, building the library with CMake, compiling it, and then linking it to your virtual environment. This method offers greater control and allows for the inclusion of opencv_contrib modules.

Why Use a Virtual Environment for OpenCV?

Using a virtual environment for your OpenCV projects offers several significant advantages:

  • Isolation: Prevents conflicts between different project dependencies and system-wide packages.
  • Portability: Makes it easier to share your project and ensure others can replicate your environment.
  • Cleanliness: Keeps your global Python installation clean and free from project-specific packages.
  • Specific Versions: Allows you to install specific versions of OpenCV and its dependencies for each project without affecting others.

Detailed Steps to Build and Install OpenCV from Source

Building OpenCV from source in a virtual environment is a comprehensive approach that ensures all desired modules (including opencv_contrib) are included and optimized for your system.

Step 1: Create a Virtual Environment

First, create and activate a new virtual environment for your project. This isolates all subsequent installations.

# Navigate to your project directory or a suitable location
mkdir opencv_project
cd opencv_project

# Create a virtual environment named 'venv'
python3 -m venv venv

# Activate the virtual environment
# On Linux/macOS:
source venv/bin/activate

# On Windows (Command Prompt):
# venv\Scripts\activate.bat

# On Windows (PowerShell):
# venv\Scripts\Activate.ps1

Once activated, your terminal prompt will typically show (venv) indicating you are inside the virtual environment.

Step 2: Install Required Dependencies

Before building OpenCV, you need to install various system-level and Python dependencies.

System-Level Dependencies (Linux/macOS Example)

These packages provide build tools, image I/O support, GUI toolkits, and Python development headers. Adjust commands based on your operating system (e.g., apt-get for Debian/Ubuntu, brew for macOS, yum for Fedora/RHEL).

# Update package lists
sudo apt update
sudo apt upgrade

# Essential build tools and CMake
sudo apt install build-essential cmake git pkg-config

# Image I/O libraries
sudo apt install libjpeg-dev libpng-dev libtiff-dev

# Video I/O libraries
sudo apt install libavcodec-dev libavformat-dev libswscale-dev libv4l-dev libxvidcore-dev libx264-dev

# GTK for GUI features (e.g., imshow)
sudo apt install libgtk-3-dev

# Python development headers
sudo apt install python3-dev python3-pip

# Optional: GStreamer, FFMPEG for advanced media handling
# sudo apt install libgstreamer1.0-dev libgstreamer-plugins-base1.0-dev

Python Dependencies

Within your activated virtual environment, install numpy, pip, and wheel as they are essential for OpenCV's Python bindings and a smoother build process.

pip install numpy pip wheel

Step 3: Clone OpenCV and OpenCV Contrib Repositories

Clone the official OpenCV and opencv_contrib repositories from GitHub. It's often best to clone them into a dedicated src directory within your project.

mkdir src
cd src

# Clone OpenCV
git clone https://github.com/opencv/opencv.git

# Clone OpenCV Contrib (important for extra modules like SIFT, SURF, DNN, etc.)
git clone https://github.com/opencv/opencv_contrib.git

# Navigate back to your project root
cd ..

It's recommended to checkout a specific version (tag) for stability, e.g., git checkout 4.x.x in both opencv and opencv_contrib directories. Ensure both are on the same version.

Step 4: Build OpenCV with CMake

Create a build directory inside your src/opencv folder and use cmake to configure the build process. This step generates the Makefiles.

cd src/opencv
mkdir build
cd build

cmake -D CMAKE_BUILD_TYPE=RELEASE \
      -D CMAKE_INSTALL_PREFIX=$VIRTUAL_ENV \
      -D INSTALL_PYTHON_EXAMPLES=ON \
      -D INSTALL_C_EXAMPLES=OFF \
      -D OPENCV_ENABLE_NONFREE=ON \
      -D OPENCV_EXTRA_MODULES_PATH=../../opencv_contrib/modules \
      -D PYTHON_EXECUTABLE=$VIRTUAL_ENV/bin/python \
      -D BUILD_EXAMPLES=ON \
      -D WITH_GTK=ON \
      -D BUILD_opencv_python3=ON \
      -D BUILD_opencv_python2=OFF \
      -D BUILD_NEW_PYTHON_SUPPORT=ON \
      -D PYTHON3_NUMPY_PATH=$VIRTUAL_ENV/lib/python3.x/site-packages/numpy/core/include \
      -D PYTHON3_PACKAGES_PATH=$VIRTUAL_ENV/lib/python3.x/site-packages \
      -D PYTHON3_INCLUDE_DIR=$(python3 -c "from distutils.sysconfig import get_python_inc; print(get_python_inc())") \
      -D PYTHON3_LIBRARY=$(python3 -c "import distutils.sysconfig as sysconfig; print(sysconfig.get_config_var('LIBDIR'))")/libpython3.x.so \
      ..

Key cmake Flags Explained:

  • -D CMAKE_BUILD_TYPE=RELEASE: Builds an optimized release version.
  • -D CMAKE_INSTALL_PREFIX=$VIRTUAL_ENV: Crucial. This tells CMake to install OpenCV directly into your active virtual environment.
  • -D OPENCV_EXTRA_MODULES_PATH=../../opencv_contrib/modules: Points to the opencv_contrib modules you cloned.
  • -D PYTHON_EXECUTABLE=$VIRTUAL_ENV/bin/python: Ensures CMake uses the Python interpreter from your virtual environment.
  • -D BUILD_opencv_python3=ON: Enables Python 3 bindings.
  • PYTHON3_NUMPY_PATH, PYTHON3_PACKAGES_PATH, PYTHON3_INCLUDE_DIR, PYTHON3_LIBRARY: These ensure OpenCV links correctly with your virtual environment's Python and NumPy installation. Replace python3.x with your specific Python version (e.g., python3.8).

Step 5: Compile and Install OpenCV

After cmake successfully configures the build, compile OpenCV using make. This step can take a significant amount of time depending on your system's processing power.

# Compile OpenCV (use -jN where N is the number of CPU cores for faster compilation)
make -j$(nproc)

# Install OpenCV into the virtual environment
make install

After make install, OpenCV's libraries and Python bindings will be placed within your virtual environment's directories.

Step 6: Verify Installation

Finally, verify that OpenCV has been successfully installed and is accessible within your virtual environment.

# Ensure you are still in your activated virtual environment
# (venv) cd .. # If you are in the build directory, go back to project root

# Open a Python interpreter
python

# Inside the Python interpreter, try importing cv2
>>> import cv2
>>> print(cv2.__version__)
# Expected output: Your installed OpenCV version (e.g., 4.9.0)

If you see the OpenCV version printed without errors, your installation is successful! If you encounter ModuleNotFoundError: No module named 'cv2', double-check your cmake flags, especially CMAKE_INSTALL_PREFIX and the PYTHON3_* paths to ensure they point to your active virtual environment.

Summary of Key Commands

Step Command (Linux/macOS) Purpose
Create/Activate Virtual Env python3 -m venv venv
source venv/bin/activate		 Isolate project dependencies.
Install Dependencies sudo apt install build-essential cmake git pkg-config libjpeg-dev libpng-dev libtiff-dev libavcodec-dev libavformat-dev libswscale-dev libv4l-dev libxvidcore-dev libx264-dev libgtk-3-dev python3-dev python3-pip
pip install numpy pip wheel		 Provide necessary tools, libraries, and Python packages for compilation.
Clone Repositories mkdir src && cd src
git clone https://github.com/opencv/opencv.git
git clone https://github.com/opencv/opencv_contrib.git		 Obtain OpenCV source code and extra modules.
Configure with CMake cd opencv && mkdir build && cd build
cmake -D CMAKE_BUILD_TYPE=RELEASE -D CMAKE_INSTALL_PREFIX=$VIRTUAL_ENV -D OPENCV_EXTRA_MODULES_PATH=../../opencv_contrib/modules -D PYTHON_EXECUTABLE=$VIRTUAL_ENV/bin/python ...		 Prepare build files and link to virtual environment.
Compile & Install make -j$(nproc)
make install		 Build the library and install it into your virtual environment.
Verify Installation python
>>> import cv2
>>> print(cv2.__version__)		 Confirm OpenCV is correctly installed and accessible.
← Previous Article
Is Nisha a Pakistani Name?
Next Article →
What Are the Current COVID-19 Variants Circulating in November 2024?