Tools and workflows

Python module vs. package vs. distribution

See what Python imports, what pip installs, and why an import name can differ from the name of the distribution you installed.

A Python module is something you import as a unit. An import package is a module that can contain other modules. A distribution is an installable release that can provide one or more import names. The name you give pip install can differ from the name you use in an import statement. For example, the Pillow distribution provides the PIL import package.

See a module inside a regular package

Suppose a project has this layout.

project/
    run_demo.py
    example_stats/
        __init__.py
        counts.py

The file counts.py is a module. The directory example_stats is a regular import package because it has an initializer. If counts.py defines a function called total, then from example_stats.counts import total loads it from that submodule when the package is on the import path. The initializer can be empty.

Python also supports namespace packages, which can be split across locations and need not have an __init__.py file. A small project with one team and one source tree can usually use a regular package. That makes the package boundary explicit and keeps the first example straightforward.

Follow the name the reader can use

Imports resolve objects from Python's module search path. An import package.module statement binds the package name in the current scope. A from package.module import thing statement binds thing directly. Both rely on the import system locating the package and submodule. Adding as changes the local name for the imported object, not the name Python searched for.

If imports work only from one directory, inspect why that directory puts code on the import path. A project that tests itself from its root may appear to work even when its installed distribution omits a module. Running an import from outside the source tree after installation is a useful check of what actually shipped.

Keep installation names distinct

When a project asks you to install a dependency, follow its metadata or official instructions. A name in a traceback is a clue about the missing import. It is not enough evidence to choose an installer command by itself. A distribution can expose a differently spelled import, offer multiple modules, or be part of a project that installs them as a group. Installing an arbitrary similarly named distribution can introduce unrelated code.

To find what has been installed, run python -m pip list with the interpreter of interest. For an import that already succeeds, inspect the module location using its __file__ attribute where available. Some modules, such as built-ins, do not have a normal source file path. The two checks answer different questions: distribution records and import resolution.

Distinguish public names from internal groupings

A package can contain helpers that callers should not depend on. For example, example_stats.counts may expose a supported total function while importing an internal convenience helper from another module. The helper can move when you refactor. A published import in the README creates a stronger expectation that the name will remain valid.

Look at code review from the caller's side. If a library's examples all rely on individual file locations that change every month, a stable public import can reduce the cost of reuse. The package's directory structure is a good way to organize work but does not automatically define which objects you promise to support.

Observe one import problem before changing the package

A local file named statistics.py can shadow Python's standard-library module of the same name. With the same Python and working directory as your failed program, check which file actually loaded. If the module imports successfully, python -c "import statistics; print(statistics.__file__)" can identify it. Rename your own file if that is blocking the intended import.

Some modules are found without a single physical Python file. Built-ins and namespace packages differ from an ordinary helper file. When your code loads a documented standard library module, do not assume that all modules have __file__ available to display. Inspect the context rather than making this attribute a condition for every successful import.

Grow structure when the boundaries become clear

A single file is a reasonable home for a small script. Move code into another module when you can name its job and want to reuse it or test it independently. A package is useful when several such modules belong to one public import name. Add build metadata when another person or system should install a known version.

Keep unrelated work out of an import. Top-level statements execute when a module is initialized. Definitions are normal there. Reading a real input file, prompting for a password, or starting an external process during import makes testing and reuse harder. Put the action behind a function and a deliberate command entry point.

Sources and further reading

Related reading

Browse Tools and workflows · Explore project tutorials

Search PythonProjects.org