Python Packaging and Project Structure Explained

A Python project can start as one script, but once it gains reusable code, tests, dependencies, or other users, where files live begins to matter. A useful structure makes imports easier to understand, keeps project-specific dependencies separate, and helps other people run or install the code.

There is no single directory layout that suits every project. For a small application, a simple layout may be enough. A reusable library needs clearer boundaries between its importable code and the rest of the project. The example below shows one common option; the right choice depends on what you are building and how you plan to use it.

Python project structure: the short answer

For a modest project, start with a clear home for your code, tests, and project notes. One possible src/ layout looks like this:

weather_tool/
├── pyproject.toml
├── README.md
├── src/
│   └── weather_tool/
│       ├── __init__.py
│       └── forecast.py
└── tests/
    └── test_forecast.py

Here, weather_tool is the import package: the code users or other parts of the project can import. The top-level project directory also holds documentation, tests, and configuration. The example includes a configuration-file name to show where project configuration commonly lives; the exact contents and build setup depend on the tools and packaging workflow you choose.

A small script or application may not need this full arrangement. A reusable library may benefit from separating importable code from project files. Treat src/ as an option, not a universal requirement.

Module, package, and distribution: what’s the difference?

These terms describe different parts of working with Python code:

• Module: A Python file containing definitions and statements. For example, forecast.py can be a module.
• Import package: A way to organize related modules under a dotted name, such as weather_tool.forecast. Python’s tutorial describes packages as a way to structure modules and explains that __init__.py is the usual package marker, with namespace packages as an exception. (Python tutorial: Modules)
• Distribution: A project prepared for other people or environments to install. The distribution is not the same thing as the import package: a project may contain several import packages, or its distribution name may differ from the name used in an import.

In short, importing is about making code available to a Python program; distribution and installation are about delivering a project so it can be used elsewhere. Python’s installation documentation describes pip as the preferred installer and PyPI as a package repository. (Installing Python modules)

When do you need __init__.py?

For a regular package, a directory containing __init__.py is the familiar arrangement. The file can be empty when you do not need package initialization code. Namespace packages are an exception: they can organize importable modules without the usual __init__.py marker. If you are learning or building a small project, using __init__.py in your package directory is a straightforward convention; do not add files throughout the project without a reason.

A practical layout for a small Python project

Consider the example project above. Each part has a distinct purpose:

• src/weather_tool/ contains the importable project code in this example.
• forecast.py holds one module’s related functions and logic.
• tests/ holds checks for the project’s behavior. Tests help you catch changes that break existing functionality.
• README.md can explain what the project does and how a reader can get started.
• pyproject.toml is shown as a project configuration location. Its exact settings depend on the chosen tools and packaging requirements.

Keep files grouped by responsibility rather than creating a deep directory tree before the project needs one. If a module becomes difficult to navigate or covers unrelated tasks, that may be a reason to split it. A directory name should also help a reader understand what belongs inside it.

Flat layout or src/ layout?

A flat layout places the import package directly under the project root:

weather_tool/
├── weather_tool/
│   ├── __init__.py
│   └── forecast.py
├── tests/
└── README.md

A src/ layout puts the import package inside a separate source directory. Either can be appropriate. A straightforward script or early learning project may be easier to manage with fewer directories. A more developed library may use src/ to make the distinction between project files and importable code visible. The available official documentation explains imports and packages, but does not establish one layout as best for all projects.

Imports and common layout problems

Python must be able to find a module for an import to work. The location from which code is run and the paths available to the interpreter can affect that. A script that works when launched from one directory may fail when started from another if it relies on an accidental path setup.

For example, if forecast.py is inside the weather_tool package, code elsewhere in the project can refer to it using the package name, such as weather_tool.forecast. Keeping the package name consistent and running the project through its intended workflow makes imports easier to reason about.

Common layout and import problems include:

• Generic filenames that shadow other modules. Names such as email.py or random.py can conflict with modules your code expects to import.
• Running files from inconsistent locations. A changed working directory can expose assumptions about where Python should look for code.
• Mixing unrelated code in one module. Separate responsibilities when doing so makes the code easier to find, test, and maintain.
• Confusing installation with importing. A folder may be importable in one development setup without being prepared as a distribution for installation elsewhere.

When an import fails, check the module’s name and location, the package structure, and how the program is being launched before adding path modifications as a quick fix.

Virtual environments and dependencies

A virtual environment provides an isolated place for a project’s Python packages. This helps keep project dependencies separate from packages used by other projects or by the system. Python documents venv as its standard tool for creating virtual environments. (Python documentation: venv)

A common starting command is:

python -m venv .venv

Activate the environment using the instructions appropriate for your operating system and shell, then install the packages the project needs. The environment itself should be recreatable rather than treated as project source code. The Python documentation advises against checking a virtual environment into source control; record and manage project dependencies using a workflow appropriate to the project instead.

Keep the environment directory, often named .venv, out of version control. Do not confuse it with the project’s source code: it is a local working environment that can be created again. Because dependency and lockfile practices vary by tooling, choose a current documented workflow rather than assuming one file or tool suits every project.

Packaging a project for installation

Packaging is the step from a working project directory to something that can be installed or shared through an installation workflow. A project’s code is the material being delivered; its project metadata and build configuration tell the chosen tooling how to treat that project. Installation is a separate step, commonly handled with pip, and may obtain packages from a repository such as PyPI. (Installing Python modules)

The exact configuration depends on the packaging tools, project type, and distribution requirements. The available research supports the distinction between installation, environments, and package repositories, but does not verify a current minimal build configuration or recommend a build backend. For that reason, this guide does not provide a copy-and-paste packaging configuration. Before publishing a library, consult current packaging guidance for the tools you intend to use and test the resulting installation in a clean environment.

For a personal application that will only run on your own machine, you may not need to publish an installable distribution. Packaging becomes more relevant when you want to install the project consistently in another environment, share it with collaborators, or distribute a reusable library.

Application or reusable library?

Both kinds of projects need readable code and a workable environment, but their priorities differ:

These are practical distinctions, not rigid rules. A small application can have reusable components, and a library may begin as a single module. Let the project’s intended users and delivery method guide how much structure you add.

Common mistakes and a starter checklist

Before adding more tooling or directories, check the basics:

• Can you explain what each top-level directory is for?
• Are importable modules grouped under clear, consistent names?
• Does the project run from its documented starting point rather than relying on an accidental working directory?
• Are tests separate from application or library code?
• Does the project use an isolated environment for its dependencies?
• Is the virtual environment excluded from version control?
• If the project must be installed elsewhere, have you checked current packaging instructions and tested installation in a clean environment?

Start with the simplest arrangement that makes those answers clear. Add packaging configuration or a more elaborate directory structure when the project’s use case calls for it, not just because a template includes it.

Further reading for Python learners

If you want a structured introduction that also covers virtual environments and packaging in its appendices, The Python Apprentice may be a useful learning resource. Its catalog description also covers Python fundamentals, modules, testing, and debugging. Choose it as a broader study companion rather than as a substitute for checking current packaging instructions when preparing a project for distribution.

The Python Apprentice

By Robert Smallshire

Learners who want a structured Python introduction that includes virtual environments and packaging in its appendices.

Read more about this book →

Digital Delights also has a Python book collection for readers exploring related programming resources.

Frequently asked questions

Do I need __init__.py?

For a regular Python package, __init__.py is the usual marker and may be empty. Namespace packages are an exception and can work without it. For a straightforward project, using the file in your package directory is a familiar convention. See the official module and package tutorial for the distinction.

Is src/ better than a flat layout?

Not for every project. A flat layout can keep a small project simple; a src/ layout makes the source-code boundary explicit. Choose based on the project’s size, intended use, and tooling rather than treating either option as a universal rule.

Should I commit my virtual environment?

No. A virtual environment is intended to be recreated and should not be checked into source control. Keep it separate from the project’s source files and use a suitable dependency workflow so the environment can be set up again. The official venv documentation explains virtual environments.

What is the difference between a Python package and a distribution?

An import package organizes code that Python imports, while a distribution is a project prepared for installation and sharing. The names can differ, and one distribution can contain more than one import package. Packaging and importing are related, but they are not the same operation.

Conclusion

A sound Python project structure makes it clear where code lives, how modules relate, and how the project is meant to run. Begin with a small, understandable layout; use a virtual environment for project dependencies; and distinguish importable packages from distributions prepared for installation. When you need to publish or share a project, verify the current packaging workflow for your chosen tools instead of relying on an untested template.

Sources

• 6. Modules — Python 3.13.16 documentation
• Installing Python modules — Python 3.14.7 documentation
• venv — Creation of virtual environments — Python 3.14.7 documentation