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 by the kie_ser_re (SER + RE chained) hub module at init when use_gpu=True and CUDA_VISIBLE_DEVICES is unset or its first character cannot be parsed as int. Like the kie_ser module, a bare except wraps both the env lookup and int(_places[0]), collapsing distinct failures (missing var, empty string, "all") into one message. Pure environment configuration error raised as RuntimeError before any predictor loads.

Source

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

    type="cv/KIE_SER_RE",
)
class KIESerRE(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.ser_re_predictor = SerRePredictor(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:

View on GitHub (pinned to 2661c7c0ef)

Solutions

  1. export CUDA_VISIBLE_DEVICES=0 (or the desired GPU id) in the shell/service environment and restart
  2. Add the env to the container/pod spec: docker run -e CUDA_VISIBLE_DEVICES=0 --gpus all ...
  3. If running CPU-only, keep use_gpu=False
  4. Use a numeric value ("0", "0,1") - not "all", "", or "-1"

Example fix

# before
hub serving start -m kie_ser_re --use_gpu true  # env unset -> RuntimeError

# after
export CUDA_VISIBLE_DEVICES=0
hub serving start -m kie_ser_re --use_gpu true
Defensive patterns

Strategy: validation

Validate before calling

import os

def gpu_env_valid() -> bool:
    v = os.environ.get("CUDA_VISIBLE_DEVICES")
    return v is not None and len(v) > 0 and v[0].isdigit()

if USE_GPU and not gpu_env_valid():
    raise SystemExit("export CUDA_VISIBLE_DEVICES=<gpu_id> before starting kie_ser_re with GPU")

Try / catch

try:
    module = SerRePredictorModule(use_gpu=True)
except RuntimeError as e:
    if "CUDA_VISIBLE_DEVICES" in str(e):
        raise SystemExit("Fix env: export CUDA_VISIBLE_DEVICES=0, then restart the service")
    raise

Prevention

When it happens

Trigger: Launching the kie_ser_re hub service with use_gpu=True in a shell/container where CUDA_VISIBLE_DEVICES was never exported; value set to "" (entrypoint script setting it empty); "all" or "NoDevFiles" on driver 450+/470+ where int() of the first char fails.

Common situations: GPU Docker deployments missing -e CUDA_VISIBLE_DEVICES=0; systemd units without Environment=; upgrading NVIDIA drivers which now advertise "all"; switching a CPU-validated deployment to GPU without revisiting env setup.

Related errors

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