opencv_contrib, the C++ quarantine where OpenCV modules live before they earn a stable API

Modules land here unstable on purpose, and the promotion path is the deal

opencv_contrib exists as a holding area for contributed functionality, and the terms are stated plainly. New modules often have no stable API and are not well tested, which is why they are not released as part of the official OpenCV distribution, a library that maintains binary compatibility and tries to provide decent performance and stability. The exchange offered to a user is a promotion path. A module is developed in this repository first, and when it matures and gains popularity it moves to the central OpenCV repository, where the development team provides production-quality support for it. The consequences follow from that policy rather than from any defect. Every API you call from a contrib module can change without a deprecation cycle, because there is no compatibility promise to violate. This repository also has no GitHub releases to pin against and its default branch is 5.x, so what you track is a moving branch. The last push is dated 2 November 2026, which tells you work is arriving without telling you which commit your build used.

The only documented route is a CMake configure pointed at a modules folder

There is no standalone library here to link, and no install script. The documented way to get these modules is to build the core library against this tree.

$ cd <opencv_build_directory>
$ cmake -DOPENCV_EXTRA_MODULES_PATH=<opencv_contrib>/modules <opencv_source_directory>
$ make -j5

The result is an OpenCV built in the build directory with all modules from this repository included. Two constraints travel with that command. Since opencv_contrib is not something you link on its own, picking up a single module costs a full rebuild of the core rather than a package you can add later. And because contrib modules are under constant development, the recommendation is to use them alongside the master branch or the latest OpenCV releases, which ties the contrib checkout you build against the core version on your disk. Neither side of that pairing is versioned for you in this repository, so the two checkouts have to be kept compatible by hand.

BUILD_opencv_legacy=OFF shows the pruning syntax and hides the dependency graph

Selection happens through CMake's `BUILD_opencv_*` options, and dropping one is a single added flag.

$ cmake -DOPENCV_EXTRA_MODULES_PATH=<opencv_contrib>/modules -DBUILD_opencv_legacy=OFF <opencv_source_directory>

That example switches off the legacy module and changes nothing else. What you do not get with it is a dependency map between contrib modules, so removing one because you have no use for it can also remove something a module you kept expects to link against, and the failure shows up during configure or link rather than in documentation. A second switch matters for evaluation. Adding `-DBUILD_EXAMPLES=ON` is what builds the samples from each module's samples folder, so with it off the example programs a module's README points you at are not in the build at all. For anyone judging a module by running its samples, that flag is the difference between a working demonstration and a link error.

Step eight of the GUI route leaves you adding linker flags by hand

A graphical route exists for people who prefer not to type flags, and the README walks it through cmake-gui in eight steps: start cmake-gui, select the OpenCV source folder and the build folder in the two upper fields, press configure, search the parameters for the form called `OPENCV_EXTRA_MODULES_PATH`, fill it with the pathname to the modules directory using the browse button, then press configure and generate, picking a makefile style when asked on the first pass, and build the core with the method you chose.

The last step is the one with consequences. After building, linker flags for contrib modules have to be added before you can use them in your code or IDE, and the only worked example given is `-lopencv_aruco` for the aruco module. A finished build is therefore not a usable build on its own. Each module you intend to call costs one manually added flag, one example is provided, and the number of modules in the tree decides how much of that you work out yourself. Nothing in the README describes a way to generate or copy the full set of flags.

A module is only as specified as its own README

Contribution carries two documentation obligations and both are written down. You add your module to the README.md under the modules folder as a single-line description, and you place a README.md inside your own module folder that explains which functionality is available, links to the corresponding samples, and sets out in more detail what the module is expected to do. Any extra requirement needed to build the module without problems belongs in that same file.

For a user, that rule is effectively the specification. A module that names its optional dependency lets you find the requirement before you configure; a module that omits it leaves the failure inside your CMake output with no pointer to a fix. The repository also carries a top-level doc/ directory, yet the README does not connect that directory to the module READMEs or say how the two are kept in step. So the module folder is the place where build requirements are recorded, and there is no second, authoritative page to cross-check them against.

The Python story is a samples folder, not a package

The tree's shape explains most of the confusion around Python. The top level holds modules/, doc/, and samples/, and inside samples there are a data/ directory and a python2/ directory, while the default branch of the repository is 5.x. Nothing in the build instructions mentions pip, a wheel, or a package index. The documented path is CMake followed by make, and that is the whole installation story given here. For someone expecting to install these modules into a Python environment, the practical consequence is that this repository holds the C++ sources and the bindings would have to be built from them, rather than handing you something to import. The python2 sample directory also sits next to a 5.x default branch with no note about which interpreter those samples target, so starting from the samples gives you no stated compatibility baseline to check against.

The repository's own scaffolding stops at a Travis file

The top level is modules/, samples/, doc/, README.md, CONTRIBUTING.md, LICENSE, .travis.yml, .editorconfig, .gitattributes, .gitignore, and .github/. The tree includes a .travis.yml, and the README names no test command, no per-module test target, and no lint step, so nothing in it tells you how to exercise one module before proposing it. The gap matters for two different readers. A contributor trying to move a module toward promotion has no documented bar to clear in this repository, which leaves the maturity judgement entirely with the central project's team. A user has no signal about which modules are in flux, because the inventory under modules/ is a single-line description per module with no stability marking. The push dated 2 November 2026 shows commits still arriving; it does not tell you which of them will change an API you call.

Editorial conclusion

opencv_contrib is the right place to work on an OpenCV module that is still moving, and for users who already rebuild the core library with CMake it is a low friction way to try functionality months before it reaches the main repository. It is the wrong choice for a production dependency that needs a stable API, for anyone who wants a pip install, and for teams that cannot absorb an API change on a branch with no releases. Before you depend on a module from it, check whether that module has already been promoted to the central repository, and read its own README for the extra build requirements the module author recorded.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. opencv/opencv_contrib on GitHub
4. README