Course contentsShow
← Python
Lesson 517 of 1,0608. Professional Tooling and PackagingFree lesson

Managing Entry Points and CLI Scripts

You will configure console scripts in your project configuration to automatically generate executable commands for your users upon package installation.

In this lesson, you will learn how to make your Python application available as a command-line tool by configuring entry points in your project metadata.

Turning Code into Commands

When you install a Python package, you often want to run it from your terminal without typing python -m my_package.main. Instead, you want to type a short command like my-tool. Entry points allow you to bridge the gap between your internal Python functions and the system’s executable path.

When a user installs your package, the installer (like pip or uv) reads your configuration file and automatically generates an executable wrapper script in the system’s bin directory.

Configuring Entry Points in pyproject.toml

The standard way to define these scripts is within your pyproject.toml file under the [project.scripts] section. You map the desired command name to a specific function in your codebase using the module.submodule:function_name syntax.

Imagine your project structure has a file src/my_app/cli.py containing a function called run(). You would configure it like this:

[project.scripts]
my-tool = "my_app.cli:run"

Once installed, your user can simply open their terminal and type my-tool. The installer handles the heavy lifting, creating a script that correctly initializes your virtual environment and executes the run() function inside your package.

Why Use Entry Points?

By using entry points, you decouple your installation process from the way users interact with your code. It keeps your project's logic clean and contained within your package structure, while providing a professional, "native" command-line experience for the end user. This prevents the need for users to hunt for your package path or rely on manual aliases in their shell configuration files.

Remember that the function referenced in your entry point should be a callable that accepts no arguments (or handles its own arguments via sys.argv), as it is essentially the "main" hook for your application.

Key Takeaway: By defining [project.scripts] in your pyproject.toml, you instruct package managers to automatically generate executable command-line wrappers for your users during installation.