vllm.envs

Functions:

• __getattr__ –

  Gets environment variables lazily.

• compile_factors –

  Return env vars used for torch.compile cache keys.

• disable_envs_cache –

  Resets the environment variables cache. It could be used to isolate environments

• enable_envs_cache –

  Enables caching of environment variables. This is useful for performance

• env_list_with_choices –

  Create a lambda that validates environment variable

• env_set_with_choices –

  Creates a lambda which that validates environment variable

• env_with_choices –

  Create a lambda that validates environment variable against allowed choices.

• get_env_or_set_default –

  Create a lambda that returns an environment variable value if set,

• get_vllm_port –

  Get the port from VLLM_PORT environment variable.

• is_set –

  Check if an environment variable is explicitly set.

Attributes:

• VLLM_SKIP_MODEL_NAME_VALIDATION (bool) –

  If set, vLLM will skip model name validation in API requests.

VLLM_SKIP_MODEL_NAME_VALIDATION = False module-attribute

If set, vLLM will skip model name validation in API requests. This allows any model name to be accepted in the 'model' field of requests, making the server model-name agnostic. Useful for proxy/gateway scenarios.

__getattr__(name)

Gets environment variables lazily.

NOTE: After enable_envs_cache() invocation (which triggered after service initialization), all environment variables will be cached.

Source code in vllm/envs.py

def __getattr__(name: str):
    """Gets environment variables lazily.

    NOTE: After enable_envs_cache() invocation (which triggered after service
    initialization), all environment variables will be cached.
    """
    if name in environment_variables:
        return environment_variables[name]()
    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

_is_envs_cache_enabled()

Checked if getattr is wrapped with functools.cache.

Source code in vllm/envs.py

def _is_envs_cache_enabled() -> bool:
    """Checked if __getattr__ is wrapped with functools.cache."""
    global __getattr__
    return hasattr(__getattr__, "cache_clear")

_resolve_rust_cli_path()

Resolve the vllm-rs binary path.

Returns None unless VLLM_USE_RUST_FRONTEND or VLLM_USE_RUST_BENCH is enabled. When enabled, resolves VLLM_RUST_FRONTEND_PATH ("auto" by default) to the actual binary path.

Source code in vllm/envs.py

def _resolve_rust_cli_path() -> str | None:
    """Resolve the vllm-rs binary path.

    Returns None unless VLLM_USE_RUST_FRONTEND or VLLM_USE_RUST_BENCH is enabled.
    When enabled, resolves VLLM_RUST_FRONTEND_PATH ("auto" by default)
    to the actual binary path.
    """
    use_rust = bool(int(os.environ.get("VLLM_USE_RUST_FRONTEND", "0"))) or bool(
        int(os.environ.get("VLLM_USE_RUST_BENCH", "0"))
    )
    raw = os.environ.get("VLLM_RUST_FRONTEND_PATH", "auto")

    if not use_rust:
        if os.environ.get("VLLM_RUST_FRONTEND_PATH") is not None:
            logger.warning(
                "VLLM_RUST_FRONTEND_PATH is set without enabling "
                "VLLM_USE_RUST_FRONTEND or VLLM_USE_RUST_BENCH. "
                "Set one of them to 1 to use the vllm-rs binary."
            )
        return None

    if raw.lower() in ("auto", "1", "true"):
        pkg_dir = os.path.dirname(os.path.abspath(__file__))
        candidate = os.path.join(pkg_dir, "vllm-rs")
        if os.path.isfile(candidate) and os.access(candidate, os.X_OK):
            return candidate

        raise FileNotFoundError(
            "VLLM_RUST_FRONTEND_PATH=auto but the vllm-rs binary was "
            f"not found at {candidate}. "
            "Build with setuptools-rust or set the path explicitly."
        )
    return raw

compile_factors()

Return env vars used for torch.compile cache keys.

Start with every known vLLM env var; drop entries in ignored_factors; hash everything else. This keeps the cache key aligned across workers.

Source code in vllm/envs.py

def compile_factors() -> dict[str, object]:
    """Return env vars used for torch.compile cache keys.

    Start with every known vLLM env var; drop entries in `ignored_factors`;
    hash everything else. This keeps the cache key aligned across workers."""
    ignored_factors: set[str] = {
        "MAX_JOBS",
        "VLLM_TRITON_JIT_WARMUP_NUM_THREADS",
        "VLLM_RPC_BASE_PATH",
        "VLLM_USE_MODELSCOPE",
        "VLLM_RINGBUFFER_WARNING_INTERVAL",
        "VLLM_DEBUG_DUMP_PATH",
        "VLLM_PORT",
        "VLLM_CACHE_ROOT",
        # Runtime memory-plan persistence; does not affect compiled graphs.
        "VLLM_ENABLE_STARTUP_PLAN",
        # Location-only derived paths: where a cache/config directory lives
        # cannot affect compiled artifacts, and hashing them means relocating
        # HOME or the XDG roots silently invalidates every compile cache
        # (VLLM_CACHE_ROOT above and VLLM_FLASHINFER_AUTOTUNE_CACHE_DIR below
        # are already ignored for the same reason).
        "VLLM_XLA_CACHE_PATH",
        "VLLM_CONFIG_ROOT",
        "LD_LIBRARY_PATH",
        "VLLM_SERVER_DEV_MODE",
        "VLLM_DP_MASTER_IP",
        "VLLM_DP_MASTER_PORT",
        "VLLM_NIXL_SIDE_CHANNEL_HOST",
        "VLLM_RANDOMIZE_DP_DUMMY_INPUTS",
        "VLLM_MODEL_REDIRECT_PATH",
        "VLLM_HOST_IP",
        "VLLM_RAY_BUNDLE_INDICES",
        "VLLM_CHAT_TEMPLATE_FUEL",
        "VLLM_ELASTIC_EP_SCALE_UP_LAUNCH",
        "VLLM_FORCE_AOT_LOAD",
        "S3_ACCESS_KEY_ID",
        "S3_SECRET_ACCESS_KEY",
        "S3_ENDPOINT_URL",
        # Credential; never affects compiled artifacts and must not be
        # persisted in cache_key_factors.json.
        "VLLM_API_KEY",
        "VLLM_USAGE_STATS_SERVER",
        "VLLM_NO_USAGE_STATS",
        "VLLM_DO_NOT_TRACK",
        "VLLM_LOGGING_LEVEL",
        "VLLM_LOGGING_PREFIX",
        "VLLM_LOGGING_STREAM",
        "VLLM_LOGGING_CONFIG_PATH",
        "VLLM_LOGGING_COLOR",
        "VLLM_LOG_STATS_INTERVAL",
        "VLLM_DEBUG_LOG_API_SERVER_RESPONSE",
        "VLLM_TUNED_CONFIG_FOLDER",
        "VLLM_FLASHINFER_AUTOTUNE_CACHE_DIR",
        "VLLM_FLASHINFER_AUTOTUNE_SKIP_OPS",
        "VLLM_HTTP_TIMEOUT_KEEP_ALIVE",
        "VLLM_HTTP_MAX_REQUEST_BODY_SIZE",
        "VLLM_EXECUTE_MODEL_TIMEOUT_SECONDS",
        "VLLM_WORKER_SHUTDOWN_TIMEOUT_SECONDS",
        "VLLM_KEEP_ALIVE_ON_ENGINE_DEATH",
        "VLLM_IMAGE_FETCH_TIMEOUT",
        "VLLM_VIDEO_FETCH_TIMEOUT",
        "VLLM_AUDIO_FETCH_TIMEOUT",
        "VLLM_MEDIA_CACHE",
        "VLLM_MEDIA_CACHE_MAX_SIZE_MB",
        "VLLM_MEDIA_CACHE_TTL_HOURS",
        "VLLM_MEDIA_FETCH_MAX_RETRIES",
        "VLLM_MEDIA_URL_ALLOW_REDIRECTS",
        "VLLM_MEDIA_LOADING_THREAD_COUNT",
        "VLLM_MAX_AUDIO_CLIP_FILESIZE_MB",
        "VLLM_MAX_AUDIO_DECODE_DURATION_S",
        "VLLM_MAX_AUDIO_DECODE_BYTES",
        "VLLM_MAX_AUDIO_PREPROCESS_WORKERS",
        "VLLM_MAX_EMBED_DECODE_BYTES",
        "VLLM_MAX_IMAGE_PIXELS",
        "VLLM_MAX_MEDIA_REQUEST_DECODE_BYTES",
        "VLLM_MAX_MEDIA_REQUEST_DOWNLOAD_SIZE_MB",
        "VLLM_VIDEO_LOADER_BACKEND",
        "VLLM_MEDIA_CONNECTOR",
        "VLLM_OBJECT_STORAGE_SHM_BUFFER_NAME",
        "VLLM_ASSETS_CACHE",
        "VLLM_ASSETS_CACHE_MODEL_CLEAN",
        "VLLM_WORKER_MULTIPROC_METHOD",
        "VLLM_ENABLE_V1_MULTIPROCESSING",
        "VLLM_V1_OUTPUT_PROC_CHUNK_SIZE",
        "VLLM_CPU_KVCACHE_SPACE",
        "VLLM_CPU_MOE_PREPACK",
        "VLLM_ZENTORCH_WEIGHT_PREPACK",
        "VLLM_TEST_FORCE_LOAD_FORMAT",
        "VLLM_RELOAD_MODE",
        "VLLM_ENABLE_CUDA_COMPATIBILITY",
        "VLLM_CUDA_COMPATIBILITY_PATH",
        "VLLM_SKIP_MODEL_NAME_VALIDATION",
        "LOCAL_RANK",
        "CUDA_VISIBLE_DEVICES",
        "NO_COLOR",
        "VLLM_SKIP_VERSION_SUFFIX",
        "FORCE_COLOR",
        "VLLM_REQUEST_BODY_LOG_LEVEL",
    }

    from vllm.config.utils import normalize_value

    factors: dict[str, object] = {}
    for factor, getter in environment_variables.items():
        if factor in ignored_factors:
            continue

        try:
            raw = getter()
        except Exception as exc:  # pragma: no cover - defensive logging
            logger.warning(
                "Skipping environment variable %s while hashing compile factors: %s",
                factor,
                exc,
            )
            continue

        factors[factor] = normalize_value(raw)

    ray_noset_env_vars = [
        # Refer to
        # https://github.com/ray-project/ray/blob/c584b1ea97b00793d1def71eaf81537d70efba42/python/ray/_private/accelerators/nvidia_gpu.py#L11
        # https://github.com/ray-project/ray/blob/c584b1ea97b00793d1def71eaf81537d70efba42/python/ray/_private/accelerators/amd_gpu.py#L11
        # https://github.com/ray-project/ray/blob/b97d21dab233c2bd8ed7db749a82a1e594222b5c/python/ray/_private/accelerators/amd_gpu.py#L10
        # https://github.com/ray-project/ray/blob/c584b1ea97b00793d1def71eaf81537d70efba42/python/ray/_private/accelerators/npu.py#L12
        # https://github.com/ray-project/ray/blob/c584b1ea97b00793d1def71eaf81537d70efba42/python/ray/_private/accelerators/hpu.py#L12
        # https://github.com/ray-project/ray/blob/c584b1ea97b00793d1def71eaf81537d70efba42/python/ray/_private/accelerators/neuron.py#L14
        # https://github.com/ray-project/ray/blob/c584b1ea97b00793d1def71eaf81537d70efba42/python/ray/_private/accelerators/tpu.py#L38
        # https://github.com/ray-project/ray/blob/c584b1ea97b00793d1def71eaf81537d70efba42/python/ray/_private/accelerators/intel_gpu.py#L10
        # https://github.com/ray-project/ray/blob/c584b1ea97b00793d1def71eaf81537d70efba42/python/ray/_private/accelerators/rbln.py#L10
        "RAY_EXPERIMENTAL_NOSET_CUDA_VISIBLE_DEVICES",
        "RAY_EXPERIMENTAL_NOSET_ROCR_VISIBLE_DEVICES",
        "RAY_EXPERIMENTAL_NOSET_HIP_VISIBLE_DEVICES",
        "RAY_EXPERIMENTAL_NOSET_ASCEND_RT_VISIBLE_DEVICES",
        "RAY_EXPERIMENTAL_NOSET_HABANA_VISIBLE_MODULES",
        "RAY_EXPERIMENTAL_NOSET_NEURON_RT_VISIBLE_CORES",
        "RAY_EXPERIMENTAL_NOSET_TPU_VISIBLE_CHIPS",
        "RAY_EXPERIMENTAL_NOSET_ONEAPI_DEVICE_SELECTOR",
        "RAY_EXPERIMENTAL_NOSET_RBLN_RT_VISIBLE_DEVICES",
    ]

    for var in ray_noset_env_vars:
        factors[var] = normalize_value(os.getenv(var))

    return factors

disable_envs_cache()

Resets the environment variables cache. It could be used to isolate environments between unit tests.

Source code in vllm/envs.py

def disable_envs_cache() -> None:
    """Resets the environment variables cache. It could be used to isolate environments
    between unit tests.
    """
    global __getattr__
    # If __getattr__ is wrapped by functions.cache, unwrap the caching layer.
    if _is_envs_cache_enabled():
        assert hasattr(__getattr__, "__wrapped__")
        __getattr__ = __getattr__.__wrapped__

enable_envs_cache()

Enables caching of environment variables. This is useful for performance reasons, as it avoids the need to re-evaluate environment variables on every call.

NOTE: Currently, it's invoked after service initialization to reduce runtime overhead. This also means that environment variables should NOT be updated after the service is initialized.

Source code in vllm/envs.py

def enable_envs_cache() -> None:
    """Enables caching of environment variables. This is useful for performance
    reasons, as it avoids the need to re-evaluate environment variables on
    every call.

    NOTE: Currently, it's invoked after service initialization to reduce
    runtime overhead. This also means that environment variables should NOT
    be updated after the service is initialized.
    """
    if _is_envs_cache_enabled():
        # Avoid wrapping functools.cache multiple times
        return
    # Tag __getattr__ with functools.cache
    global __getattr__
    __getattr__ = functools.cache(__getattr__)

    # Cache all environment variables
    for key in environment_variables:
        __getattr__(key)

env_list_with_choices(env_name, default, choices, case_sensitive=True)

Create a lambda that validates environment variable containing comma-separated values against allowed choices

Parameters:

• env_name

  (str) –

  Name of the environment variable

• default

  (list[str]) –

  Default list of values if not set

• choices

  (list[str] | Callable[[], list[str]]) –

  List of valid string options or callable that returns list

• case_sensitive

  (bool, default: True ) –

  Whether validation should be case sensitive

Returns:

• Callable[[], list[str]] –

  Lambda function for environment_variables

• Callable[[], list[str]] –

  dict that returns list of strings

Source code in vllm/envs.py

def env_list_with_choices(
    env_name: str,
    default: list[str],
    choices: list[str] | Callable[[], list[str]],
    case_sensitive: bool = True,
) -> Callable[[], list[str]]:
    """Create a lambda that validates environment variable
    containing comma-separated values against allowed choices

    Args:
        env_name: Name of the environment variable
        default: Default list of values if not set
        choices: List of valid string options or callable that returns list
        case_sensitive: Whether validation should be case sensitive

    Returns:
        Lambda function for environment_variables
        dict that returns list of strings

    """

    def _get_validated_env_list() -> list[str]:
        value = os.getenv(env_name)
        if value is None:
            return default

        # Split comma-separated values and strip whitespace
        values = [v.strip() for v in value.split(",") if v.strip()]

        if not values:
            return default

        # Resolve choices if it's a callable (for lazy loading)
        actual_choices = choices() if callable(choices) else choices

        # Validate each value
        for val in values:
            if not case_sensitive:
                check_value = val.lower()
                check_choices = [choice.lower() for choice in actual_choices]
            else:
                check_value = val
                check_choices = actual_choices

            if check_value not in check_choices:
                raise ValueError(
                    f"Invalid value '{val}' in {env_name}. "
                    f"Valid options: {actual_choices}."
                )

        return values

    return _get_validated_env_list

env_set_with_choices(env_name, default, choices, case_sensitive=True)

Creates a lambda which that validates environment variable containing comma-separated values against allowed choices which returns choices as a set.

Source code in vllm/envs.py

def env_set_with_choices(
    env_name: str,
    default: list[str],
    choices: list[str] | Callable[[], list[str]],
    case_sensitive: bool = True,
) -> Callable[[], set[str]]:
    """Creates a lambda which that validates environment variable
    containing comma-separated values against allowed choices which
    returns choices as a set.
    """

    def _get_validated_env_set() -> set[str]:
        return set(env_list_with_choices(env_name, default, choices, case_sensitive)())

    return _get_validated_env_set

env_with_choices(env_name, default, choices, case_sensitive=True)

Create a lambda that validates environment variable against allowed choices.

Parameters:

• env_name

  (str) –

  Name of the environment variable

• default

  (str | None) –

  Default value if not set (can be None)

• choices

  (list[str] | Callable[[], list[str]]) –

  List of valid string options or callable that returns list

• case_sensitive

  (bool, default: True ) –

  Whether validation should be case sensitive

Returns:

• Callable[[], str | None] –

  Lambda function for environment_variables dict

Source code in vllm/envs.py

def env_with_choices(
    env_name: str,
    default: str | None,
    choices: list[str] | Callable[[], list[str]],
    case_sensitive: bool = True,
) -> Callable[[], str | None]:
    """Create a lambda that validates environment variable against allowed choices.

    Args:
        env_name: Name of the environment variable
        default: Default value if not set (can be None)
        choices: List of valid string options or callable that returns list
        case_sensitive: Whether validation should be case sensitive

    Returns:
        Lambda function for environment_variables dict

    """

    def _get_validated_env() -> str | None:
        value = os.getenv(env_name)
        if value is None:
            return default

        # Resolve choices if it's a callable (for lazy loading)
        actual_choices = choices() if callable(choices) else choices

        if not case_sensitive:
            check_value = value.lower()
            check_choices = [choice.lower() for choice in actual_choices]
        else:
            check_value = value
            check_choices = actual_choices

        if check_value not in check_choices:
            raise ValueError(
                f"Invalid value '{value}' for {env_name}. "
                f"Valid options: {actual_choices}."
            )

        return value

    return _get_validated_env

get_env_or_set_default(env_name, default_factory)

Create a lambda that returns an environment variable value if set, or generates and sets a default value using the provided factory function.

Source code in vllm/envs.py

def get_env_or_set_default(
    env_name: str,
    default_factory: Callable[[], str],
) -> Callable[[], str]:
    """Create a lambda that returns an environment variable value if set,
    or generates and sets a default value using the provided factory function.
    """

    def _get_or_set_default() -> str:
        value = os.getenv(env_name)
        if value is not None:
            return value

        default_value = default_factory()
        os.environ[env_name] = default_value
        return default_value

    return _get_or_set_default

get_vllm_port()

Get the port from VLLM_PORT environment variable.

Returns:

• int | None –

  The port number as an integer if VLLM_PORT is set, None otherwise.

Raises:

• ValueError –

  If VLLM_PORT is a URI, suggest k8s service discovery issue.

Source code in vllm/envs.py

def get_vllm_port() -> int | None:
    """Get the port from VLLM_PORT environment variable.

    Returns:
        The port number as an integer if VLLM_PORT is set, None otherwise.

    Raises:
        ValueError: If VLLM_PORT is a URI, suggest k8s service discovery issue.

    """
    if "VLLM_PORT" not in os.environ:
        return None

    port = os.getenv("VLLM_PORT", "0")

    try:
        return int(port)
    except ValueError as err:
        from urllib3.util import parse_url

        parsed = parse_url(port)
        if parsed.scheme:
            raise ValueError(
                f"VLLM_PORT '{port}' appears to be a URI. "
                "This may be caused by a Kubernetes service discovery issue,"
                "check the warning in: https://docs.vllm.ai/en/latest/configuration/env_vars.html"
            ) from None
        raise ValueError(f"VLLM_PORT '{port}' must be a valid integer") from err

is_set(name)

Check if an environment variable is explicitly set.

Source code in vllm/envs.py

def is_set(name: str):
    """Check if an environment variable is explicitly set."""
    if name in environment_variables:
        return name in os.environ
    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")