Structure Your Project: Modules And Packages

In this section, you learn about Python modules and packages. Modules are the ideal way to group and organize code, while packages are collections of Python modules. Before you start learning about packages, you need to thoroughly understand modules.

Below, you’ll find a short introduction to each topic, followed by the project layout I recommend for most Python projects.

Python modules

A module is simply a Python file. Once your program grows beyond a few dozen lines, you split it into multiple files and use the import statement to use code from one file in another. Python also comes with many built-in modules, like math, random and pathlib. You can define your own modules too, so let’s explore how! Start with the article on the Python import statement and modules.

Python packages

A package is a directory that groups related modules, usually with an __init__.py file in it. Packages let you build a hierarchy, so you can import things like from shop.payments import refund. They’re also what you install with pip: every package on PyPI is a package in this sense. Learn how to create and import them in Python packages: structure code by bundling your modules.

A typical Python project layout

Most modern Python projects look roughly like this. It’s what uv init --package my-tool creates, plus a tests folder:

my-tool/
├── .gitignore
├── .python-version
├── README.md
├── pyproject.toml
├── src/
│   └── my_tool/
│       ├── __init__.py
│       └── ...
└── tests/
    └── test_my_tool.pyCode language: Python (python)

Here’s what each part is for:

• pyproject.toml is the standard configuration file for a Python project. It holds the name, version, required Python version and dependencies, plus settings for tools like Ruff and pytest.
• src/my_tool/ is your package, with your modules in it. Note the underscore: the project name may contain a dash, but a package name can’t.
• tests/ holds your tests, separate from the code you ship.
• README.md explains what the project does and how to use it. .python-version tells tools like uv which Python version to use.

Putting the package inside a src folder is called the src layout. It prevents a common mistake: accidentally importing your code from the project folder instead of the installed version, so your tests run against what users will actually get. The alternative is the flat layout, where my_tool/ sits directly next to pyproject.toml. Both work. The Python Packaging User Guide compares the two.

For a small script or app that you won’t distribute as a package, you don’t need any of this structure. uv init --no-package gives you a pyproject.toml and a single main.py, and you can add modules next to it as the program grows.

Managing dependencies and environments

A project structure goes hand in hand with a virtual environment and a tool to manage your dependencies. These articles cover that part:

• Python uv: creates the project layout above and manages Python versions, virtual environments and dependencies in one tool.
• Python venv: the virtual environment tool that comes with Python.
• Python Poetry: an alternative to uv for packaging and dependency management.
• Virtual environments and package management: the overview of all of these.