PaddlePaddle/PaddleOCR · error · RuntimeError

Environment Variable CUDA_VISIBLE_DEVICES is not set correct

Error message

Environment Variable CUDA_VISIBLE_DEVICES is not set correctly. If you wanna use gpu, please set CUDA_VISIBLE_DEVICES via export CUDA_VISIBLE_DEVICES=cuda_device_id.

What it means

Raised during __init__ of the structure_system (PP-Structure end-to-end) hubserving module when use_gpu=True and the CUDA_VISIBLE_DEVICES check fails. The check (read env var, int() the first char) sits in a bare try/except, so unset/empty/non-digit values all raise this RuntimeError.

Source

Thrown at deploy/hubserving/structure_system/module.py:64

    type="cv/structure_system",
)
class StructureSystem(hub.Module):
    def _initialize(self, use_gpu=False, enable_mkldnn=False):
        """
        initialize with the necessary elements
        """
        cfg = self.merge_configs()

        cfg.use_gpu = use_gpu
        if use_gpu:
            try:
                _places = os.environ["CUDA_VISIBLE_DEVICES"]
                int(_places[0])
                print("use gpu: ", use_gpu)
                print("CUDA_VISIBLE_DEVICES: ", _places)
                cfg.gpu_mem = 8000
            except:
                raise RuntimeError(
                    "Environment Variable CUDA_VISIBLE_DEVICES is not set correctly. If you wanna use gpu, please set CUDA_VISIBLE_DEVICES via export CUDA_VISIBLE_DEVICES=cuda_device_id."
                )
        cfg.ir_optim = True
        cfg.enable_mkldnn = enable_mkldnn

        self.table_sys = PPStructureSystem(cfg)

    def merge_configs(self):
        # default cfg
        backup_argv = copy.deepcopy(sys.argv)
        sys.argv = sys.argv[:1]
        cfg = parse_args()

        update_cfg_map = vars(read_params())

        for key in update_cfg_map:
            cfg.__setattr__(key, update_cfg_map[key])

View on GitHub (pinned to 2661c7c0ef)

Solutions

export CUDA_VISIBLE_DEVICES=0 and then initialize with use_gpu=True.
Initialize with use_gpu=False for CPU deployments.
Verify the variable in the same shell/process that launches the service.

Example fix

# before
mod = StructModule(use_gpu=True)  # env unset -> RuntimeError

# after
import os
os.environ["CUDA_VISIBLE_DEVICES"] = "0"
mod = StructModule(use_gpu=True)
# or
mod = StructModule(use_gpu=False)

Defensive patterns

Strategy: validation

Validate before calling

import os

v = os.environ.get("CUDA_VISIBLE_DEVICES")
if USE_GPU and (not v or not v[0].isdigit()):
    raise SystemExit("GPU requested but CUDA_VISIBLE_DEVICES invalid; export CUDA_VISIBLE_DEVICES=0")
mod = StructModule(use_gpu=USE_GPU)

Try / catch

try:
    mod = StructModule(use_gpu=True)
except RuntimeError as e:
    if "CUDA_VISIBLE_DEVICES" in str(e):
        mod = StructModule(use_gpu=False)
    else:
        raise

Prevention

Make GPU env part of the deployment checklist for PP-Structure services.
Fail fast at startup with a clear message instead of crashing at module init.
Pin the env var in container specs so it is never shell-dependent.

When it happens

Trigger: Constructing the structure system module with use_gpu=True while CUDA_VISIBLE_DEVICES is missing or malformed.

Common situations: PP-Structure serving on GPU hardware where the device visibility env var was never exported; containers missing the -e CUDA_VISIBLE_DEVICES flag.

Related errors

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