All the ways to extend vLLM

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

The idea#

An extension point is a place where code from outside the vLLM repository can change what vLLM does. Such code is out-of-tree (OOT). vLLM has about twenty extension points. They come in three kinds, and each kind reaches your code in a different way.

1. Entry-point groups. Your package publishes an entry point under a plugin group, for example vllm.platform_plugins. vLLM finds it with no help from you. There are six groups. The page How vLLM finds and loads plugins explains how and when each process loads them.
2. Registries. vLLM keeps tables of models, layers, attention backends, quantization methods, connectors and more. A function such as ModelRegistry.register_model adds your class to one table. You call these functions from a general plugin, so that the call runs in every process.
3. Config hooks. A config field or a CLI flag names your class or your module, for example --scheduler-cls my_pkg.MyScheduler. vLLM imports the name when it needs the class. No entry point is necessary.

The three kinds work together. A typical plugin package publishes one general plugin. Its function calls several register functions. A platform plugin also sets config fields, for example worker_cls, in its check_and_update_config hook.

An everyday comparison. Think of a large office building. The entry-point groups are the front desk: it has a list of named visitors, and it calls each one at a fixed time. The registries are the notice boards on each floor: a visitor pins a card there, and the staff on that floor read it. The config hooks are an order form: you write the name of a contractor, and the building calls that contractor. The comparison stops here. In vLLM each process is its own building with its own notice boards. A card that you pin in the API server is not visible in a worker.

The picture#

Read the diagram column by column. Each item names the line that reads the extension point, so it shows where your code must be visible. Green and violet items need no extra work in that process. A blue item works only if a general plugin (or your platform) has filled the registry in that same process.

The interactive timeline below shows the order of the start-up. Choose the settings, and read which plugin groups and Platform hooks run in each process.

In the code#

Step 1: the six entry-point groups#

Five group names are constants in vllm/plugins/__init__.py. The sixth group is in the sampler code:

# Default plugins group will be loaded in all processes(process0, engine core
# process and worker processes)
DEFAULT_PLUGINS_GROUP = "vllm.general_plugins"
# IO processor plugins group will be loaded in process0 only
IO_PROCESSOR_PLUGINS_GROUP = "vllm.io_processor_plugins"
# Platform plugins group will be loaded in all processes when
# `vllm.platforms.current_platform` is called and the value not initialized,
PLATFORM_PLUGINS_GROUP = "vllm.platform_plugins"
# Stat logger plugins group will be loaded in process0 only when serve vLLM with
# async mode.
STAT_LOGGER_PLUGINS_GROUP = "vllm.stat_logger_plugins"
# Endpoint plugins group is loaded in the API server front end process only.
# Each entry point resolves to a factory returning an `EndpointPlugin`
# (see `vllm/plugins/endpoint_plugins/interface.py`).
ENDPOINT_PLUGINS_GROUP = "vllm.endpoint_plugins"

The table gives the short form. The page How vLLM finds and loads plugins has the full detail for each group: the loader, the filter and the error handling.

Step 2: registries that a general plugin fills#

Most extension points are registries. A registry is a module-level table plus a register function. The KV connector factory is a short example:

class KVConnectorFactory:
    _registry: dict[str, Callable[[], type[KVConnectorBase]]] = {}

    @classmethod
    def register_connector(cls, name: str, module_path: str, class_name: str) -> None:
        """Register a connector with a lazy-loading module and class name."""
        if name in cls._registry:
            raise ValueError(f"Connector '{name}' is already registered.")

        def loader() -> type[KVConnectorBase]:
            module = importlib.import_module(module_path)
            return getattr(module, class_name)

        cls._registry[name] = loader

vLLM reads the table later, in the process that builds the part. So the register call must run in that process before the read. A general plugin does this, because each process runs it (Step 1). The table lists the registries.

Step 3: config hooks that name your class#

A config hook is a field of VllmConfig (or a CLI flag) that holds the name of your class or module. The front end parses it. The other processes get it inside the pickled VllmConfig, because the start method is spawn and the config is a process argument (vllm/v1/engine/utils.py:256-287). The scheduler hook shows the pattern:

    def get_scheduler_cls(self) -> type["SchedulerInterface"]:
        if self.scheduler_cls is None:
            if self.async_scheduling:
                from vllm.v1.core.sched.async_scheduler import AsyncScheduler

                return AsyncScheduler
            from vllm.v1.core.sched.scheduler import Scheduler

            return Scheduler

        # The first half of this warning can be removed once the Scheduler interface is
        # finalized and we can maintain support for scheduler classes that implement it
        if not (
            isinstance(self.scheduler_cls, str)
            and self.scheduler_cls.startswith("vllm.")
        ):
            logger.warning_once(
                "Using custom scheduler class %s. This scheduler interface is not "
                "public and compatibility may not be maintained. If you have "
                "subclassed Scheduler instead of AsyncScheduler, you will see "
                "degraded performance due to async scheduling being disabled.",
                self.scheduler_cls,  # type: ignore[arg-type]
            )
        if not isinstance(self.scheduler_cls, str):
            return cast(type["SchedulerInterface"], self.scheduler_cls)
        return resolve_obj_by_qualname(self.scheduler_cls)

Two more fields name classes. logits_processors takes classes or "module:Class" strings (vllm/config/model.py:407, vllm/v1/worker/gpu/sample/logits_processor/loader.py:77-105). model_class_overrides registers a model class in every process, but its docstring says it is "for development and debugging purposes only" (vllm/config/model.py:351-357, vllm/config/model.py:1170-1193).

Step 4: which one do I need?#

Start from your goal. Each line names the extension point and the page that explains it.

• New hardware. Write a platform plugin (vllm.platform_plugins) with a Platform subclass. Set worker_cls in check_and_update_config, and add a general plugin for your custom ops. See Platform plugins and current_platform and The Platform interface.
• New model architecture. Call ModelRegistry.register_model("MyArch", "my_pkg.model:MyModel") from a general plugin. See Out-of-tree models and the model registry.
• A faster kernel for one op. Subclass the in-tree CustomOp and decorate it with register_oot. On an out-of-tree platform, an enabled op calls forward_oot (vllm/model_executor/custom_op.py:183, vllm/model_executor/custom_op.py:202-203). See CustomOp, out-of-tree ops and IR op providers.
• New quantization format. Use @register_quantization_config("my_quant") in a general plugin. See Quantization methods as plugins.
• A custom HTTP route. Write an endpoint plugin (vllm.endpoint_plugins), and name it in VLLM_PLUGINS. See Plugins in the API server.
• A custom metrics sink. Publish a StatLoggerBase subclass in vllm.stat_logger_plugins. See Plugins in the API server.
• KV offload to your storage. Write a KV connector. Register it with KVConnectorFactory.register_connector, or name its module in kv_connector_module_path. See KV connectors.
• A different scheduling policy. Subclass the scheduler and set --scheduler-cls. See Hooks in the engine core and the workers.

The tours Tour: Life of a plugin and Tour: Build a toy plugin follow one plugin through these steps. The page Extension points will hold the full reference table.

Deep dive#

The sections below give the full detail. Open them one at a time, or use Open all deep dives at the top of the page.

What can go wrong#

• The registry is empty in a worker. You registered from a launch script or from code that runs only in the front end. Register from a general plugin instead (first deep dive).
• An allowlist filters your general plugin. VLLM_PLUGINS applies to general plugins too (vllm/plugins/__init__.py:63-64). Then no register call runs, with no error. Use the timeline above with VLLM_PLUGINS=acme_admin to see it.
• A short parser plugin value is ignored. A value of 3 characters or fewer is not imported (vllm/entrypoints/common/cli_args.py:579). A path that fails to import only writes an ERROR log (vllm/utils/import_utils.py:94-98).
• A custom scheduler loses async scheduling. vLLM warns: if you subclass Scheduler instead of AsyncScheduler, async scheduling is off and performance drops (vllm/config/scheduler.py:247-253).
• A worker extension hides a method. If the worker class already has an attribute of the extension, an assert stops start-up (vllm/v1/worker/worker_base.py:310-319).

Why it matters. The right extension point depends on the process that must see your code. An entry-point group or a config hook reaches its process by itself. A registry reaches only the process where your register call ran. Most "it works in the front end but not in the worker" problems come from this difference.