Entry points specification#
Entry points are a mechanism for an installed distribution to advertise components it provides to be discovered and used by other code. For example:
Distributions can specify
console_scriptsentry points, each referring to a function. When pip (or another console_scripts aware installer) installs the distribution, it will create a command-line wrapper for each entry point.
Applications can use entry points to load plugins; e.g. Pygments (a syntax highlighting tool) can use additional lexers and styles from separately installed packages. For more about this, see Creating and discovering plugins.
The entry point file format was originally developed to allow packages built
with setuptools to provide integration point metadata that would be read at
importlib.metadata. It is now defined as a PyPA interoperability
specification in order to allow build tools other than
setuptools to publish
importlib.metadata compatible entry point metadata, and runtime libraries other
importlib.metadata to portably read published entry point metadata
(potentially with different caching and conflict resolution strategies).
Conceptually, an entry point is defined by three required properties:
The group that an entry point belongs to indicates what sort of object it provides. For instance, the group
console_scriptsis for entry points referring to functions which can be used as a command, while
pygments.stylesis the group for classes defining pygments styles. The consumer typically defines the expected interface. To avoid clashes, consumers defining a new group should use names starting with a PyPI name owned by the consumer project, followed by
.. Group names must be one or more groups of letters, numbers and underscores, separated by dots (regex
The name identifies this entry point within its group. The precise meaning of this is up to the consumer. For console scripts, the name of the entry point is the command that will be used to launch it. Within a distribution, entry point names should be unique. If different distributions provide the same name, the consumer decides how to handle such conflicts. The name may contain any characters except
=, but it cannot start or end with any whitespace character, or start with
[. For new entry points, it is recommended to use only letters, numbers, underscores, dots and dashes (regex
The object reference points to a Python object. It is either in the form
importable.module:object.attr. Each of the parts delimited by dots and the colon is a valid Python identifier. It is intended to be looked up like this:
import importlib modname, qualname_separator, qualname = object_ref.partition(':') obj = importlib.import_module(modname) if qualname_separator: for attr in qualname.split('.'): obj = getattr(obj, attr)
Some tools call this kind of object reference by itself an ‘entry point’, for want of a better term, especially where it points to a function to launch a program.
There is also an optional property: the extras are a set of strings identifying optional features of the distribution providing the entry point. If these are specified, the entry point requires the dependencies of those ‘extras’. See the metadata field Provides-Extra (multiple use).
Using extras for an entry point is no longer recommended. Consumers should support parsing them from existing distributions, but may then ignore them. New publishing tools need not support specifying extras. The functionality of handling extras was tied to setuptools’ model of managing ‘egg’ packages, but newer tools such as pip and virtualenv use a different model.
Entry points are defined in a file called
entry_points.txt in the
*.dist-info directory of the distribution. This is the directory
described in Recording installed projects for installed distributions,
and in Binary distribution format for wheels.
The file uses the UTF-8 character encoding.
The file contents are in INI format, as read by Python’s
module. However, configparser treats names as case-insensitive by default,
whereas entry point names are case sensitive. A case-sensitive config parser
can be made like this:
optionxform = staticmethod(str)
The entry points file must always use
= to delimit names from values
(whereas configparser also allows using
The sections of the config file represent entry point groups, the names are names, and the values encode both the object reference and the optional extras. If extras are used, they are a comma-separated list inside square brackets.
Within a value, readers must accept and ignore spaces (including multiple
consecutive spaces) before or after the colon, between the object reference and
the left square bracket, between the extra names and the square brackets and
colons delimiting them, and after the right square bracket. The syntax for
extras is formally specified as part of PEP 508 (as
restrictions on values specified in PEP 685.
For tools writing the file, it is recommended only to insert a space between the
object reference and the left square bracket.
foo = foomod:main
# One which depends on extras:
foobar = foomod:main_bar [bar,baz]
# pytest plugins refer to a module, so there is no ':obj'
nbval = nbval.plugin
Use for scripts#
Two groups of entry points have special significance in packaging:
gui_scripts. In both groups, the name of the entry
point should be usable as a command in a system shell after the package is
installed. The object reference points to a function which will be called with
no arguments when this command is run. The function may return an integer to be
used as a process exit code, and returning
None is equivalent to returning
For instance, the entry point
mycmd = mymod:main would create a command
mycmd launching a script like this:
from mymod import main
The difference between
gui_scripts only affects
console_scripts are wrapped in a console executable,
so they are attached to a console and can use
sys.stderr for input and output.
gui_scripts are wrapped in a GUI executable, so they can be started without
a console, but cannot use standard streams unless application code redirects them.
Other platforms do not have the same distinction.
Install tools are expected to set up wrappers for both
gui_scripts in the scripts directory of the install scheme. They are not
responsible for putting this directory in the
PATH environment variable
which defines where command-line tools are found.
As files are created from the names, and some filesystems are case-insensitive, packages should avoid using names in these groups which differ only in case. The behaviour of install tools when names differ only in case is undefined.
October 2017: This specification was written to formalize the existing entry points feature of setuptools (discussion).