uv init: Project layouts, defaults and terminology

[MikeHart85]

Thank you for working on this wonderful tool.

I'd like to suggest several changes to uv init arguments and defaults, with the following goals:

• Use consistent and established terminology
• Options to support common usage patterns, so seasoned Python developers can have things their way
• Defaults which guide Python newcomers towards best practices, hint at available features

Much of this revolves around separating the concept of project directory structure ("layout" in Python) from project purpose and contents ("library", "application", etc), as well as disambiguating the overloaded term "package". Currently these terms are conflated and inconsistent in uv.

Apologies in advance for the massive wall of text.

Current behavior

"Application" (default):

$ uv init [--app] project-name
$ tree project-name/
project-name/
├── hello.py
├── pyproject.toml  # only [project] (builds don't work due to misnamed hello.py)
└── README.md

"Library":

$ uv init --lib project-name
project-name/
├── pyproject.toml  # [project], [build-system]
├── README.md
└── src
    └── project_name
        ├── __init__.py  # contains "hello" code
        └── py.typed

"Application Package":

$ uv init [--app] --package project-name  # --app appears to do nothing here, in spite of docs suggesting it
project-name/
├── pyproject.toml  # [project], [project.scripts], [build-system]
├── README.md
└── src
    └── project_name
        └── __init__.py  # contains "hello" code

Suggested behavior

Src layout (default):

$ uv init [--layout=src] project-name
project-name/
├── pyproject.toml  # [project], [project.scripts], [build-system]
├── README.md
└── src
    └── project_name
        └── __init__.py  # empty
        └── example.py   # def say_hello(): print("...")

Flat layout:

$ uv init --layout=flat project-name
project-name/
├── pyproject.toml  # [project], [project.scripts], [build-system]
├── README.md
└── project_name
    └── __init__.py  # empty
    └── example.py   # def say_hello(): print("...")

Single module layout:

$ uv init --layout=single project-name
project-name/
├── pyproject.toml  # [project], [project.scripts], [build-system]
├── README.md
└── project_name.py  # def say_hello(): print("...") 
                     # NOTE: file name MUST be project_name.py (it replaces the package)

Bare / no layout:

$ uv init --layout=<bare|none> project-name  # maybe pick one rather than allowing either one
project-name/
├── pyproject.toml  # [project]
└── README.md

• Add --no-entrypoint to suppress [project.scripts]
  • Consider adding --entrypoint=name to customize key name under [project.scripts], defaulting to project-name
• Add --build-system=<hatchling|...|none>, with hatchling being default, and none to suppress [build-system]
  • Consider adding --no-build-system, synonymous with --build-system=none, for symmetry
  • Remove --no-package
• Add --typed to create a py.typed
• Remove --package
• Remove --app, or:
  • Make synonymous with --entrypoint=project-name
  • Consider generating example code to be more "app-like"
  • Consider __main__.py [1] instead of example.py, but that may unnecessarily confuse newcomers
• Remove --lib, or:
  • Make synonymous with --no-entrypoint
  • Consider generating example code to be more "lib-like"
  • Consider implying --typed (IMO explicit uv init --lib --typed would be better)

I would just remove --lib and --app to keep things simple.

Reasoning for suggestions

• "Entry point" is the established term for shortcuts to functions that ultimately become commands when installed [2]
• "Layout" is the established term for project directory structure [3], [4]
  • Src layout should be default
    • It is the most robust, avoids import conflicts, most suitable for serious projects
    • Prevents needing to restructure when project outgrows other layouts
    • Uv eliminates its main downside (very easy to get up-to-date REPL):
    • uv run python
    • >>> import project_name
  • Flat layout is also quite popular, and currently not available in uv init
  • Single module (current --app, default) layout is the most limited
    • It should most certainly not be the default
    • Has issues and limitations which will confuse newcomers
    • Should really only be used for single file projects, if at all
    • Currently broken for builds due to example file always being hello.py
    • Changing file to project_name.py allows builds to work
  • --layout=none for custom layouts, notebook projects, etc
• Project layout is not related to whether it is an "app" or "lib"
  • Any layout can be an application or a library
  • Project contents and usage determine whether it is an application, or library, or both
  • Not as clear cut in Python as "executable" vs "library" projects in compiled languages, shouldn't attempt to force that pattern since it doesn't fit
  • "App" and "Application" terms should probably be reserved for possible integration with tools like PyInstaller, cxfreeze, etc (IE, generating a self-contained binary executable for distribution)
  • A library isn't required to have PEP 561 compliant py.typed
• Current use of --package conflates it with build-system/distribution, src layout, and absence of py.typed
  • A "package" in Python is simply a directory with an __init__.py [5]
  • Ideally, the term "package" should not be used for anything else, to avoid confusion
  • A package doesn't have to be distributable / have a build-system
  • Single module (IE, non-package) distributions are a thing (hence --layout=single with build-system)
    • A prominent example would be six, which is a single module library: PyPI GitHub
• __init__.py should not contain general purpose code
  • __init__.py is a special purpose file, and putting arbitrary code there can easily have unintended side effects
  • Its meant for initializing packages, making symbols available at package level, __all__, etc [6]
  • Putting the hello world example there can mislead newcomers into thinking this is where all their code belongs
• Don't see a reason not to include entry point and build system by default in all layouts which support it
  • Can easily be removed / ignored / switched off if not needed
  • Default presence shows newcomers what is possible / where it belongs
  • Reduces friction when a project graduates from hobby to distribution
• Layouts are mutually exclusive, hence grouping them under one argument with a value
  • Less room for confusion than having multiple differently named options, which may or may not be mixable
• All three layouts (src, flat, single) work with uv run project-name and uv build as shown
  • Only uv init needs to change, to support generating them

Context

• Src layout used to be the default until: Add --app and --lib options to uv init #6689
• "App", "lib" and "package" terminology introduced around here: Add support for virtual projects #6585

Discussion in the latter floated using "distribution" (ala PDM) instead of "package" (ala Poetry) in some contexts, but it seems "package" won out. I would argue "distribution" would have been the correct choice. As mentioned, "package" has a very specific meaning in Python, not strictly related to whether the project is built for distribution.

Thanks for considering.

[Weilet]

I think uv init --layout=<bare|none> is very useful for me when it comes to creating a Django app. I am searching for a way to initialize the project with only a pyproject.toml, so that I can use django-admin to manage my project without too much unnecessary stuff.

[zanieb]

Thanks for your thoughts! I'll own responding to this and seeing what we can integrate.

[drcongo]

I've only ended up in this thread because I was confused about the default behaviour here - to me it feels like uv init with no options should do the equivalent of uv init --layout=<bare|none> mentioned above and create nothing but a pyproject.toml. I can't imagine ever needing uv to create the .gitignore, .git/ and hello.py so for that to be the default seems kinda wild.

Feel free to ignore me though, I realise I'm a data point of one and maybe those do somehow make sense to other devs.

[thcrt]

I think both the options available and their documentation are somewhat confusing at present. There are multiple different decisions in determining how a project should be structured, but those decisions seem to be split between uv init's sub-optimal presets and further configuration options in pyproject.toml that need to be set manually.

Often, I might want to create a standalone application, such as a Flask webapp. This doesn't need to expose a Python API or be imported into other projects, so I would assume I don't need a build system to turn my code into a package. I'll probably just write a Dockerfile that will produce a container image with my dependencies installed, ready to run my code directly.

In terms of layout, I probably want a 'flat layout', where my code is in ./myapp. This is what Flask, for instance, recommends. That's not available from uv init -- I have to choose between:

• a 'Packaged Application'
  This configures a build system I don't need and nests all my code in ./src/myapp.
• a 'Library'
  This has all the downsides of a 'Packaged Application', and also doesn't specify a command-line entry point.
• an 'Application'
  This puts my code in ., the project root, which will get cluttered quickly if I want to build anything bigger than a single-file script.

None of these do what I want! No matter what I choose, I'll have to move things around and change pyproject.toml to account for the changes.

This is addressed in #6460, which seems to be resolved by #6585, adding 'Virtual Projects', which don't get built or installed as packages. But the only place this is documented is under the setting that enables it, where I can read a brief summary of what a virtual project is, but not why I might want to use one. #6585 states that a project will be treated as 'virtual' merely by the lack of a [build-system] in pyproject.toml, but this isn't documented there. The documentation on uv init doesn't mention 'virtual projects' at all.

A brief aside regarding 'virtual projects' and uv init: it seems like uv init --virtual creates a virtual project, but the --virtual flag can't be used with --package (for a 'Packaged Application') or with --lib (for a 'Library'). And uv init --virtual produces exactly the same result as uv init without the --virtual flag, not even adding package = false to pyproject.toml. So it's not clear to me what the flag is supposed to do.

I love uv as a whole, but this is extremely confusing to me. Maybe I'm mistaken on some of this, and I'm doing something wrong, in which case please feel free to correct me.

I agree. As someone migrating from Poetry to uv, uv's project layout options were a lot harder for me to understand.

[jromal]

I've only ended up in this thread because I was confused about the default behaviour here - to me it feels like uv init with no options should do the equivalent of uv init --layout=<bare|none> mentioned above and create nothing but a pyproject.toml. I can't imagine ever needing uv to create the .gitignore, .git/ and hello.py so for that to be the default seems kinda wild.

I can follow the logic for not wanting a "hello.py", but I can fully understand that an example (in the terms mentioned by the request) is a good thing for most of the people. I cannot support not creating the ".git" and ".gitignore" files. All amateurs (which I count myself) should have it, but many do not know about it. Nothing serious should be done without them.

What we need is a revamp on the "layout" structure. Which is confusing. I had to test all the options to understant what is meant. With the "--layout" option is clear and does what people do. .

[clbarnes]

I can't imagine ever needing uv to create the .gitignore, .git/ and hello.py so for that to be the default seems kinda wild.

Counterpoint: I can't imagine ever needing to start a python project without a .gitignore file, and it's annoying to go and fetch the exact same file every time, when uv aims to be a one-stop shop. Of course, a minority of people don't use git for version control, although a host of other dev tools respect .gitignore when it comes to ignoring files to search/ index/ include so arguably it's useful to have even if you're not using git.

I think that hello.py, while deleted/ renamed immediately by developers who start new projects regularly, acts as a useful marker for where your functional code should go. Between script, app, and library projects, flat or src layouts, multi-package projects etc., that may not be clear to someone less experienced, or even an experienced developer who hasn't followed the breakneck pace of the evolution of python's best practices in the last few years.

[drcongo]

@clbarnes Not everyone is starting a new project, nor running uv where their .gitignore, .git repo or README lives - think mono-repos, projects where uv is inside docker, projects where you're in a git submodule etc. - in some of these cases, creating a .git repo is a positively hostile thing to do as you can suddenly end up with nested repositories being pushed and then someone (me) has to untangle it.

[allenc97]

Lots of insightful thoughts. I would also argue for project layout to be separated from rather the project is intended to be an application or a python package. In fact, it is not uncommon for python applications to also use a src layout. This is especially useful with containers as mounting all source code files is just a singular mount, or for standardized use in CI/CD.

[Bunker-D]

I second the idea of a more customized option for uv init. I would also like the option to setup a personal default configuration.

Additionally, it would be neat to be able to customize the starting .gitignore (at least, setting up a personal default .gitignore).

Typically, I would systematically exclude .*_cache (.pytest_cache and .ruff_cache) and .venv, and I'm pretty sure developers' needs would change based on their favorite tools.

[Bunker-D]

Also, while I don't disagree with @clbarnes 's justification of hello.py (making me neutral about the creation of hello.py), I think src/<…>/__init__.py should not be initialized with code inside it. My big issue with this behavior is that this dummy code not visible at first sight when looking at the project. Worse than having to clean it up, devs might miss it,