To install OpenCV on Ubuntu, you can either use the system package manager for a quick setup or build from source for the latest features and optimizations. This guide covers both methods, including how to set up a Python virtual environment and troubleshoot common issues.
Background: What is OpenCV?
OpenCV (Open Source Computer Vision Library) is an open-source library of programming functions mainly aimed at real-time computer vision. It provides a common infrastructure for computer vision applications and accelerates the use of machine perception in commercial products. Originally developed by Intel, it now supports a wide range of algorithms, including face detection, object recognition, and image processing. OpenCV is written in C++ and has bindings for Python, Java, and other languages, making it a versatile tool for developers and researchers.
Prerequisites and System Preparation
Before installing OpenCV, ensure your Ubuntu system is up to date and has the necessary build tools if you plan to compile from source. For most users, the Python package manager (pip) is the simplest route. However, you should also consider using a virtual environment to avoid conflicts with system packages.
- Update your package list:
sudo apt update - Install Python and pip if not already present:
sudo apt install python3 python3-pip - For building from source, install CMake and other dependencies:
sudo apt install build-essential cmake git pkg-config - For camera and video support, install:
sudo apt install libavcodec-dev libavformat-dev libswscale-dev libv4l-dev
Method 1: Install via pip (Recommended for Most Users)
The easiest way to install OpenCV for Python is using pip. This method provides pre-built binaries that work out of the box for most use cases.
- Create and activate a virtual environment (optional but recommended):
python3 -m venv opencv-envsource opencv-env/bin/activate - Install the main OpenCV package:
pip install opencv-python - For additional functionality like video decoding, also install:
pip install opencv-python-headless(if you don’t need GUI features) orpip install opencv-contrib-python(includes extra modules).
After installation, verify it by running python -c "import cv2; print(cv2.__version__)". You should see the version number, e.g., 4.8.0.
Method 2: Install via apt (System-Wide)
Ubuntu’s official repositories include OpenCV packages. This method is straightforward and integrates with system package management, but the version may be older than the latest release.
- Install the Python bindings:
sudo apt install python3-opencv - For C++ development, install the library and headers:
sudo apt install libopencv-dev
Check the installed version with python3 -c "import cv2; print(cv2.__version__)" or pkg-config --modversion opencv4 for C++.
Method 3: Building from Source (For Customization)
Building OpenCV from source gives you full control over enabled modules and optimizations (e.g., CUDA support). This process takes time and requires several dependencies.
- Install all required dependencies:
sudo apt install python3-dev python3-numpy python3-py python3-pytestplus the ones listed in prerequisites. - Clone the OpenCV and OpenCV contrib repositories:
git clone https://github.com/opencv/opencv.gitgit clone https://github.com/opencv/opencv_contrib.git - Create a build directory and configure with CMake:
cd opencv && mkdir build && cd buildcmake -D CMAKE_BUILD_TYPE=RELEASE -D CMAKE_INSTALL_PREFIX=/usr/local -D OPENCV_EXTRA_MODULES_PATH=../../opencv_contrib/modules .. - Compile and install:
make -j$(nproc)thensudo make install
This method is best for developers needing custom features or maximum performance.
Choosing the Right Installation Method
The best method depends on your needs:
- pip – Quick, simple, and ideal for Python-only projects. You get the latest stable version.
- apt – Good for system-wide integration and when you don’t need the newest features. It’s also easier to uninstall.
- Source – Necessary for CUDA support, custom modules, or if you need to modify the library itself.
Common Problems and How to Fix Them
Here are some frequent issues users encounter:
- ImportError: libGL.so.1: cannot open shared object file – This happens when the headless version is not installed or when the system lacks OpenGL libraries. Install with
sudo apt install libgl1or use the headless package. - ModuleNotFoundError: No module named ‘cv2’ – Ensure you installed the package in the correct environment. Check with
pip listand verify the virtual environment is active. - Version mismatch with numpy – OpenCV may require a specific numpy version. Upgrade or downgrade numpy accordingly:
pip install numpy==1.24.3(or a compatible version). - Camera not working – For webcam access, ensure the video device is available and permissions are set. Add your user to the
videogroup:sudo usermod -aG video $USER.
Frequently Asked Questions
What is the difference between opencv-python and opencv-contrib-python?
opencv-python contains the main modules, while opencv-contrib-python includes additional contributed modules like SIFT and SURF. If you need these extra algorithms, install the contrib version.
Can I use OpenCV with C++ on Ubuntu?
Yes, you can install the C++ library via sudo apt install libopencv-dev or build from source. Then compile your code with g++ -o app app.cpp $(pkg-config --cflags --libs opencv4).
How do I uninstall OpenCV?
If installed via pip, run pip uninstall opencv-python. For apt, use sudo apt remove python3-opencv. If built from source, you can remove the build directory and delete the installed files manually (or use sudo make uninstall in the build directory if available).
Does OpenCV support GPU acceleration on Ubuntu?
Yes, but you need to build from source with CUDA support enabled. Pre-built pip packages do not include CUDA. You must also have an NVIDIA GPU and the CUDA toolkit installed.
Is it safe to install OpenCV via pip?
Yes, the official packages on PyPI are safe. However, always verify the package name and version. Avoid installing from unverified sources.
Alternatives to OpenCV
If OpenCV doesn’t meet your needs, consider these alternatives:
- scikit-image – A Python library focused on image processing algorithms, built on SciPy.
- Pillow (PIL) – For basic image manipulation and format conversion.
- SimpleCV – A simplified interface for computer vision tasks, though less maintained.
- TensorFlow / PyTorch – For deep learning-based vision tasks, often used alongside OpenCV.
Choosing the right installation method ensures a smooth experience with OpenCV on Ubuntu. Whether you’re a beginner or an advanced developer, the steps above will get you up and running.
Related
General steps for current mainstream versions; menus can differ by device and version. See the disclaimer or report an error.
More in this bed
- iOS 18 Safari Not Working? Fixes That Help
- How to Check Your Linux Kernel for Spectre
- iPhone Safe Mode: How to Enable or Disable It
- Fix Slow Internet Lag on Samsung Galaxy Note
- How to Retrieve WhatsApp Backup from Google Drive
- How to Get iOS 17 on iPhone X (Safe Methods)