Distribution package vs. import package#
A number of different concepts are commonly referred to by the word “package”. This page clarifies the differences between two distinct but related meanings in Python packaging, “distribution package” and “import package”.
What’s a distribution package?#
A distribution package is a piece of software that you can install.
Most of the time, this is synonymous with “project”. When you type
install pkg, or when you write
dependencies = ["pkg"] in your
pkg is the name of a distribution package. When
you search or browse the PyPI, the most widely known centralized source for
installing Python libraries and tools, what you see is a list of distribution
packages. Alternatively, the term “distribution package” can be used to
refer to a specific file that contains a certain version of a project.
Note that in the Linux world, a “distribution package”, most commonly abbreviated as “distro package” or just “package”, is something provided by the system package manager of the Linux distribution, which is a different meaning.
What’s an import package?#
An import package is a Python module. Thus, when you write
from pkg import func in your Python code,
pkg is the
name of an import package. More precisely, import packages are special
Python modules that can contain submodules. For example, the
package contains modules like
numpy.fft. Usually, an import package is a directory on the file
system, containing modules as
.py files and subpackages as
You can use an import package as soon as you have installed a distribution package that provides it.
How do distribution package names and import package names compare?#
Import packages should have valid Python identifiers as their name (the
exact rules are found in the Python
documentation) . In particular, they use underscores
_ as word
separator and they are case-sensitive.
On the other hand, distribution packages can use hyphens
_. They can also contain dots
., which is sometimes
used for packaging a subpackage of a namespace package. For most purposes, they are insensitive
to case and to
_ differences, e.g.,
Awesome_Package is the same as
pip install awesome-package (the
precise rules are given in the name normalization specification).