vllm serve flags

Code version: vLLM @ 3e44c0d · 2026-10-22

Use this page in two ways. To learn how the parser works and which defaults are real, read the first four sections. To look up one flag, go to All flags, or search for its name. The script tools/gen_serve_flags.py makes the big tables from the parser code. The text above the tables is written by hand from the code.

How a config field becomes a flag#

vllm serve builds its parser in make_arg_parser. It adds five arguments by hand: the positional model_tag, --headless, --api-server-count, --config and --grpc. Then it adds the front-end flags and the engine flags (vllm/entrypoints/common/cli_args.py:429-466):

    parser = FrontendArgs.add_cli_args(parser)
    parser = AsyncEngineArgs.add_cli_args(parser)

The engine flags come from EngineArgs.add_cli_args. For each config class, it calls get_kwargs(XConfig), makes one argument group with the class name as its title, and adds one flag per field. The flag name is written by hand. The type, default, choices and help come from the field. Sometimes the code replaces the field default. In this excerpt, three scheduler flags get the default None:

        scheduler_kwargs = get_kwargs(SchedulerConfig)
        scheduler_group = parser.add_argument_group(
            title="SchedulerConfig",
            description=SchedulerConfig.__doc__,
        )
        scheduler_group.add_argument(
            "--max-num-batched-tokens",
            **{
                **scheduler_kwargs["max_num_batched_tokens"],
                "default": None,
            },
        )
        scheduler_group.add_argument(
            "--max-num-scheduled-tokens",
            **{
                **scheduler_kwargs["max_num_scheduled_tokens"],
                "default": None,
            },
        )
        scheduler_group.add_argument(
            "--max-num-seqs",
            **{
                **scheduler_kwargs["max_num_seqs"],
                "default": None,
            },
        )

get_kwargs returns a copy of the cached result of _compute_kwargs (vllm/engine/arg_utils.py:324, vllm/engine/arg_utils.py:443-453). _compute_kwargs reads each dataclass field (vllm/engine/arg_utils.py:324-440):

• Default: the field default, or the result of its default factory (vllm/engine/arg_utils.py:339-352).
• Help: the string literal after the field, read by get_attr_docs (vllm/engine/arg_utils.py:355-356, vllm/config/utils.py:201-215). The parser reads these strings only when the command line contains --help (or when mkdocs is loaded), because that is slow (vllm/engine/arg_utils.py:285-288, vllm/engine/arg_utils.py:327).
• Type: from the type hint. A dataclass type takes JSON. A bool gets BooleanOptionalAction (a bool | str | None field takes an optional text value instead). A Literal gives the choices. A list, tuple or set takes several values. Some int fields accept 1k, 2M or 1G (vllm/engine/arg_utils.py:367-425).

Flag pairs: --enable-x and --disable-x#

FlexibleArgumentParser replaces BooleanOptionalAction with EnableDisableAction (vllm/utils/argparse_utils.py:179). For a flag that starts with --enable-, it adds the opposite --disable- flag, and the reverse. The form --no-enable-x still works, but --help does not show it (vllm/utils/argparse_utils.py:120-151). Other boolean flags get the normal pair, for example --enforce-eager and --no-enforce-eager.

Other parser rules#

• Dashes and underscores. --max_num_seqs and --max-num-seqs are the same flag. The parser changes _ to - in the flag name (vllm/utils/argparse_utils.py:374-394).
• JSON flags. A flag that takes a dataclass also accepts its keys one by one, for example -cc.mode=3 (vllm/config/vllm.py:405-406, vllm/utils/argparse_utils.py:462-491).
• Optimization level. -O3 is short for --optimization-level 3 (vllm/utils/argparse_utils.py:395-399).
• Config file. --config file.yaml reads flags from a YAML file (vllm/utils/argparse_utils.py:371-372).
• Help by group. --help=ModelConfig shows one group, and --help=all shows all flags (vllm/utils/argparse_utils.py:384-386, vllm/utils/argparse_utils.py:241-252).

The model: positional, not --model#

Give the model as the first positional argument: vllm serve Qwen/Qwen3-0.6B. The positional value goes into args.model (vllm/entrypoints/cli/serve.py:55-57). If you write --model X, the parser logs a warning that the option will be removed, and moves X to the front (vllm/utils/argparse_utils.py:324-353). With no model, the default is Qwen/Qwen3-0.6B (vllm/config/model.py:155). vllm serve --help does not list --model, because add_cli_args skips it when the command line contains both serve and --help (vllm/engine/arg_utils.py:961-962).

How the flags reach VllmConfig#

1. AsyncEngineArgs.from_cli_args(args) copies each parsed value into the EngineArgs field of the same name (vllm/entrypoints/launchers/api_server/entry.py:52, vllm/engine/arg_utils.py:1962-1970).
2. create_engine_config(usage_context=OPENAI_API_SERVER) builds the sub-configs (vllm/entrypoints/launchers/api_server/entry.py:82). On the way, it replaces the None defaults. Chunked prefill and prefix caching come from the model (vllm/engine/arg_utils.py:2275), and the scheduler limits come from the GPU memory (vllm/engine/arg_utils.py:2631-2635).
3. It makes one VllmConfig (vllm/engine/arg_utils.py:2870). VllmConfig.__post_init__ checks the sub-configs together and sets more defaults, for example the compilation mode and async scheduling. See Config classes and How configuration works.

So the generated table below shows the default of the flag. For many tuning flags that is None, which means "EngineArgs or VllmConfig decides". The next section gives the values that they decide.

Flags you tune first for online serving, with their real defaults#

Example, with one assumption: current_platform.get_device_total_memory() reports 70 GiB or more (and less than 160 GiB) for an 80 GB card (vllm/engine/arg_utils.py:2946). The repository does not give this value; it comes from the driver at run time. On one 80 GB H100, the name has no "a100". So vllm serve uses a token budget of 8192 and at most 1024 requests per step. On one 80 GB A100, the name contains "a100", so the same command uses 2048 tokens and at most 256 requests (vllm/engine/arg_utils.py:2970-2993). A platform can still change the config later, in current_platform.check_and_update_config (vllm/config/vllm.py:2046).

Deprecated flags#

Three flags still parse, but they do nothing or forward to a new flag. The help text says that they will be removed in v0.33.0.

All flags#

319 arguments of vllm serve in 19 groups, rebuilt from make_arg_parser and EngineArgs.add_cli_args. Inside a group the flags are sorted as in vllm serve --help.

positional arguments (1)#

options (12)#

Frontend (61)#

ModelConfig (46)#

LoadConfig (9)#

AttentionConfig (1)#

MambaConfig (4)#

StructuredOutputsConfig (2)#

ParallelConfig (53)#

CacheConfig (21)#

OffloadConfig (7)#

MultiModalConfig (24)#

LoRAConfig (13)#

LoggingConfig (3)#

ObservabilityConfig (13)#

SchedulerConfig (18)#

CompilationConfig (2)#

KernelConfig (6)#

VllmConfig (23)#