Merge pull request #26564 from shyama7004:improve-macos-install-docs

Improvement of macOS installation guide in documentation #26564 ### 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 - [ ] There is a reference to the original bug report and related work - [ ] There is accuracy test, performance test and test data in opencv_extra repository, if applicable Patch to opencv_extra has the same branch name. - [ ] The feature is well documented and sample code can be built with the project CMake
2025-07-30 17:37:05 +08:00 · 2024-12-06 11:25:41 +05:30 · 2024-12-06 11:25:41 +05:30 · 3d91d75f1a
commit 3d91d75f1a
parent 23fcea0d33
1 changed files with 94 additions and 39 deletions
--- a/doc/tutorials/introduction/macos_install/macos_install.markdown
+++ b/doc/tutorials/introduction/macos_install/macos_install.markdown
@ -9,41 +9,49 @@ Installation in MacOS {#tutorial_macos_install}
 | Original author | `@sajarindider` |
 | Compatibility | OpenCV >= 3.4 |

-The following steps have been tested for MacOSX (Mavericks) but should work with other versions as well.
+The following steps have been tested for macOS (Mavericks) but should work with other versions as well.

 Required Packages
 -----------------

 -   CMake 3.9 or higher
 -   Git
-   Python 2.7 or later and Numpy 1.5 or later
+-   Python 3.x and NumPy 1.5 or later

 This tutorial will assume you have [Python](https://docs.python.org/3/using/mac.html),
-[Numpy](https://docs.scipy.org/doc/numpy-1.10.1/user/install.html) and
-[Git](https://www.atlassian.com/git/tutorials/install-git) installed on your machine.
+[NumPy](https://numpy.org/install/) and
+[Git](https://git-scm.com/downloads/mac) installed on your machine.

@note
-OSX comes with Python 2.7 by default, you will need to install Python 3.8 if you want to use it specifically.
+-   macOS up to 12.2 (Monterey): Comes with Python 2.7 pre-installed.
+-   macOS 12.3 and later: Python 2.7 has been removed, and no version of Python is included by default.
+
+It is recommended to install the latest version of Python 3.x (at least Python 3.8) for compatibility with the latest OpenCV Python bindings.

@note
-If you XCode and XCode Command Line-Tools installed, you already have git installed on your machine.
+If you have Xcode and Xcode Command Line Tools installed, Git is already available on your machine.

 Installing CMake
 ----------------
 -# Find the version for your system and download CMake from their release's [page](https://cmake.org/download/)

-# Install the dmg package and launch it from Applications. That will give you the UI app of CMake
+-# Install the `.dmg` package and launch it from Applications. That will give you the UI app of CMake

 -# From the CMake app window, choose menu Tools --> How to Install For Command Line Use. Then, follow the instructions from the pop-up there.

-# Install folder will be /usr/bin/ by default, submit it by choosing Install command line links.
+-# The install folder will be `/usr/local/bin/` by default. Complete the installation by choosing Install command line links.
+
+-# Test that CMake is installed correctly by running:

-# Test that it works by running
    @code{.bash}
    cmake --version
    @endcode

-@note You can use [Homebrew](https://brew.sh/) to install CMake with @code{.bash} brew install cmake @endcode
+@note You can use [Homebrew](https://brew.sh/) to install CMake with:
+
+    @code{.bash}
+    brew install cmake
+    @endcode

 Getting OpenCV Source Code
 --------------------------
@ -53,20 +61,22 @@ You can use the latest stable OpenCV version or you can grab the latest snapshot

 ### Getting the Latest Stable OpenCV Version

-   Go to our [downloads page](https://opencv.org/releases).
-   Download the source archive and unpack it.
+-   Go to our [OpenCV releases page](https://opencv.org/releases).
+-   Download the source archive of the latest version (e.g., OpenCV 4.x) and unpack it.

 ### Getting the Cutting-edge OpenCV from the Git Repository

-Launch Git client and clone [OpenCV repository](http://github.com/opencv/opencv).
-If you need modules from [OpenCV contrib repository](http://github.com/opencv/opencv_contrib) then clone it as well.
+Launch Git client and clone [OpenCV repository](https://github.com/opencv/opencv).
+If you need modules from [OpenCV contrib repository](https://github.com/opencv/opencv_contrib) then clone it as well.
+
+For example:
+
+    @code{.bash}
+    cd ~/<your_working_directory>
+    git clone https://github.com/opencv/opencv.git
+    git clone https://github.com/opencv/opencv_contrib.git
+    @endcode

-For example
-@code{.bash}
-cd ~/<my_working_directory>
-git clone https://github.com/opencv/opencv.git
-git clone https://github.com/opencv/opencv_contrib.git
-@endcode
 Building OpenCV from Source Using CMake
 ---------------------------------------

@ -74,53 +84,98 @@ Building OpenCV from Source Using CMake
    the generated Makefiles, project files as well the object files and output binaries and enter
    there.

-    For example
+    For example:
+
    @code{.bash}
    mkdir build_opencv
    cd build_opencv
    @endcode

-    @note It is good practice to keep clean your source code directories. Create build directory outside of source tree.
+    @note It is good practice to keep your source code directories clean. Create the build directory outside of the source tree.

 -#  Configuring. Run `cmake [<some optional parameters>] <path to the OpenCV source directory>`

-    For example
+    For example:
+
    @code{.bash}
    cmake -DCMAKE_BUILD_TYPE=Release -DBUILD_EXAMPLES=ON ../opencv
    @endcode

-    or cmake-gui
+    Alternatively, you can use the CMake GUI (`cmake-gui`):

-    -   set the OpenCV source code path to, e.g. `/home/user/opencv`
-    -   set the binary build path to your CMake build directory, e.g. `/home/user/build_opencv`
+    -   set the OpenCV source code path to, e.g. `/Users/your_username/opencv`
+    -   set the binary build path to your CMake build directory, e.g. `/Users/your_username/build_opencv`
    -   set optional parameters
    -   run: "Configure"
    -   run: "Generate"

 -#  Description of some parameters
-    -   build type: `CMAKE_BUILD_TYPE=Release` (or `Debug`)
-    -   to build with modules from opencv_contrib set `OPENCV_EXTRA_MODULES_PATH` to `<path to
-        opencv_contrib>/modules`
-    -   set `BUILD_DOCS=ON` for building documents (doxygen is required)
-    -   set `BUILD_EXAMPLES=ON` to build all examples
+    -   build type: `-DCMAKE_BUILD_TYPE=Release` (or `Debug`).
+    -   include Extra Modules: If you cloned the `opencv_contrib` repository and want to include its modules, set:
+
+        @code{.bash}
+        -DOPENCV_EXTRA_MODULES_PATH=../opencv_contrib/modules
+        @endcode
+    -   set `-DBUILD_DOCS=ON` for building documents (doxygen is required)
+    -   set `-DBUILD_EXAMPLES=ON` to build all examples

 -#  [optional] Building python. Set the following python parameters:
-    -   `PYTHON3_EXECUTABLE = <path to python>`
-    -   `PYTHON3_INCLUDE_DIR = /usr/include/python<version>`
-    -   `PYTHON3_NUMPY_INCLUDE_DIRS =
-        /usr/lib/python<version>/dist-packages/numpy/core/include/`
+    -   `-DPYTHON3_EXECUTABLE=$(which python3)`
+    -   `-DPYTHON3_INCLUDE_DIR=$(python3 -c "from sysconfig import get_paths as gp; print(gp()['include'])")`
+    -   `-DPYTHON3_NUMPY_INCLUDE_DIRS=$(python3 -c "import numpy; print(numpy.get_include())")`
    @note
-    To specify Python2 versions, you can replace `PYTHON3_` with `PYTHON2_` in the above parameters.
+    Python 2 has reached its end of life. It is recommended to use Python 3 for building Python bindings.

 -#  Build. From build directory execute *make*, it is recommended to do this in several threads

-    For example
+    For example:
+
    @code{.bash}
-    make -j7 # runs 7 jobs in parallel
+    make -j$(sysctl -n hw.ncpu) # runs the build using all available CPU cores
    @endcode

-#  To use OpenCV in your CMake-based projects through `find_package(OpenCV)` specify `OpenCV_DIR=<path_to_build_or_install_directory>` variable.
+-#  After building, you can install OpenCV system-wide using:
+
+    @code{.bash}
+    sudo make install
+    @endcode
+
+-#  To use OpenCV in your CMake-based projects through `find_package(OpenCV)`, specify the `OpenCV_DIR` variable pointing to the build or install directory.
+
+    For example:
+
+    @code{.bash}
+    cmake -DOpenCV_DIR=~/build_opencv ..
+    @endcode
+
+### Verifying the OpenCV Installation
+
+After building (and optionally installing) OpenCV, you can verify the installation by checking the version using Python:
+
+    @code{.bash}
+    python3 -c "import cv2; print(cv2.__version__)"
+    @endcode
+
+This command should output the version of OpenCV you have installed.

@note
 You can also use a package manager like [Homebrew](https://brew.sh/)
 or [pip](https://pip.pypa.io/en/stable/) to install releases of OpenCV only (Not the cutting edge).
+
+- Installing via Homebrew:
+
+    For example:
+
+    @code{.bash}
+    brew install opencv
+    @endcode
+
+- Installing via pip:
+
+    For example:
+
+    @code{.bash}
+    pip install opencv-python
+    @endcode
+
+    @note To access the extra modules from `opencv_contrib`, install the `opencv-contrib-python` package using `pip install opencv-contrib-python`.