uv init: create a new Python project with uv
- tool
- uv
- versions
- uv 0.12
- os
- any
uv init NAME creates a folder NAME with a pyproject.toml, a README.md, a .python-version pin and a git repository; uv init without a name turns the current folder into a project. From there, uv add PACKAGE adds dependencies and uv run executes code in the project's .venv, which uv creates on first use. --lib, --app, --package, --bare and --script choose the layout.
Create a project
uv init demo --python 3.13 -q
cd demo
find . -type f -not -path './.git/*' | sort
echo "--- pyproject.toml"
cat pyproject.tomlOutput
./.gitignore ./.python-version ./README.md ./pyproject.toml ./src/demo/__init__.py --- pyproject.toml [project] name = "demo" version = "0.1.0" description = "Add your description here" readme = "README.md" requires-python = ">=3.13" dependencies = [] [project.scripts] demo = "demo:main" [build-system] requires = ["uv_build>=0.12.19,<0.13.0"] build-backend = "uv_build"
With uv 0.12 the default layout is a packaged application: code under src/demo/, a [build-system] using uv_build, and a demo command in [project.scripts].
Layout options
| Command | Creates |
|---|---|
| uv init NAME | Project folder with pyproject.toml, README.md, .python-version, .gitignore and git |
| uv init --app --no-package | An application without a build system: a single main.py |
| uv init --lib | A library: src/NAME/__init__.py, py.typed and a build system |
| uv init --package | An application built as a package, with a console script entry point |
| uv init --bare | Only pyproject.toml (no README, no .python-version, no git) |
| uv init --script tool.py | A single script with inline (PEP 723) metadata, no project |
| uv init --build-backend hatch | Use another build backend (hatch, flit, pdm, poetry, setuptools, maturin, scikit) |
| uv init --vcs none | Skip git init |
Next steps
cd demo
uv add requests # adds to [project.dependencies] and writes uv.lock
uv add --dev pytest # adds to the dev dependency group
uv run demo # runs the console script in .venv
uv run pytestCommit pyproject.toml, uv.lock and .python-version; .venv is already in the generated .gitignore. When the folder is inside an existing uv workspace, uv init adds the new project as a workspace member; pass --no-workspace to keep it standalone.