PaddlePaddle/PaddleOCR · critical · RuntimeError

Cannot compile pse: {}, if your system is windows, you need

Error message

Cannot compile pse: {}, if your system is windows, you need to install all the default components of `desktop development using C++` in visual studio 2019+

What it means

RuntimeError raised at import time of ppocr.postprocess.pse_postprocess.pse when the package fails to compile its Cython/C++ extension in-place by shelling out to 'setup.py build_ext --inplace'. It means no working C/C++ toolchain (or broken environment) was available to build the PSE postprocessing module, which is required for PSE/ PSENet text detection.

Source

Thrown at ppocr/postprocess/pse_postprocess/pse/__init__.py:26

#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
import sys
import os
import subprocess

python_path = sys.executable

ori_path = os.getcwd()
os.chdir("ppocr/postprocess/pse_postprocess/pse")
if (
    subprocess.call("{} setup.py build_ext --inplace".format(python_path), shell=True)
    != 0
):
    raise RuntimeError(
        "Cannot compile pse: {}, if your system is windows, you need to install all the default components of `desktop development using C++` in visual studio 2019+".format(
            os.path.dirname(os.path.realpath(__file__))
        )
    )
os.chdir(ori_path)

from .pse import pse

View on GitHub (pinned to 2661c7c0ef)

Solutions

On Windows, install Visual Studio 2019+ with ALL default components of the 'Desktop development with C++' workload, then retry.
On Linux/macOS ensure a compiler and Python headers exist (apt install build-essential python3-dev) and that Cython is installed (pip install cython).
Build manually to see the real error: cd ppocr/postprocess/pse_postprocess/pse && python setup.py build_ext --inplace.
Delete stale .so/.pyd artifacts and rebuild if you switched Python versions.

Defensive patterns

Strategy: try-catch

Validate before calling

import shutil, subprocess, sys

def can_compile_pse() -> bool:
    compiler = shutil.which('cl') or shutil.which('gcc') or shutil.which('clang')
    if not compiler:
        return False
    r = subprocess.run([sys.executable, 'setup.py', 'build_ext', '--inplace'],
                       cwd='ppocr/postprocess/pse_postprocess/pse', capture_output=True)
    return r.returncode == 0

Try / catch

try:
    from ppocr.postprocess.pse_postprocess.pse import pse
except (RuntimeError, ImportError) as e:
    raise SystemExit(
        'PSE postprocess requires a C++ toolchain. '
        'Windows: install VS 2019+ with the "Desktop development with C++" workload. '
        'Linux: apt install build-essential python3-dev && pip install cython.'
    ) from e

Prevention

Provision build tools in the image/environment before running PSE models (build-essential + python3-dev + cython, or the full VS C++ workload).
Bake the compiled pse extension into Docker images at build time so runtime imports never compile.
Avoid PSE configs on machines without compilers; use DB configs instead.

When it happens

Trigger: Importing anything that pulls in pse_postprocess (i.e. running PSE detection training/inference) on a machine without a C++ compiler, without the Python dev headers, or on Windows without the 'Desktop development with C++' workload of Visual Studio 2019+.

Common situations: Fresh Windows machines with only VS BuildTools partial workloads; slim Docker images (python:slim) missing gcc; Cython not installed so setup.py fails; stale build artifacts from a different Python version.

Related errors

AI-assisted analysis of PaddlePaddle/PaddleOCR@2661c7c0ef (2026-08-14). Data as JSON: /api/errors/7df9c730722ae745. Report an issue: GitHub.