C++ Headers Not Found with pip install on MSYS2/Mingw64 for OpenBLAS

The error occurs because pip attempts to build OpenBLAS from source using a C compiler that cannot locate the necessary C++ standard library headers provided by MSYS2. This is not a Python issue but a toolchain configuration problem where the environment variables for include paths are missing or misconfigured during the compilation phase.

Understanding the MSYS2 Environment

MSYS2 provides multiple terminal environments, each with different default configurations. The most common mistake is running pip install inside the generic msys2_shell.cmd or the base MSYS2 shell. These shells use the msys-2.0.dll runtime and are designed for POSIX-like tools, not for compiling Windows native applications. To compile C++ code on Windows using MinGW-w64, you must use the specific terminal shortcut named UCRT64 or MINGW64. The MINGW64 shell sets up the correct PATH to point to /mingw64/bin, which contains the GCC and G++ compilers linked against the UCRT (Universal C Runtime) or MSVCRT. When you run which gcc in this shell, it should return /mingw64/bin/gcc.exe. If it returns /usr/bin/gcc, you are in the wrong shell, and header resolution will fail. For more details on building C code in similar cross-platform environments, see Building and Running C++ Code in WSL2 (Linux Debian) with Mingw - Not Always the Last One Running. While WSL2 is Linux-based, the principle of ensuring the correct compiler toolchain is active before invoking build systems remains identical.

Installing Required Development Packages

Before installing any Python package that requires compilation, you must ensure the underlying C++ development headers are present in your MSYS2 installation. Open your preferred MinGW64 terminal and execute the following command:

pacman -S mingw-w64-x86_64-toolchain
pacman -S mingw-w64-x86_64-gcc

This installs the GNU Compiler Collection and associated headers into the /mingw64/include directory. Specifically, look for files like cxxabi.h or bits/c++config.h in that path. If these files are missing, the C++ standard library is incomplete, and any package attempting to link C++ code will fail immediately. You may also need to install the specific BLAS/LAPACK development libraries if they are required as dependencies, though OpenBLAS usually bundles its own sources. However, having the base toolchain is non-negotiable.

Configuring the Build Environment

When pip builds OpenBLAS, it invokes a setup script that calls the system compiler. By default, this compiler might not know where to find the MSYS2-specific headers if the environment is not properly exported. You can verify your current include paths by running:

gcc -print-search-dirs | grep "programs: ="

If the output does not show /mingw64/lib/gcc/... or /mingw64/include/..., your PATH is incorrect. Ensure that /mingw64/bin appears before /usr/bin in your PATH variable. In the MinGW64 shell, this is handled automatically. If you are using an external IDE or a custom script, you may need to manually export the CXX and CC variables:

export CC=/mingw64/bin/gcc
export CXX=/mingw64/bin/g++

This forces the build system to use the correct compiler wrappers that understand the MSYS2/MinGW ABI. Without this, pip might fall back to a different compiler or fail to detect the C++ support entirely.

Resolving the Externally Managed Environment Error

Recent versions of Python (3.11+) enforce PEP 668, which prevents pip from modifying system-wide packages unless explicitly allowed. If you encounter the error ERROR:externally-managed-environment, you cannot simply ignore it by using --break-system-packages without understanding the risks. Instead, use a virtual environment. Create a virtual environment in your project directory:

python -m venv .venv
source .venv/bin/activate

Once activated, all subsequent pip install commands operate within this isolated scope, bypassing the externally managed check. This is the recommended practice for all Python projects. For more information on managing dependencies safely, refer to Error: Externally managed Environment,PIP. If you prefer not to use virtual environments, you can force the installation, but this is discouraged for production systems. Alternatively, consider using pipx for global CLI tools, though it is less suitable for library dependencies like OpenBLAS. See How to use pipx install -r? for context on alternative installation methods.

Final Verification

After successfully installing the package, verify that the C++ bindings are accessible. Create a simple test file test.cpp:

#include <iostream>
int main() {
    std::cout << "OpenBLAS installed correctly" << std::endl;
    return 0;
}

Compile it using the MinGW64 compiler:

g++ test.cpp -o test.exe
./test.exe

If this runs without errors, your toolchain is correctly configured, and the previous header issues were likely due to shell confusion or missing packages.

Frequently Asked Questions

Why does pip work in MSYS2 shell but fail in MinGW64 shell?

This is rare but possible if the MSYS2 shell has pre-installed binary wheels cached. Generally, pip fails in MSYS2 because the POSIX-style paths interfere with Windows-native compilers. Always prefer the MinGW64 shell for native Windows Python packages.

Can I use MSVC instead of MinGW for OpenBLAS?

Yes, but you must have Visual Studio Build Tools installed. Pip will detect the MSVC compiler if it is in the PATH. However, mixing MSVC and MinGW headers causes severe conflicts. Stick to one toolchain per environment.

What if I get 'libgfortran' not found errors?

OpenBLAS depends on Fortran libraries. Ensure you have installed mingw-w64-x86_64-gcc-fortran via pacman. The shared libraries must be in your system PATH or copied to the Python scripts directory.

Is it safe to use --break-system-packages?

No. It breaks Python's dependency isolation guarantees and can cause conflicts between system updates and pip-installed packages. Use virtual environments or conda instead.

How do I clear the pip cache if a build failed halfway?

Run pip cache purge to remove cached wheels and source distributions. This forces pip to re-download and rebuild the package, which can resolve intermittent build failures caused by corrupted downloads.