Tools and workflows

Python src layout vs. flat layout

Compare src and flat Python package layouts. Check where your tests import code from and catch files missing from a built wheel.

In a flat layout, the import package sits in the project root. In a src layout, it sits inside src/. Both can provide the same public import, such as import inventory. A src layout helps expose missing installation steps because simply running a test from the project root usually cannot import the source package.

Where the package directory goes in each layout

In a flat layout, a package directory such as inventory/ sits beside pyproject.toml. In a source layout, it moves to src/inventory/. The public import can remain import inventory.

project/
    pyproject.toml
    src/
        inventory/
            __init__.py
            summaries.py
    tests/
        test_summaries.py

Configure your build backend to find packages under src/ if its default discovery does not. Installed code imports inventory. For guidance on the files around that directory, see how to organize a Python project.

Recognize the problem the layout can expose

A local test starts from the root and imports inventory.summaries. In a flat layout this can succeed even if the installed product would lack the module, because Python can find the checkout copy. A customer who only has the installed wheel cannot rely on that directory. Running the same test there can fail immediately.

With a correctly arranged src layout, an uninstalled package typically is not importable from the repository root. Install the project into the development environment. Editable installation, where supported, can make source changes visible without a rebuild. Check a built wheel separately, because an editable installation and the wheel can include different files.

Identify the file Python loaded

With the interpreter your tests use, import the package and print inventory.__file__. For a regular package, this points to the initializer that was loaded. It may point into the checkout with editable installation. In a fresh wheel verification environment, it should identify the installed package. Run that verification outside the repository.

Avoid solving a failed import by adding unrelated locations to machine-wide PYTHONPATH. That can conceal missing installation steps. A deliberate development installation and a small public usage test give a more reproducible result.

Try the installed import before migrating

A checkout might have a root helper called benchmark.py that is never intended for distribution. A test can accidentally import it when the repository root is visible. Install the built wheel outside the checkout and run the relevant import or public command. An error from there identifies a mismatch between the code and the install contract.

If you migrate to src, move the import package, update backend discovery, and verify development and installed copies with the same named test. Remove any temporary path workaround you added during diagnosis. A test runner should exercise a deliberately installed package, rather than quietly copying a checkout-specific import assumption.

Keep editable and wheel checks separate

An editable installation can be right for a contributor changing source. A tested wheel is right for someone using the exact release. Document both paths when you need both. A wheel install uses the files in the artifact, so it can catch missing module or data files that a contributor's editable check does not.

If the checkout contains multiple distributions, name their boundaries explicitly. Testing one from a monorepo root does not guarantee it declares an import from a sibling distribution. Reproducing the install in a clean environment can turn a confusing import error into a precise missing dependency report.

Put examples and data in the right place

Tests that serve only verification can stay under tests/. Data that users need at runtime belongs with the installed package and needs a distinct packaging check. Published examples should normally call the same import or command readers will use. That lets you change internal locations without rewriting every instruction.

If you move to src, build a wheel and test the installed copy. That check verifies that users get the importable files and runtime data you intended.

Sources and further reading

Related reading

Browse Tools and workflows · Explore project tutorials

Search PythonProjects.org