vllm-project/vllm

[RFC]: Limit the use of envvars in vLLM

Open

#25700 opened on Sep 25, 2025

View on GitHub
 (17 comments) (5 reactions) (2 assignees)Python (80,034 stars) (16,816 forks)batch import
RFCgood first issue

Description

Motivation.

vLLM's envvars are on the edge of getting out of control. There are many envvars should instead be configs. Like the attention backend, all2all kernel backend, and even there is a flag to control KV cache layout. envvars are evil because:

  1. It is equivalent of using global variables everywhere in the code, which is a bad programming practice.
  2. envvars have no advanced structure like, hierarchy, typechecks, etc.

In summary, I think envvars are the kind of thing that is very easy to add so people tend to add envvars as the shortest path to implement their feature, but this can quickly becomes unmanageable and makes the project very hard to use.

Proposed Change.

I think we should:

  1. Spend some effort on reviewing the current envvars and move many of them to configs.
  2. Have very strict bar on what can be an envvar and question every new envvars in vllm.

Feedback Period.

No response

CC List.

No response

Any Other Things.

No response

Before submitting a new issue...

  • Make sure you already searched for relevant issues, and asked the chatbot living at the bottom right corner of the documentation page, which can answer lots of frequently asked questions.

Contributor guide

Tech stack
python
Domain
backenddeveloper experience
Issue type
refactor
DifficultyEstimated implementation difficulty for a new contributor, from 1 for very small changes to 5 for expert-level work.
4
Estimated timeA rough time range for an experienced contributor to investigate, implement, test, and prepare a pull request.
over 1 week
Activity statusHow available the issue appears right now: fresh, active, stale, blocked, or waiting on maintainer input.
active
ClarityHow clearly the issue explains the expected change, acceptance criteria, and next step.
clear
Prerequisites
Understanding of vLLM architecture
Newbie friendlinessA 1-100 score estimating how approachable this issue is for first-time contributors.
20
Research direction
Investigate the current use of environment variables in vLLM by searching for `os.environ` calls or envvar definitions (likely in `vllm/envs.py`). Review the existing configuration system (e.g., `vllm/config.py`) to understand how configs are structured. Engage with the assignees and commenters on issue #25700 to align on which envvars to convert first. The goal is to create a plan or list of envvars that should become configs.