Skip to content

pyproject.toml with setuptools

Jump to bottom
AJprogramming123 edited this page Jun 11, 2025 · 2 revisions

Understanding pyproject.toml and Python Packaging

Packaging your Python application correctly will make your project cleaner, your imports more predictable, and your life easier—especially when using tools like pip install -e or when working with test runners like pytest.

Why Project Structure Matters

Suppose you're working on a project and you place your main code inside a folder named src. You might end up with a structure like:

project_root/
├── src/
│   └── App/
│       └── __init__.py
├── run.py
├── pyproject.toml
└── README.md

Now, when you run python run.py from the project_root, Python adds the root directory to sys.path, but not the src directory.

This means when you write:

from App import create_app

Python raises an ImportError, because it doesn't see App in the current path—it’s hidden inside src.

Fixing This With pyproject.toml

To fix this and make the project pip-installable in development mode (using pip install -e .), you'll want to create and configure a pyproject.toml file.

Here’s a minimal but effective example:

[build-system]
requires = ["setuptools>=61.0"]
build-backend = "setuptools.build_meta"

[tool.setuptools]
packages = ["App"]

[tool.setuptools.package-dir]
"" = "src"

Explanation:

  • [build-system]: Tells pip how to build your package (uses modern setuptools).
  • [tool.setuptools]: Declares what package(s) to include. In this case, it's "App", which is your application.
  • [tool.setuptools.package-dir]: Specifies where the actual code lives. The line "" = "src" tells setuptools: look in src/ for the packages, not in the root directory.

Installing the Project in Development Mode

Once your pyproject.toml is correctly set up, run:

pip install -e .

This installs your project in editable mode. Any changes you make to the source code will immediately reflect when you run the app or tests—no reinstalling required. It also makes the import system aware of the correct package paths.

Conceptual Overview

  • Imports are like finding the address of a house — Python needs to know where the code lives.
  • Blueprints (in Flask or similar frameworks) are like organizing rooms inside the house — they help structure your app, but they rely on proper import paths.

If your files are not in the right structure or not installed properly, imports and blueprints will not behave as expected.

For example: run.py cannot import App directly from src/ unless the package is correctly installed or src is added to PYTHONPATH.

Final Notes

Using pyproject.toml with setuptools is now the modern, preferred way to package Python projects. It brings better tooling support, clarity, and compatibility with the Python ecosystem going forward.

By following this layout:

  • Your code is cleaner.
  • Your imports are reliable.
  • Your environment is easier to manage.
  • Your application is ready to scale.

Clone this wiki locally