Understanding uv init Project Types
The uv init command creates different types of Python projects through various flags, each optimized for specific use cases. Here’s how they compare:
| Flag | Build System | Structure | Entry Point | Distribution | Use Case |
|---|---|---|---|---|---|
--app (default) | ❌ | Flat | main.py | Not intended | Web apps, scripts |
--lib | ✅ | src/ layout | ❌ | PyPI packages | Reusable libraries |
--package | ✅ | src/ layout | Console script | Installable apps | CLI tools |
--bare | ❌ | Minimal | ❌ | Manual setup | Custom projects |
--no-package | ❌ | Flat | main.py | Explicitly blocked | Internal apps |
The Four Main Project Types
Applications (--app)
Applications are standalone programs like web servers, CLI tools, or scripts. This is the default when you run uv init.
Application projects use a flat structure with main.py and no build system configuration since they aren’t distributed as packages. The pyproject.toml focuses on runtime dependencies without packaging metadata.
Libraries (--lib)
Libraries are designed for distribution and reuse. They use the src/package_name/ layout for better testing isolation and include a py.typed file for type checking support.
The pyproject.toml includes complete build system configuration with hatchling as the default backend, enabling wheel and source distribution creation for PyPI.
Packageable Applications (--package)
Some applications benefit from being installable as packages, like CLI tools distributed through PyPI.
The --package flag combines application and library features - using the src/ layout but adding [project.scripts] entry points that create executable commands when installed.
Minimal Projects (--bare)
The --bare flag creates only a pyproject.toml file with essential metadata. This suits existing projects or situations requiring complete structural control.
No sample code, README, or directory structure gets generated.
How Project Types Differ
The key differences between project types lie in three areas:
Build System: Libraries and packageable applications include [build-system] configuration for creating distributions. Applications and bare projects omit this unless you need packaging capabilities.
Project Structure: Libraries and packageable applications use the src/ layout for better testing isolation. Applications use flat structures for simplicity.
Entry Points: Packageable applications define console scripts that become executable commands when installed. Other project types handle execution differently.