A distribution package is the thing you install, like a PyPI project. An import package is the thing you import in code. They usually share a name, but PyPI does not enforce that, so seeing import foo does not prove that pip install foo gives you the right code.
Definitions
The Python Packaging User Guide separates the two meanings of the word package.
| Term | What it is | Where you see it |
|---|---|---|
| Distribution package | Installable software, or a specific file for one version | pip install, the dependencies list, PyPI search |
| Import package | A Python module that can contain submodules | import statements in code |
Most of the time, one distribution package provides one import package with a matching name. The guide calls that a convention only.
Why the names can differ
A distribution package can provide an import package with a different name, or more than one import package. The guide's examples: the Pillow distribution provides the import package PIL, kept for historical reasons because Pillow began as a fork of PIL, and the attrs distribution provides both attrs and attr. The guide also says PyPI and other indices do not enforce any relationship between the name of a distribution package and the import packages it provides.
That has a direct consequence. The guide states that you cannot blindly install the PyPI package foo because you see import foo, since this may install an unintended and potentially even malicious package.
How this goes wrong
- Copying an install line from an AI answer or a forum post. The code imports a module, and the answer guesses the install name.
- Fixing an ImportError by installing whatever has that name. A different project may own it.
- Several distributions sharing one import name. The guide says import packages have no uniqueness requirement, and forks are a common reason.
- Typosquats. Names that look like popular ones are a known pattern. Our posts on name normalization and lookalikes explain the mechanics.
What to do as a user
- Look up the project's own documentation or repository for the exact install name.
- Open the PyPI page and check the project links, owners and release history.
- Compare the install name to what the docs say, character by character.
- Add the verified name to your dependency list, not to a one off command.
- After installing, check what the distribution actually provides, by listing its installed files.
What to do as a library author
- Document the install command and the import line side by side in your README.
- If the two names differ, say so clearly.
- Do not pick an import name that collides with a popular project.
- Keep the README accurate, as in our README rendering fix guide.
Why dependency lists matter
Your declared dependencies are distribution names. Scanners, advisories and SBOMs all work on those. A clear inventory lets you see which distributions you rely on, whatever the import lines say.
Try it yourself
Click through it at your own pace, or open it full screen.
Open a package in the inventory and compare its name with what the code imports. Note that the inventory tracks distribution names.
Safeguard's SBOM and dependency scanning list the distributions a project declares. You can run a free scan.
Quick check
Is the install name always the import name?
Usually, but not always. The packaging guide says it is only a convention that PyPI does not enforce.
Is it safe to pip install a name from an import statement?
Not blindly. The guide warns it may install an unintended and potentially malicious package. Confirm the name from the project's own docs.
Can one distribution provide several import packages?
Yes. A distribution package can provide multiple import packages, as attrs does.
Sources
- Distribution package vs. import package, Python Packaging User Guide
- Names and normalization, Python Packaging User Guide
Last reviewed: 19 October 2026.
