Support a "flat" package layout in `uv init`

[mgaitan]

uv init mypackage currently generates a "src" layout:

.
├── pyproject.toml
├── README.md
└── src
    └── mypackage
        └── __init__.py

That's okay as the default because this layout has some known advantages.

However, it isn't a widely used convention, especially for simple, pure Python packages.

So I propose to allow creating a flat layout with uv init --flat:

.
├── pyproject.toml
├── README.md
└── mypackage
    └── __init__.py

Paraphrasing The Hitchhiker's Guide to Python:

Python allows many tricks, and some of them are potentially dangerous. [Python's] philosophy, very different from highly defensive languages like Java, which provide many mechanisms to prevent misuse, is expressed by the saying: “We are all responsible users.”

and (abusing) the Zen of Python:

Flat is better than nested.

[zanieb]

Thanks for the writeup!

I'm pretty hesitant, honestly. This results in confusing behavior for users due to the module search path including the package by default. I think we may be better off taking an opinionated stance here.

[danielgafni]

The lack of flat layout support makes migrating large monorepos (https://github.com/dagster-io/dagster) with dozens of packages much harder.

I agree with your point about the potential confusion with automatic package discovery when using the flat layourt, but there are already thousands of Python projects using it.

I think uv should prefer the src layout and use it by default, but at the same time adding support for flat layout seems reasonable to me. The opposite decision will slow down uv adoption.

[zanieb]

@danielgafni Sorry if I'm missing something here, but we just don't create a flat layout in uv init — as far as I know, uv itself should fully support flat layouts otherwise?

[danielgafni]

Hey, I first tried using the flat layout and got import errors for our packages.

For example, with the following pyproject.toml, running

uv pip install -e python_modules/dagster-pipes

passes with both flat and src layout, but only the src layout makes the package available for importing. I'm not sure what can cause this behavior. Moving dagster_pipes to /src and re-running uv pip install solves the problem, that's why I assumed flat layout wasn't supported.

[danielgafni]

Actually, I can't reproduce this issue anymore :open_mouth: Everything seems to be working, probably something was wrong on my side, sorry about that!

[mgaitan]

@zanieb I guess my original request have been implemented via uv init --app right? . We could close this.

[charliermarsh]

Correct! Thanks @mgaitan.

[Winand]

When we use --lib uv creates a folder src/<NAME> and adds hatchling build system.

In hatchling docs i read that by default it searches for a package in <NAME>, src/<NAME>, <NAME>.py and <NAMESPACE>/<NAME>.

So do I understand correctly that i can place my package in project's root dir? So the "flat" layout is already supported, right?

---

Update: also an example for Packaged applications won't work as described in docs, because src/example_packaged_app differs from project name "example-pkg" so hatchling won't find that package.