Python entry points

pyproject.toml. The [project] table of the packaging standard has two places for entry points:

• [project.scripts]: each key becomes a console script (pyproject.toml:42-43). The installer writes it into the group console_scripts.
• [project.entry-points."<group>"]: any other group. The group name has dots, so it needs quotes (pyproject.toml:45-47).

setup.py. Older packages pass a dictionary to setup(): group name → list of "name = module:attr" strings. One package can fill several groups. The dummy platform plugin of the tests fills two groups at once (tests/plugins/vllm_add_dummy_platform/setup.py:6-18):

setup(
    name="vllm_add_dummy_platform",
    version="0.1",
    packages=["vllm_add_dummy_platform"],
    entry_points={
        "vllm.platform_plugins": [
            "dummy_platform_plugin = vllm_add_dummy_platform:dummy_platform_plugin"  # noqa
        ],
        "vllm.general_plugins": [
            "dummy_custom_ops = vllm_add_dummy_platform:register_ops"
        ],
    },
)

What the installer writes. In the installed <name>-<version>.dist-info/ folder, the file entry_points.txt has one INI section per group. For vLLM it looks like this (the file is not in the repo; it comes from the build):

[console_scripts]
vllm = vllm.entrypoints.cli.main:main

[vllm.general_plugins]
lora_filesystem_resolver = vllm.plugins.lora_resolvers.filesystem_resolver:register_filesystem_resolver
lora_hf_hub_resolver = vllm.plugins.lora_resolvers.hf_hub_resolver:register_hf_hub_resolver

An editable install (pip install -e .) also writes this file. So when you add or rename an entry point, install the package again. A change to the code of the target needs no new install.

vLLM needs Python 3.11 or newer (pyproject.toml:34). From Python 3.10, importlib.metadata.entry_points(group=...) returns only the entry points of one group. Each item is an EntryPoint with these attributes:

A tiny plugin package (example files, not in the repo). Two files are enough:

# my_vllm_plugin/pyproject.toml
[project]
name = "my-vllm-plugin"
version = "0.1"

[project.entry-points."vllm.general_plugins"]
hello = "my_vllm_plugin:register"

# my_vllm_plugin/my_vllm_plugin/__init__.py
def register():
    print("hello from my_vllm_plugin")

Install it with pip install -e my_vllm_plugin. Then read the group from any Python process:

from importlib.metadata import entry_points

eps = entry_points(group="vllm.general_plugins")
for ep in eps:
    print(ep.name, "->", ep.value)

ep = next(ep for ep in eps if ep.name == "hello")
func = ep.load()   # imports my_vllm_plugin now
func()             # prints "hello from my_vllm_plugin"

Install no other plugin of this group. Then the loop prints three lines: hello and the two LoRA resolvers of vLLM. The order of the lines depends on the order of the packages on sys.path; do not depend on it.

def load_plugins_by_group(group: str) -> dict[str, Callable[[], Any]]:
    """Load plugins registered under the given entry point group."""
    from importlib.metadata import entry_points

    allowed_plugins = envs.VLLM_PLUGINS

    discovered_plugins = entry_points(group=group)
    if len(discovered_plugins) == 0:
        logger.debug("No plugins for group %s found.", group)
        return {}

    # Check if the only discovered plugin is the default one
    is_default_group = group == DEFAULT_PLUGINS_GROUP
    # Use INFO for non-default groups and DEBUG for the default group
    log_level = logger.debug if is_default_group else logger.info

    log_level("Available plugins for group %s:", group)
    for plugin in discovered_plugins:
        log_level("- %s -> %s", plugin.name, plugin.value)

    if allowed_plugins is None:
        log_level(
            "All plugins in this group will be loaded. "
            "Set `VLLM_PLUGINS` to control which plugins to load."
        )

    plugins = dict[str, Callable[[], Any]]()
    for plugin in discovered_plugins:
        if allowed_plugins is None or plugin.name in allowed_plugins:
            if allowed_plugins is not None:
                log_level("Loading plugin %s", plugin.name)

            try:
                func = plugin.load()
                plugins[plugin.name] = func
            except Exception:
                logger.exception("Failed to load plugin %s", plugin.name)

    return plugins

1. Line 40. VLLM_PLUGINS is a list of names, or None when the variable is not set (vllm/envs.py:1163-1167).
2. Line 42. entry_points(group=group) reads the metadata of all installed packages. Nothing is imported yet.
3. Lines 43-45. An empty group returns an empty dict.
4. Lines 52-54. The loader logs each ep.name and ep.value: at DEBUG for vllm.general_plugins, at INFO for other groups.
5. Line 64. The filter compares ep.name, not the package name, with VLLM_PLUGINS.
6. Lines 68-72. plugin.load() imports the module. An exception is logged with logger.exception, and the loop goes on with the next plugin.
7. Line 74. The result maps each name to the loaded object. The caller decides what to do with it. For general plugins, load_general_plugins() calls each function once per process (vllm/plugins/__init__.py:77-90).

The groups. vLLM reads five groups through this function (vllm/plugins/__init__.py:16-30). A sixth group, vllm.logits_processors, has its own loader that calls entry_points() directly (vllm/v1/worker/gpu/sample/logits_processor/loader.py:46). Which process loads which group, when, and what the loaded object must be, is the topic of How vLLM finds and loads plugins. This page does not repeat it.

For each console script, the installer writes a small executable into the bin/ folder of the environment (Scripts\ on Windows). It imports vllm.entrypoints.cli.main and calls main(). So vllm serve ... and python -m vllm.entrypoints.cli.main serve ... run the same function (vllm/entrypoints/cli/main.py:122-123).

The same metadata gives the version. vllm --version prints importlib.metadata.version("vllm"): the version of the installed distribution, not a constant in the code (vllm/entrypoints/cli/main.py:92-97).

Worked example. The value vllm.entrypoints.cli.main:main splits at the colon. The module part is vllm.entrypoints.cli.main, and the attribute part is main. So ep.load() does the same as importlib.import_module("vllm.entrypoints.cli.main").main. A value can also name a dotted attribute, for example pkg.mod:Class.method; then load() follows each dot.