From 3dce4fa655606a326374bf857e55e2940c27025f Mon Sep 17 00:00:00 2001 From: omaraziz255 <34421528+omaraziz255@users.noreply.github.com> Date: Fri, 14 Nov 2025 17:07:30 +0200 Subject: [PATCH] Merge pull request #27943 from omaraziz255:docs/py-pip-install docs(py): add pip-based install tutorial #27943 - New tutorial: `doc/tutorials/py_tutorials/py_setup/py_pip_install/py_pip_install.markdown` with anchor `{#tutorial_py_pip_install}`. - Python setup TOC updated to include the new page near the top. - Windows/Ubuntu/Fedora pages: added **Quick start (pip)** callout - Expanded troubleshooting in the pip tutorial (env mismatch, headless GUI notes, wheel mismatches, Raspberry Pi/ARM guidance). This aligns with the issue request to make `pip install opencv-python` the default path for Python newcomers and reduce confusion from legacy content. Fixes #24360 ### Pull Request Readiness Checklist See details at https://github.com/opencv/opencv/wiki/How_to_contribute#making-a-good-pull-request - [x] I agree to contribute to the project under Apache 2 License. - [x] To the best of my knowledge, the proposed patch is not based on a code under GPL or another license that is incompatible with OpenCV - [x] The PR is proposed to the proper branch - [x] There is a reference to the original bug report and related work - [x] There is accuracy test, performance test and test data in opencv_extra repository, if applicable Patch to opencv_extra has the same branch name. - [x] The feature is well documented and sample code can be built with the project CMake --- .../py_pip_install/py_pip_install.markdown | 116 ++++++++++++++++++ .../py_setup_in_fedora.markdown | 2 + .../py_setup_in_ubuntu.markdown | 2 + .../py_setup_in_windows.markdown | 12 +- .../py_table_of_contents_setup.markdown | 5 + 5 files changed, 132 insertions(+), 5 deletions(-) create mode 100644 doc/py_tutorials/py_setup/py_pip_install/py_pip_install.markdown diff --git a/doc/py_tutorials/py_setup/py_pip_install/py_pip_install.markdown b/doc/py_tutorials/py_setup/py_pip_install/py_pip_install.markdown new file mode 100644 index 0000000000..3630b3067d --- /dev/null +++ b/doc/py_tutorials/py_setup/py_pip_install/py_pip_install.markdown @@ -0,0 +1,116 @@ +# Install OpenCV for Python with pip {#tutorial_py_pip_install} + +This quick-start shows the **recommended** way for most users to get OpenCV in Python: install from +**PyPI** with `pip`. It also explains virtual environments, platform notes, and common troubleshooting. +If you need OS‑specific alternatives (system packages or source builds), see the OS pages linked +below, but those are **not required** for typical Python use. + +@note: OpenCV team maintains **PyPI** packages only. Conda distributions and platform specific builds +are community builds and hardware vendor builds and may differ from the official one. + +## Quick start + +```bash +# 1) Create and activate a virtual environment (recommended) +python -m venv .venv +# Windows: +.venv\Scripts\activate +# Linux/macOS: +source .venv/bin/activate + +# 2) Upgrade pip tooling +python -m pip install --upgrade pip setuptools wheel + +# 3) Install OpenCV from PyPI (choose ONE) +pip install opencv-python # main package (most users) +# or +pip install opencv-contrib-python # + extra modules (contrib) +# or +pip install opencv-python-headless # no GUI/backends (servers/CI) +# or +pip install opencv-contrib-python-headless # no GUI/backends with extra modules (servers/CI) +``` + +### Tiny hello‑world + +```python +import cv2 as cv +import numpy as np + +print("OpenCV:", cv.__version__) +img = np.zeros((120, 400, 3), dtype=np.uint8) +cv.putText(img, "OpenCV OK", (10, 80), cv.FONT_HERSHEY_SIMPLEX, 2, (255,255,255), 3) +# If you installed a non-headless build, you can display a window: +# cv.imshow("hello", img); cv.waitKey(0) +# Always safe (headless or not): save to file +cv.imwrite("hello.png", img) +``` + +## Virtual environments and IDEs + +Using a virtual environment keeps project dependencies isolated. Tools that create or activate envs include: + +- `venv` (built-in) and `virtualenv` +- Conda environments +- IDEs (VS Code, PyCharm) that may **auto-create and auto-activate** an env per workspace + +If imports fail inside an IDE, verify the interpreter selected by the IDE matches the environment +where you installed OpenCV. + +## OS notes + +- **Linux:** Your default Python may be `python3`. Use `python3 -m venv .venv` and `python3 -m pip ...`. +If you cannot use a virtual env, `pip --user` installs to your home directory: `python3 -m pip install --user opencv-python`. +- **Windows:** Install Python from [python.org] or via `winget install Python.Python.3`. Make sure +**“Add python to PATH”** is enabled or use the **“Open in terminal”** from your IDE, which selects +the right interpreter automatically. +- **macOS:** Use the system `python3` or a managed one (Homebrew or Python.org). +Always prefer a virtual environment. +- **Raspberry Pi / ARM boards:** Prebuilt wheels may not exist for some Pi OS / Python combinations. +See **Troubleshooting** below. + +## Choosing a PyPI variant + +- `opencv-python`: core OpenCV modules with GUI/backends +- `opencv-contrib-python`: includes **contrib** modules in addition to the core +- `opencv-python-headless`: no GUI/backends (ideal for servers/containers/CI) +- `opencv-contrib-python-headless`: contrib + headless + +Install exactly **one** of these per environment. + +## Troubleshooting + +Please start with opencv-python project [README](https://github.com/opencv/opencv-python/blob/4.x/README.md) + +**Pip is trying to build from source** +Symptoms: very long build step, CMake errors, compiler errors. +Fixes: +- Upgrade build tooling: `python -m pip install --upgrade pip setuptools wheel` +- Ensure your Python version is supported by the chosen package. +- If you are on an uncommon platform or Python build, switch to a supported Python or try a different +variant (headless vs non‑headless). + +**“No matching distribution found” or “Unsupported wheel”** +- Confirm your Python version (e.g., `python -V`). Choose a wheel that supports that version +(manylinux/macOS/Windows wheels on PyPI target specific Python versions). +- Create a fresh virtual environment with a mainstream Python (e.g., 3.10–3.12 for now) and reinstall. + +**Raspberry Pi / ARM** +- Wheels may lag behind new Python/Pi OS releases. Try `opencv-python-headless` first. If +unavailable, consider system packages for camera/GUI pieces, or build from source following +the OS page linked below. + +**Import works in terminal but fails in IDE** +- The IDE is using a different interpreter. Select the **same** environment inside your +IDE’s interpreter settings. + +## What about system packages or building from source? + +For beginners using Python, **PyPI is recommended**. Native distribution packages and full source +builds are better suited to advanced users with platform‑specific needs. You can still find them on +the OS‑specific pages, moved under “Alternatives.” + +## See also + +- @ref tutorial_py_root +- OS pages: @ref tutorial_py_setup_in_windows, @ref tutorial_py_setup_in_ubuntu, @ref tutorial_py_setup_in_fedora diff --git a/doc/py_tutorials/py_setup/py_setup_in_fedora/py_setup_in_fedora.markdown b/doc/py_tutorials/py_setup/py_setup_in_fedora/py_setup_in_fedora.markdown index 68fa5f678a..138b9125d7 100644 --- a/doc/py_tutorials/py_setup/py_setup_in_fedora/py_setup_in_fedora.markdown +++ b/doc/py_tutorials/py_setup/py_setup_in_fedora/py_setup_in_fedora.markdown @@ -1,6 +1,8 @@ Install OpenCV-Python in Fedora {#tutorial_py_setup_in_fedora} =============================== +@note: Please prefer binaries distributed with PyPI, if possible. See @ref tutorial_py_pip_install for details. + Goals ----- diff --git a/doc/py_tutorials/py_setup/py_setup_in_ubuntu/py_setup_in_ubuntu.markdown b/doc/py_tutorials/py_setup/py_setup_in_ubuntu/py_setup_in_ubuntu.markdown index 8b99c5df92..37a6b72ff9 100644 --- a/doc/py_tutorials/py_setup/py_setup_in_ubuntu/py_setup_in_ubuntu.markdown +++ b/doc/py_tutorials/py_setup/py_setup_in_ubuntu/py_setup_in_ubuntu.markdown @@ -1,6 +1,8 @@ Install OpenCV-Python in Ubuntu {#tutorial_py_setup_in_ubuntu} =============================== +@note: Please prefer binaries distributed with PyPI, if possible. See @ref tutorial_py_pip_install for details. + Goals ----- diff --git a/doc/py_tutorials/py_setup/py_setup_in_windows/py_setup_in_windows.markdown b/doc/py_tutorials/py_setup/py_setup_in_windows/py_setup_in_windows.markdown index 198422d8bf..417ab4cd67 100644 --- a/doc/py_tutorials/py_setup/py_setup_in_windows/py_setup_in_windows.markdown +++ b/doc/py_tutorials/py_setup/py_setup_in_windows/py_setup_in_windows.markdown @@ -1,6 +1,8 @@ Install OpenCV-Python in Windows {#tutorial_py_setup_in_windows} ================================ +@note: Please prefer binaries distributed with PyPI, if possible. See @ref tutorial_py_pip_install for details. + Goals ----- @@ -15,13 +17,13 @@ Installing OpenCV from prebuilt binaries -# Below Python packages are to be downloaded and installed to their default locations. - -# Python 3.x (3.4+) or Python 2.7.x from [here](https://www.python.org/downloads/). + -# Python 3.x (3.4+) from [here](https://www.python.org/downloads/). -# Numpy package (for example, using `pip install numpy` command). -# Matplotlib (`pip install matplotlib`) (*Matplotlib is optional, but recommended since we use it a lot in our tutorials*). --# Install all packages into their default locations. Python will be installed to `C:/Python27/` in case of Python 2.7. +-# Install all packages into their default locations. Python will be installed to `C:/Python34/` in case of Python 3.4. -# After installation, open Python IDLE. Enter **import numpy** and make sure Numpy is working fine. @@ -29,11 +31,11 @@ Installing OpenCV from prebuilt binaries [SourceForge site](https://sourceforge.net/projects/opencvlibrary/files/) and double-click to extract it. --# Goto **opencv/build/python/2.7** folder. +-# Goto **opencv/build/python/3.4** folder. --# Copy **cv2.pyd** to **C:/Python27/lib/site-packages**. +-# Copy **cv2.pyd** to **C:/Python34/lib/site-packages**. --# Copy the **opencv_world.dll** file to **C:/Python27/lib/site-packages** +-# Copy the **opencv_world.dll** file to **C:/Python34/lib/site-packages** -# Open Python IDLE and type following codes in Python terminal. @code diff --git a/doc/py_tutorials/py_setup/py_table_of_contents_setup.markdown b/doc/py_tutorials/py_setup/py_table_of_contents_setup.markdown index a5ea46d750..813e899320 100644 --- a/doc/py_tutorials/py_setup/py_table_of_contents_setup.markdown +++ b/doc/py_tutorials/py_setup/py_table_of_contents_setup.markdown @@ -6,6 +6,11 @@ Introduction to OpenCV {#tutorial_py_table_of_contents_setup} Getting Started with OpenCV-Python +- @subpage tutorial_py_pip_install + + Install OpenCV for + Python with pip + - @subpage tutorial_py_setup_in_windows Set Up