Module not found, CUDA mismatches, a slow first run — these are the errors people hit most with RetinaFace, and each one has a clear fix.
Most RetinaFace problems fall into a small set of recurring patterns, and almost all of them come from environment setup rather than the detector itself. Work through the ones below in order and you will clear the overwhelming majority of issues without much fuss.
Module or import not found
The classic first error is an import that fails because the package is not installed in the environment you are actually running. Nine times out of ten this means you installed it into one environment and launched Python from another. Confirm your virtual environment is active, reinstall the package inside it, and check that the interpreter you are running is the same one you installed into. Mismatched environments are the single most common cause of this message.
CUDA or GPU version mismatch
If you are trying to use a GPU and see errors mentioning CUDA, the GPU toolkit on your system and the build expecting it are out of step. The simplest path is to first confirm RetinaFace works on the CPU, which removes the GPU from the equation entirely. Once CPU detection runs cleanly, line up the GPU toolkit version with what your build expects. Trying to fix the GPU path before the CPU path works just adds variables to the problem.
The first run is slow
A long pause on the very first detection is usually not an error at all. Some components initialise once — loading weights, warming up libraries — and that cost is paid a single time. Subsequent runs are far quicker. If only your first detection feels slow and everything after is fast, that is expected behaviour, not a bug to chase.
No faces detected in an obvious image
When RetinaFace returns nothing on an image that clearly contains a face, check three things. First, confirm the image actually loaded — a path typo produces an empty array that silently yields no detections. Second, look at your confidence threshold; if it is set very high, genuine faces can be filtered out. Third, consider the face size: extremely small or heavily cropped faces are harder, so lowering the threshold or using a larger input can help.
Out-of-memory errors
Memory errors typically appear when processing very large images or long batches. Resize oversized images before detection, process files one at a time rather than loading hundreds into memory at once, and if you are on a GPU with limited memory, reduce the batch size. These adjustments solve the vast majority of memory complaints without any change to the detector.
When the file is blocked on Windows
Windows occasionally blocks a freshly downloaded file. If the application will not start at all, confirm you obtained it from the official source, then unblock the file through its properties or re-download it cleanly. This is a security feature doing its job, not a fault in RetinaFace, and clearing it takes only a moment.
Still stuck?
If none of the above applies, isolate the problem by reducing it to the smallest case: a single known-good image, the CPU path, default settings. A minimal reproduction almost always reveals which layer is at fault, and it makes any help you seek far faster to provide.