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 ocr_cls hubserving module when use_gpu=True but the CUDA_VISIBLE_DEVICES environment variable cannot be validated. The code reads os.environ["CUDA_VISIBLE_DEVICES"] and does int(_places[0]) inside a bare try/except, so a KeyError (variable unset/empty) or ValueError (first char not a digit, e.g. an empty string) both collapse into this RuntimeError.

Source

Thrown at deploy/hubserving/ocr_cls/module.py:60

    type="cv/text_angle_cls",
)
class OCRCls(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.text_classifier = TextClassifier(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 (a plain device id) before starting the service, then re-run with use_gpu=True.
  2. If no GPU is intended, pass use_gpu=False when instantiating the module.
  3. Verify with: python -c "import os; v=os.environ.get('CUDA_VISIBLE_DEVICES',''); print(v, v[:1].isdigit())".

Example fix

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

# after
import os
os.environ["CUDA_VISIBLE_DEVICES"] = "0"
mod = ClsModule(use_gpu=True)
# or, on CPU:
mod = ClsModule(use_gpu=False)
Defensive patterns

Strategy: validation

Validate before calling

import os

def cuda_env_ok() -> bool:
    v = os.environ.get("CUDA_VISIBLE_DEVICES", "")
    return bool(v) and v[0].isdigit()

assert cuda_env_ok() or not USE_GPU, "set CUDA_VISIBLE_DEVICES=<id> or use use_gpu=False"

Try / catch

try:
    module = ClsModule(use_gpu=True)
except RuntimeError as e:
    if "CUDA_VISIBLE_DEVICES" in str(e):
        # fall back to CPU instead of crashing the service
        module = ClsModule(use_gpu=False)
    else:
        raise

Prevention

When it happens

Trigger: Constructing the module (or starting the hub serving container) with use_gpu=True while CUDA_VISIBLE_DEVICES is unset, set to an empty string, or starts with a non-digit character.

Common situations: Deploying the hubserving docker/service on a GPU machine without exporting CUDA_VISIBLE_DEVICES; CI shells that scrub environment variables; setting the variable to a value like "cuda:0" instead of "0".

Related errors

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