uv init: Scaffold a New Python Project
uv init scaffolds a new Python project, writing pyproject.toml and a starter source layout.
uv init is the starting point for a uv-managed project. It picks a sensible layout and pins a Python version so the project is reproducible from day one.
What it does
uv init creates pyproject.toml, a .python-version file, a README, and a starter module or script. The flavor (--app, --lib, --package) controls whether you get a runnable app, an importable library with a src layout, or a packaged distribution.
Common usage
uv init my-app
uv init --lib my-library
uv init --package my-package
uv init --python 3.12 my-app
uv init --appOptions
| Flag | What it does |
|---|---|
| --app | Create an application layout (the default) |
| --lib | Create a library with a src/ layout and build backend |
| --package | Make the project a packaged, buildable distribution |
| --python <version> | Pin the project to a Python version |
| --no-readme | Skip generating README.md |
| --bare | Create only pyproject.toml, no extra files |
In CI
uv init is a local scaffolding step, not a pipeline step; the generated files belong in version control. In CI you consume those files with uv sync. If you generate fixtures dynamically in a job, --bare keeps the output minimal.
Common errors in CI
"error: Project is already initialized in <dir>" means a pyproject.toml already exists; uv will not overwrite it. "error: Failed to parse --python request" means a version like 3.12 was malformed (use 3.12, not 3,12). A read-only working directory yields a permission error on the file write; init into a writable path.