Tools

How to Install dlib for PyCharm on Windows, macOS and Linux

Tools · Published 2026-10-24

Macro view of a green circuit board with printed labels and small components
Printed labels and components on a circuit board, close up.

dlib is a C++ library with Python bindings, and the official package on PyPI is source code only, so pip install dlib compiles it on your machine and needs a C++ compiler plus CMake. The easiest route is a conda environment with conda install -c conda-forge dlib; otherwise install the build tools for your OS, run pip in the project's interpreter, and select that interpreter in PyCharm.

Why dlib is harder to install than most packages

Most popular packages publish wheels, prebuilt binaries for each platform and Python version, so pip only downloads and unpacks them. At the time of writing, the dlib project publishes only a source archive on PyPI (for version 20.0.1 the sole file is dlib-20.0.1.tar.gz). pip therefore has to build it: CMake configures the build, a C++ compiler compiles several hundred source files, and the result is packed into a wheel. That takes several minutes and fails with a long error if a tool is missing.

Unofficial prebuilt wheels exist from third parties under other package names. They can work, but they are not published by the dlib project, may lag behind releases and may be built with different options. Prefer conda-forge or building it yourself.

Whichever method you choose, install into the interpreter your PyCharm project uses. Check it under Settings (PyCharm › Settings on macOS) › Project: <name> › Python Interpreter, or in the status bar at the bottom right in PyCharm 2023.x and later.

Option 1 (easiest): conda-forge

conda-forge provides prebuilt dlib binaries for Windows, macOS and Linux, so no compiler is involved:

conda create -n faces -c conda-forge python=3.12 dlib
conda activate faces
python -c "import dlib; print(dlib.__version__)"

Then in PyCharm: Python Interpreter › Add Interpreter › Add Local Interpreter › Conda Environment, choose Use existing environment and select faces. Install the rest of your packages into the same environment, preferring conda-forge versions where they exist (for example opencv, numpy) and pip for anything else. Pick a Python version that conda-forge currently builds dlib for; if the solver reports a conflict, try one minor version lower.

Option 2: pip with build tools

If the project uses a virtualenv (PyCharm's default), install a compiler and CMake first.

Windows

  1. Install Visual Studio Build Tools (or Visual Studio Community) from Microsoft and select the workload Desktop development with C++. This provides the MSVC compiler and Windows SDK. Reboot if the installer asks.
  2. Install CMake from cmake.org and tick the option to add it to the PATH. Open a new terminal and confirm cmake --version works.
  3. In PyCharm's terminal (which activates the project venv), run python -m pip install dlib.

MinGW is not a substitute here; Python on Windows is built with MSVC and extensions should be too.

macOS

xcode-select --install      # Apple's command line tools (clang)
brew install cmake
python -m pip install dlib

This works on both Intel and Apple Silicon. If you mix Homebrew Python and the python.org build, make sure the venv was created from the one you intend to use.

Debian and Ubuntu

sudo apt update
sudo apt install build-essential cmake python3-dev
python -m pip install dlib

On Fedora, the equivalents are sudo dnf install gcc-c++ make cmake python3-devel. Optional speedups: installing BLAS/LAPACK development packages (for example libopenblas-dev liblapack-dev) lets dlib's build detect and use them.

What happens during the build

Recent dlib releases list cmake as a build requirement in pyproject.toml, so pip fetches a CMake binary from PyPI into its isolated build environment automatically. A system CMake is still a good idea: dlib's own setup script warns that copies of CMake bundled by Python package managers are sometimes broken and recommends an official one. The C++ compiler, however, is never installed by pip; that part is always up to you.

Building dlib 20.0.1 with Python 3.13 in a clean Linux container with g++ and CMake present succeeded but took several minutes, with pip printing Building wheel for dlib (pyproject.toml): still running... repeatedly. That is normal; do not interrupt it. Building on a machine with little memory can fail with the compiler being killed; close other programs or add swap.

Option 3: PyCharm's package manager

Installing dlib from the Python Packages tool window or the + button in interpreter settings runs the same pip build in the background, with the same requirements. It works once the tools above are installed, but when it fails the error is easier to read in the terminal, so use python -m pip install dlib there for the first attempt.

Verify the installation

Run this from PyCharm with the project interpreter:

import sys
import dlib

print("Python :", sys.version.split()[0])
print("Path   :", sys.executable)
print("dlib   :", dlib.__version__)
print("CUDA   :", dlib.DLIB_USE_CUDA)

detector = dlib.get_frontal_face_detector()
print("Face detector loaded:", type(detector).__name__)

It prints the Python version and interpreter path (which should match the PyCharm settings), the dlib version, whether dlib was compiled with CUDA, and confirms the bundled HOG face detector loads. In the test build described above it reported dlib 20.0.1 with CUDA : False. The detector works without any model file; landmark prediction and face recognition need the separate model files (such as shape_predictor_68_face_landmarks.dat) referenced in the dlib Python API documentation and examples.

Common errors and fixes

"CMake is not installed on your system!"

dlib's setup could not run cmake --version. Install CMake from cmake.org, your package manager or Homebrew, open a new terminal so PATH is reloaded, and restart PyCharm so its terminal picks up the new PATH as well. On Linux, which cmake shows which copy is found first; remove a broken one inside a Python or conda directory if that is what it points to.

"Failed building wheel for dlib" / "ERROR: Could not build wheels for dlib"

This line is only the summary; the cause is further up in the output. Scroll up to the first error:. Typical causes:

Installed, but import dlib fails in PyCharm

The package went into a different interpreter. Compare sys.executable from the script above with the interpreter in Settings, and install again with that interpreter's python -m pip. Also check Run › Edit Configurations for a per-script interpreter override.

face_recognition fails to install

The popular face_recognition package depends on dlib, so it hits exactly the same build requirements. Install dlib first using one of the methods above, then install face_recognition.

Summary

The dlib package on PyPI is compiled at install time, which requires a C++ compiler (Visual Studio Build Tools with "Desktop development with C++" on Windows, Xcode Command Line Tools on macOS, build-essential on Debian/Ubuntu) and CMake. If you can use conda, conda install -c conda-forge dlib avoids compiling altogether. Either way, install into the interpreter selected under Settings › Project › Python Interpreter and verify with import dlib; print(dlib.__version__). For general package management in the IDE, see installing Python packages in PyCharm.

Read next

More in Tools
A plain taped cardboard box on a weathered wooden tableTools

Install packages in PyCharm

Install Python packages in PyCharm via the Packages tool window, interpreter settings or pip; venv vs conda, requirements.txt and fixing import errors.

A strip of small window panes set into a turquoise wallTools

Install Tkinter for PyCharm

Tkinter ships with Python and cannot be installed with pip. Check for it, add it on Windows, macOS or Linux, and point PyCharm at an interpreter that has it.

An old leather luggage tag with a handwritten date, May 15-96Tools

Check a package version with pip

Check an installed Python package version with pip show, pip list and pip freeze, or in code with importlib.metadata, and compare versions safely.