Entry Points & Console Scripts

Entry points register CLI commands and plugin hooks at install time. [project.scripts] creates console commands; [project.entry-points] enables plugin discovery.

Recipe

[project.scripts]
myapp = "myapp.cli:main"
 
[project.entry-points."myapp.plugins"]
json = "myapp.plugins.json:JsonPlugin"

When to reach for this:

• Shipping a CLI with your package
• Building a plugin system other packages extend
• Registering tools discoverable by frameworks

Working Example

[project]
name = "invoice-cli"
version = "0.1.0"
 
[project.scripts]
invoice = "invoice_cli.main:cli"
 
[project.entry-points."invoice.exporters"]
csv = "invoice_cli.exporters:CSVExporter"
pdf = "invoice_cli.exporters:PDFExporter"

# src/invoice_cli/main.py
import click
from importlib.metadata import entry_points
 
@click.group()
def cli():
    """Invoice management CLI."""
    pass
 
@cli.command()
@click.option("--format", default="csv")
def export(format: str):
    eps = entry_points(group="invoice.exporters")
    exporter = eps[format].load()
    exporter().run()
 
def main():
    cli()

uv pip install -e .
invoice export --format csv

What this demonstrates:

• project.scripts installs invoice command to PATH
• Entry point groups enable plugin discovery via importlib.metadata
• Third-party packages can add exporters by registering their own entry points
• click or typer handles CLI parsing inside main

Deep Dive

Entry Point Types

Gotchas

• Entry point to non-callable - install succeeds, run fails. Fix: point to a function, not a module.
• Name collision with existing CLI - overwrites user commands. Fix: unique, namespaced command names.
• Loading all plugins at import - slow startup. Fix: lazy-load plugins when subcommand is invoked.
• Missing main() guard - fine for entry points but needed for python -m. Fix: add if __name__ == "__main__" for module execution.
• Editable install not updating scripts - stale entry points. Fix: reinstall after changing entry point config.

Alternatives

FAQs

Related

• CLI Basics - CLI design
• Packaging & Distributing CLIs - pipx distribution
• Packaging Basics - build and install
• Click - CLI framework

Stack versions: This page was written for Python 3.14.0, FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+, and uv 0.6+.