Prev Tutorial: OpenCV configuration options reference
Next Tutorial: Installation in Linux
Introduction
OpenCV can change its behavior depending on the runtime environment:
- enable extra debugging output or performance tracing
- modify default locations and search paths
- tune some algorithms or general behavior
- enable or disable workarounds, safety features and optimizations
Notes:
- ⭐ marks most popular variables
- variables with names like this
VAR_${NAME}
describes family of variables, where ${NAME}
should be changed to one of predefined values, e.g. VAR_TBB
, VAR_OPENMP
, ...
Setting environment variable in Windows
In terminal or cmd-file (bat-file):
set MY_ENV_VARIABLE=true
C:\my_app.exe
In GUI:
- Go to "Settings -> System -> About"
- Click on "Advanced system settings" in the right part
- In new window click on the "Environment variables" button
- Add an entry to the "User variables" list
Setting environment variable in Linux
In terminal or shell script:
export MY_ENV_VARIABLE=true
./my_app
or as a single command:
MY_ENV_VARIABLE=true ./my_app
Setting environment variable in Python
import os
os.environ["MY_ENV_VARIABLE"] = True
import cv2
Types
- non-null - set to anything to enable feature, in some cases can be interpreted as other types (e.g. path)
- bool -
1
, True
, true
, TRUE
/ 0
, False
, false
, FALSE
- number/_size_ - unsigned number, suffixes
MB
, Mb
, mb
, KB
, Kb
, kb
- string - plain string or can have a structure
- path - to file, to directory
- paths -
;
-separated on Windows, :
-separated on others
General, core
name | type | default | description |
OPENCV_SKIP_CPU_BASELINE_CHECK | non-null | | do not check that current CPU supports all features used by the build (baseline) |
OPENCV_CPU_DISABLE | , or ; -separated | | disable code branches which use CPU features (dispatched code) |
OPENCV_SETUP_TERMINATE_HANDLER | bool | true (Windows) | use std::set_terminate to install own termination handler |
OPENCV_LIBVA_RUNTIME | file path | | libva for VA interoperability utils |
OPENCV_ENABLE_MEMALIGN | bool | true (except static analysis, memory sanitizer, fuzzying, _WIN32?) | enable aligned memory allocations |
OPENCV_BUFFER_AREA_ALWAYS_SAFE | bool | false | enable safe mode for multi-buffer allocations (each buffer separately) |
OPENCV_KMEANS_PARALLEL_GRANULARITY | num | 1000 | tune algorithm parallel work distribution parameter parallel_for_(..., ..., ..., granularity) |
OPENCV_DUMP_ERRORS | bool | true (Debug or Android), false (others) | print extra information on exception (log to Android) |
OPENCV_DUMP_CONFIG | non-null | | print build configuration to stderr (getBuildInformation ) |
OPENCV_PYTHON_DEBUG | bool | false | enable extra warnings in Python bindings |
OPENCV_TEMP_PATH | non-null / path | /tmp/ (Linux), /data/local/tmp/ (Android), GetTempPathA (Windows) | directory for temporary files |
OPENCV_DATA_PATH_HINT | paths | | paths for findDataFile |
OPENCV_DATA_PATH | paths | | paths for findDataFile |
OPENCV_SAMPLES_DATA_PATH_HINT | paths | | paths for findDataFile |
OPENCV_SAMPLES_DATA_PATH | paths | | paths for findDataFile |
Links:
Logging
name | type | default | description |
⭐ OPENCV_LOG_LEVEL | string | | logging level (see accepted values below) |
OPENCV_LOG_TIMESTAMP | bool | true | logging with timestamps |
OPENCV_LOG_TIMESTAMP_NS | bool | false | add nsec to logging timestamps |
Levels:
0
, O
, OFF
, S
, SILENT
, DISABLE
, DISABLED
F
, FATAL
E
, ERROR
W
, WARNING
, WARN
, WARNINGS
I
, INFO
D
, DEBUG
V
, VERBOSE
core/parallel_for
name | type | default | description |
⭐ OPENCV_FOR_THREADS_NUM | num | 0 | set number of threads |
OPENCV_THREAD_POOL_ACTIVE_WAIT_PAUSE_LIMIT | num | 16 | tune pthreads parallel_for backend |
OPENCV_THREAD_POOL_ACTIVE_WAIT_WORKER | num | 2000 | tune pthreads parallel_for backend |
OPENCV_THREAD_POOL_ACTIVE_WAIT_MAIN | num | 10000 | tune pthreads parallel_for backend |
OPENCV_THREAD_POOL_ACTIVE_WAIT_THREADS_LIMIT | num | 0 | tune pthreads parallel_for backend |
OPENCV_FOR_OPENMP_DYNAMIC_DISABLE | bool | false | use single OpenMP thread |
backends
OPENCV_LEGACY_WAITKEY Some modules have multiple available backends, following variables allow choosing specific backend or changing default priorities in which backends will be probed (e.g. when opening a video file).
name | type | default | description |
OPENCV_PARALLEL_BACKEND | string | | choose specific paralel_for backend (one of TBB , ONETBB , OPENMP ) |
OPENCV_PARALLEL_PRIORITY_${NAME} | num | | set backend priority, default is 1000 |
OPENCV_PARALLEL_PRIORITY_LIST | string, , -separated | | list of backends in priority order |
OPENCV_UI_BACKEND | string | | choose highgui backend for window rendering (one of GTK , GTK3 , GTK2 , QT , WIN32 ) |
OPENCV_UI_PRIORITY_${NAME} | num | | set highgui backend priority, default is 1000 |
OPENCV_UI_PRIORITY_LIST | string, , -separated | | list of hioghgui backends in priority order |
OPENCV_VIDEOIO_PRIORITY_${NAME} | num | | set videoio backend priority, default is 1000 |
OPENCV_VIDEOIO_PRIORITY_LIST | string, , -separated | | list of videoio backends in priority order |
plugins
Some external dependencies can be detached into a dynamic library, which will be loaded at runtime (plugin). Following variables allow changing default search locations and naming pattern for these plugins.
name | type | default | description |
OPENCV_CORE_PLUGIN_PATH | paths | | directories to search for core plugins |
OPENCV_CORE_PARALLEL_PLUGIN_${NAME} | string, glob | | parallel_for plugin library name (glob), e.g. default for TBB is "opencv_core_parallel_tbb*.so" |
OPENCV_DNN_PLUGIN_PATH | paths | | directories to search for dnn plugins |
OPENCV_DNN_PLUGIN_${NAME} | string, glob | | parallel_for plugin library name (glob), e.g. default for TBB is "opencv_core_parallel_tbb*.so" |
OPENCV_CORE_PLUGIN_PATH | paths | | directories to search for highgui plugins (YES it is CORE) |
OPENCV_UI_PLUGIN_${NAME} | string, glob | | highgui plugin library name (glob) |
OPENCV_VIDEOIO_PLUGIN_PATH | paths | | directories to search for videoio plugins |
OPENCV_VIDEOIO_PLUGIN_${NAME} | string, glob | | videoio plugin library name (glob) |
OpenCL
Note: OpenCL device specification format is <Platform>:<CPU|GPU|ACCELERATOR|nothing=GPU/CPU>:<deviceName>
, e.g. AMD:GPU:
name | type | default | description |
OPENCV_OPENCL_RUNTIME | filepath or disabled | | path to OpenCL runtime library (e.g. OpenCL.dll , libOpenCL.so ) |
⭐ OPENCV_OPENCL_DEVICE | string or disabled | | choose specific OpenCL device. See specification format in the note above. See more details in the Links section. |
OPENCV_OPENCL_RAISE_ERROR | bool | false | raise exception if something fails during OpenCL kernel preparation and execution (Release builds only) |
OPENCV_OPENCL_ABORT_ON_BUILD_ERROR | bool | false | abort if OpenCL kernel compilation failed |
OPENCV_OPENCL_CACHE_ENABLE | bool | true | enable OpenCL kernel cache |
OPENCV_OPENCL_CACHE_WRITE | bool | true | allow writing to the cache, otherwise cache will be read-only |
OPENCV_OPENCL_CACHE_LOCK_ENABLE | bool | true | use .lock files to synchronize between multiple applications using the same OpenCL cache (may not work on network drives) |
OPENCV_OPENCL_CACHE_CLEANUP | bool | true | automatically remove old entries from cache (leftovers from older OpenCL runtimes) |
OPENCV_OPENCL_VALIDATE_BINARY_PROGRAMS | bool | false | validate loaded binary OpenCL kernels |
OPENCV_OPENCL_DISABLE_BUFFER_RECT_OPERATIONS | bool | true (Apple), false (others) | enable workaround for non-continuos data downloads |
OPENCV_OPENCL_BUILD_EXTRA_OPTIONS | string | | pass extra options to OpenCL kernel compilation |
OPENCV_OPENCL_ENABLE_MEM_USE_HOST_PTR | bool | true | workaround/optimization for buffer allocation |
OPENCV_OPENCL_ALIGNMENT_MEM_USE_HOST_PTR | num | 4 | parameter for OPENCV_OPENCL_ENABLE_MEM_USE_HOST_PTR |
OPENCV_OPENCL_DEVICE_MAX_WORK_GROUP_SIZE | num | 0 | allow to decrease maxWorkGroupSize |
OPENCV_OPENCL_PROGRAM_CACHE | num | 0 | limit number of programs in OpenCL kernel cache |
OPENCV_OPENCL_RAISE_ERROR_REUSE_ASYNC_KERNEL | bool | false | raise exception if async kernel failed |
OPENCV_OPENCL_BUFFERPOOL_LIMIT | num | 1 << 27 (Intel device), 0 (others) | limit memory used by buffer bool |
OPENCV_OPENCL_HOST_PTR_BUFFERPOOL_LIMIT | num | | same as OPENCV_OPENCL_BUFFERPOOL_LIMIT, but for HOST_PTR buffers |
OPENCV_OPENCL_BUFFER_FORCE_MAPPING | bool | false | force clEnqueueMapBuffer |
OPENCV_OPENCL_BUFFER_FORCE_COPYING | bool | false | force clEnqueueReadBuffer/clEnqueueWriteBuffer |
OPENCV_OPENCL_FORCE | bool | false | force running OpenCL kernel even if usual conditions are not met (e.g. dst.isUMat) |
OPENCV_OPENCL_PERF_CHECK_BYPASS | bool | false | force running OpenCL kernel even if usual performance-related conditions are not met (e.g. image is very small) |
SVM (Shared Virtual Memory) - disabled by default
name | type | default | description |
OPENCV_OPENCL_SVM_DISABLE | bool | false | disable SVM |
OPENCV_OPENCL_SVM_FORCE_UMAT_USAGE | bool | false | |
OPENCV_OPENCL_SVM_DISABLE_UMAT_USAGE | bool | false | |
OPENCV_OPENCL_SVM_CAPABILITIES_MASK | num | | |
OPENCV_OPENCL_SVM_BUFFERPOOL_LIMIT | num | | same as OPENCV_OPENCL_BUFFERPOOL_LIMIT, but for SVM buffers |
Links:
Tracing/Profiling
name | type | default | description |
⭐ OPENCV_TRACE | bool | false | enable trace |
OPENCV_TRACE_LOCATION | string | OpenCVTrace | trace file name ("${name}-$03d.txt") |
OPENCV_TRACE_DEPTH_OPENCV | num | 1 | |
OPENCV_TRACE_MAX_CHILDREN_OPENCV | num | 1000 | |
OPENCV_TRACE_MAX_CHILDREN | num | 1000 | |
OPENCV_TRACE_SYNC_OPENCL | bool | false | wait for OpenCL kernels to finish |
OPENCV_TRACE_ITT_ENABLE | bool | true | |
OPENCV_TRACE_ITT_PARENT | bool | false | set parentID for ITT task |
OPENCV_TRACE_ITT_SET_THREAD_NAME | bool | false | set name for OpenCV's threads "OpenCVThread-%03d" |
Links:
Cache
Note: Default tmp location is TMPDIR%
(Windows); $XDG_CACHE_HOME
, $HOME/.cache
, /var/tmp
, /tmp
(others)
name | type | default | description |
OPENCV_CACHE_SHOW_CLEANUP_MESSAGE | bool | true | show cache cleanup message |
OPENCV_DOWNLOAD_CACHE_DIR | path | default tmp location | cache directory for downloaded files (subdirectory downloads ) |
OPENCV_DNN_IE_GPU_CACHE_DIR | path | default tmp location | cache directory for OpenVINO OpenCL kernels (subdirectory dnn_ie_cache_${device} ) |
OPENCV_OPENCL_CACHE_DIR | path | default tmp location | cache directory for OpenCL kernels cache (subdirectory opencl_cache ) |
dnn
Note: In the table below dump_base_name
equals to ocv_dnn_net_%05d_%02d
where first argument is internal network ID and the second - dump level.
name | type | default | description |
OPENCV_DNN_BACKEND_DEFAULT | num | 3 (OpenCV) | set default DNN backend, see dnn.hpp for backends enumeration |
OPENCV_DNN_NETWORK_DUMP | num | 0 | level of information dumps, 0 - no dumps (default file name ${dump_base_name}.dot ) |
OPENCV_DNN_DISABLE_MEMORY_OPTIMIZATIONS | bool | false | |
OPENCV_DNN_CHECK_NAN_INF | bool | false | check for NaNs in layer outputs |
OPENCV_DNN_CHECK_NAN_INF_DUMP | bool | false | print layer data when NaN check has failed |
OPENCV_DNN_CHECK_NAN_INF_RAISE_ERROR | bool | false | also raise exception when NaN check has failed |
OPENCV_DNN_ONNX_USE_LEGACY_NAMES | bool | false | use ONNX node names as-is instead of "onnx_node!${node_name}" |
OPENCV_DNN_CUSTOM_ONNX_TYPE_INCLUDE_DOMAIN_NAME | bool | true | prepend layer domain to layer types ("domain.type") |
OPENCV_VULKAN_RUNTIME | file path | | set location of Vulkan runtime library for DNN Vulkan backend |
OPENCV_DNN_IE_SERIALIZE | bool | false | dump intermediate OpenVINO graph (default file names ${dump_base_name}_ngraph.xml , ${dump_base_name}_ngraph.bin ) |
OPENCV_DNN_IE_EXTRA_PLUGIN_PATH | path | | path to extra OpenVINO plugins |
OPENCV_DNN_IE_VPU_TYPE | string | | Force using specific OpenVINO VPU device type ("Myriad2" or "MyriadX") |
OPENCV_TEST_DNN_IE_VPU_TYPE | string | | same as OPENCV_DNN_IE_VPU_TYPE, but for tests |
OPENCV_DNN_INFERENCE_ENGINE_HOLD_PLUGINS | bool | true | always hold one existing OpenVINO instance to avoid crashes on unloading |
OPENCV_DNN_INFERENCE_ENGINE_CORE_LIFETIME_WORKAROUND | bool | true (Windows), false (other) | another OpenVINO lifetime workaround |
OPENCV_DNN_OPENCL_ALLOW_ALL_DEVICES | bool | false | allow running on CPU devices, allow FP16 on non-Intel device |
OPENCV_OCL4DNN_CONVOLUTION_IGNORE_INPUT_DIMS_4_CHECK | bool | false | workaround for OpenCL backend, see https://github.com/opencv/opencv/issues/20833 |
OPENCV_OCL4DNN_WORKAROUND_IDLF | bool | true | another workaround for OpenCL backend |
OPENCV_OCL4DNN_CONFIG_PATH | path | | path to kernel configuration cache for auto-tuning (must be existing directory), set this variable to enable auto-tuning |
OPENCV_OCL4DNN_DISABLE_AUTO_TUNING | bool | false | disable auto-tuning |
OPENCV_OCL4DNN_FORCE_AUTO_TUNING | bool | false | force auto-tuning |
OPENCV_OCL4DNN_TEST_ALL_KERNELS | num | 0 | test convolution kernels, number of iterations (auto-tuning) |
OPENCV_OCL4DNN_DUMP_FAILED_RESULT | bool | false | dump extra information on errors (auto-tuning) |
OPENCV_OCL4DNN_TUNING_RAISE_CHECK_ERROR | bool | false | raise exception on errors (auto-tuning) |
Tests
name | type | default | description |
⭐ OPENCV_TEST_DATA_PATH | dir path | | set test data search location (e.g. /home/user/opencv_extra/testdata ) |
⭐ OPENCV_DNN_TEST_DATA_PATH | dir path | $OPENCV_TEST_DATA_PATH/dnn | set DNN model search location for tests (used by dnn, gapi, objdetect, video modules) |
OPENCV_OPEN_MODEL_ZOO_DATA_PATH | dir path | $OPENCV_DNN_TEST_DATA_PATH/omz_intel_models | set OpenVINO models search location for tests (used by dnn, gapi modules) |
INTEL_CVSDK_DIR | | | some dnn tests can search OpenVINO models here too |
OPENCV_TEST_DEBUG | num | 0 | debug level for tests, same as --test_debug (0 - no debug (default), 1 - basic test debug information, >1 - extra debug information) |
OPENCV_TEST_REQUIRE_DATA | bool | false | same as --test_require_data option (fail on missing non-required test data instead of skip) |
OPENCV_TEST_CHECK_OPTIONAL_DATA | bool | false | assert when optional data is not found |
OPENCV_IPP_CHECK | bool | false | default value for --test_ipp_check and --perf_ipp_check |
OPENCV_PERF_VALIDATION_DIR | dir path | | location of files read/written by --perf_read_validation_results /--perf_write_validation_results |
⭐ OPENCV_PYTEST_FILTER | string (glob) | | test filter for Python tests |
Links:
videoio
Note: extra FFmpeg options should be pased in form key;value|key;value|key;value
, for example hwaccel;cuvid|video_codec;h264_cuvid|vsync;0
or vcodec;x264|vprofile;high|vlevel;4.0
name | type | default | description |
⭐ OPENCV_FFMPEG_CAPTURE_OPTIONS | string (see note) | | extra options for VideoCapture FFmpeg backend |
⭐ OPENCV_FFMPEG_WRITER_OPTIONS | string (see note) | | extra options for VideoWriter FFmpeg backend |
OPENCV_FFMPEG_THREADS | num | | set FFmpeg thread count |
OPENCV_FFMPEG_DEBUG | non-null | | enable logging messages from FFmpeg |
OPENCV_FFMPEG_LOGLEVEL | num | | set FFmpeg logging level |
OPENCV_FFMPEG_DLL_DIR | dir path | | directory with FFmpeg plugin (legacy) |
OPENCV_FFMPEG_IS_THREAD_SAFE | bool | false | enabling this option will turn off thread safety locks in the FFmpeg backend (use only if you are sure FFmpeg is built with threading support, tested on Linux) |
OPENCV_FFMPEG_READ_ATTEMPTS | num | 4096 | number of failed av_read_frame attempts before failing read procedure |
OPENCV_FFMPEG_DECODE_ATTEMPTS | num | 64 | number of failed avcodec_receive_frame attempts before failing decoding procedure |
OPENCV_VIDEOIO_GSTREAMER_CALL_DEINIT | bool | false | close GStreamer instance on end |
OPENCV_VIDEOIO_GSTREAMER_START_MAINLOOP | bool | false | start GStreamer loop in separate thread |
OPENCV_VIDEOIO_MFX_IMPL | num | | set specific MFX implementation (see MFX docs for enumeration) |
OPENCV_VIDEOIO_MFX_EXTRA_SURFACE_NUM | num | 1 | add extra surfaces to the surface pool |
OPENCV_VIDEOIO_MFX_POOL_TIMEOUT | num | 1 | timeout for waiting for free surface from the pool (in seconds) |
OPENCV_VIDEOIO_MFX_BITRATE_DIVISOR | num | 300 | this option allows to tune encoding bitrate (video quality/size) |
OPENCV_VIDEOIO_MFX_WRITER_TIMEOUT | num | 1 | timeout for encoding operation (in seconds) |
OPENCV_VIDEOIO_MSMF_ENABLE_HW_TRANSFORMS | bool | true | allow HW-accelerated transformations (DXVA) in MediaFoundation processing graph (may slow down camera probing process) |
OPENCV_DSHOW_DEBUG | non-null | | enable verbose logging in the DShow backend |
OPENCV_DSHOW_SAVEGRAPH_FILENAME | file path | | enable processing graph tump in the DShow backend |
OPENCV_VIDEOIO_V4L_RANGE_NORMALIZED | bool | false | use (0, 1) range for properties (V4L) |
OPENCV_VIDEOIO_V4L_SELECT_TIMEOUT | num | 10 | timeout for select call (in seconds) (V4L) |
OPENCV_VIDEOCAPTURE_DEBUG | bool | false | enable debug messages for VideoCapture |
OPENCV_VIDEOWRITER_DEBUG | bool | false | enable debug messages for VideoWriter |
⭐ OPENCV_VIDEOIO_DEBUG | bool | false | debug messages for both VideoCapture and VideoWriter |
videoio tests
name | type | default | description |
OPENCV_TEST_VIDEOIO_BACKEND_REQUIRE_FFMPEG | | | test app will exit if no FFmpeg backend is available |
OPENCV_TEST_V4L2_VIVID_DEVICE | file path | | path to VIVID virtual camera device for V4L2 test (e.g. /dev/video5 ) |
OPENCV_TEST_PERF_CAMERA_LIST | paths | | cameras to use in performance test (waitAny_V4L test) |
OPENCV_TEST_CAMERA_d_FPS | num | | fps to set for N-th camera (0-based index) (waitAny_V4L test) |
gapi
name | type | default | description |
⭐ GRAPH_DUMP_PATH | file path | | dump graph (dot format) |
PIPELINE_MODELS_PATH | dir path | | pipeline_modeling_tool sample application uses this var |
OPENCV_GAPI_INFERENCE_ENGINE_CORE_LIFETIME_WORKAROUND | bool | true (Windows, Apple), false (others) | similar to OPENCV_DNN_INFERENCE_ENGINE_CORE_LIFETIME_WORKAROUND |
gapi tests/samples
name | type | default | description |
PLAIDML_DEVICE | string | | specific to PlaidML backend test |
PLAIDML_TARGET | string | | specific to PlaidML backend test |
OPENCV_GAPI_ONNX_MODEL_PATH | dir path | | search location for ONNX models test |
OPENCV_TEST_FREETYPE_FONT_PATH | file path | | location of TrueType font for one of tests |
Links:
highgui
name | type | default | description |
OPENCV_LEGACY_WAITKEY | non-null | | switch waitKey return result (default behavior: return code & 0xff (or -1), legacy behavior: return code ) |
$XDG_RUNTIME_DIR | | | Wayland backend specific - create shared memory-mapped file for interprocess communication (named opencv-shared-?????? ) |
imgproc
name | type | default | description |
OPENCV_OPENCL_IMGPROC_MORPH_SPECIAL_KERNEL | bool | true (Apple), false (others) | use special OpenCL kernel for small morph kernel (Intel devices) |
OPENCV_GAUSSIANBLUR_CHECK_BITEXACT_KERNELS | bool | false | validate Gaussian kernels before running (src is CV_16U, bit-exact version) |
imgcodecs
name | type | default | description |
OPENCV_IMGCODECS_AVIF_MAX_FILE_SIZE | num | 64MB | limit input AVIF size |
OPENCV_IMGCODECS_WEBP_MAX_FILE_SIZE | num | 64MB | limit input WEBM size |
OPENCV_IO_MAX_IMAGE_PARAMS | num | 50 | limit maximum allowed number of parameters in imwrite and imencode |
OPENCV_IO_MAX_IMAGE_WIDTH | num | 1 << 20, limit input image size to avoid large memory allocations | |
OPENCV_IO_MAX_IMAGE_HEIGHT | num | 1 << 20 | |
OPENCV_IO_MAX_IMAGE_PIXELS | num | 1 << 30 | |
OPENCV_IO_ENABLE_OPENEXR | bool | true (set build option OPENCV_IO_FORCE_OPENEXR or use external OpenEXR), false (otherwise) | enable OpenEXR backend |
OPENCV_IO_ENABLE_JASPER | bool | true (set build option OPENCV_IO_FORCE_JASPER), false (otherwise) | enable Jasper backend |