Overview

Fixes #48094 (also reported earlier as #42852). On Python 3.10–3.12, vllm chat and vllm complete print a spurious argument 'url' is deprecated warning on every run, because run-batch's deprecated --url leaks into sibling subcommands.

cc @hmellor

Claims

• vllm chat / vllm complete no longer warn that their own (valid) --url is deprecated.
• Deprecated arguments still warn for the subcommand that defines them (vllm run-batch --url ... still warns once).
• Each parser now only checks its own deprecated arguments, so the same leak can't happen for future deprecated arguments, and the top-level parser no longer re-checks a subcommand's arguments.

Validation

Python 3.12.3 (WSL2 Ubuntu), editable install with VLLM_USE_PRECOMPILED=1.

New regression test test_deprecated_arg_scoped_to_subcommand:

pytest tests/utils_/test_argparse_utils.py -k deprecated   # on main: 1 failed
pytest tests/utils_/test_argparse_utils.py                 # with this PR: 24 passed

End-to-end, counting argument 'url' is deprecated lines (no server or GPU needed):

pre-commit run --files <changed files> and pre-commit run --hook-stage manual --files <changed files> (ruff, mypy 3.10–3.13, etc.) pass.

Details

Root cause. Below Python 3.13, FlexibleArgumentParser emulates add_argument(..., deprecated=True) by recording the action in _deprecated, a set defined on the class and therefore shared by every parser and subparser. parse_known_args then walks that whole set. run-batch marks its --url (default 0.0.0.0) as deprecated via frontend_kwargs["url"]["deprecated"] = True, and since vllm/entrypoints/cli/main.py builds every subcommand's parser on each invocation, that action is always in the set. When chat/complete parse their own --url (default http://localhost:8000/v1), the value never equals run-batch's default, so the warning fires. (This is also why a grep for deprecated=True doesn't find it.)

Fix. Make _deprecated an instance variable. It is created at the top of __init__, because ArgumentParser.__init__ already adds argument groups and -h, and _FlexibleArgumentGroup shares its parser's set, because argparse groups don't keep a reference to their container. _SubParsersAction calls each subparser's own parse_known_args, so a subcommand's deprecated arguments are only checked when that subcommand is parsed. The warning condition (value differs from the default) is unchanged. Python 3.13+ is unaffected since it uses argparse's native support.

Prior work. #42854 proposed the same per-instance fix but was auto-closed as stale without a review. No other open PR addresses this issue.

AI-assisted; I reviewed and tested all changes.

BEFORE SUBMITTING, PLEASE READ https://docs.vllm.ai/en/latest/contributing (anything written below this line will be removed by GitHub Actions)