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
2026-01-15 12:15:17 +00:00 · 2025-11-14 17:07:30 +02:00
parent 1abc90c178
commit 3dce4fa655
5 changed files with 132 additions and 5 deletions
--- 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
@@ -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
--- 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
 -----

--- 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
 -----

--- 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
--- 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