Skip to main content
Create a new Python project or script.

​
Usage

uv init [OPTIONS] [PATH]

​
Description

Initialize a new Python project following the pyproject.toml specification. If a pyproject.toml already exists at the target, uv will exit with an error. If a pyproject.toml is found in any of the parent directories of the target path, the project will be added as a workspace member of the parent. Some project state is not created until needed:
  • The project virtual environment (.venv) is created lazily during the first sync
  • The lockfile (uv.lock) is created during the first sync

​
Arguments

​
PATH
string
The path to use for the project/script.Defaults to the current working directory when initializing an app or library. Required when initializing a script. Accepts relative and absolute paths.If a pyproject.toml is found in any of the parent directories of the target path, the project will be added as a workspace member of the parent, unless --no-workspace is provided.

​
Options

​
Project Configuration

​
--name
string
The name of the project.Defaults to the name of the directory. Cannot be used with --script.
​
--package
Set up the project to be built as a Python package.Defines a [build-system] for the project. This is the default behavior when using --lib or --build-backend.When using --app, this will include a [project.scripts] entrypoint and use a src/ project structure.
​
--no-package
Do not set up the project to be built as a Python package.Does not include a [build-system] for the project. This is the default behavior when using --app.
​
--app
Create a project for an application.This is the default behavior if --lib is not requested. This project kind is for web servers, scripts, and command-line interfaces.By default, an application is not intended to be built and distributed as a Python package. The --package option can be used to create an application that is distributable.
​
--lib
Create a project for a library.A library is a project that is intended to be built and distributed as a Python package.
​
--script
Create a script.A script is a standalone file with embedded metadata enumerating its dependencies, along with any Python version requirements, as defined in the PEP 723 specification.PEP 723 scripts can be executed directly with uv run.By default, adds a requirement on the system Python version; use --python to specify an alternative Python version requirement.
​
--bare
Only create a pyproject.toml.Disables creating extra files like README.md, the src/ tree, .python-version files, etc.When combined with --script, the script will only contain the inline metadata header.
​
--description
string
Set the project description.
​
--no-description
Disable the description for the project.

​
Build Configuration

​
--build-backend
string
default:"hatchling"
Initialize a build-backend of choice for the project.Implicitly sets --package. Options include:
  • hatchling - Use Hatchling as the build backend
  • flit - Use Flit as the build backend
  • pdm - Use PDM as the build backend
  • setuptools - Use setuptools as the build backend
  • maturin - Use Maturin as the build backend
  • scikit - Use scikit-build-core as the build backend
Environment variable: UV_INIT_BUILD_BACKEND

​
Version Control

​
--vcs
string
default:"git"
Initialize a version control system for the project.By default, uv will initialize a Git repository (git). Use --vcs none to explicitly avoid initializing a version control system.
​
--no-readme
Do not create a README.md file.
​
--author-from
string
default:"auto"
Fill in the authors field in the pyproject.toml.By default, uv will attempt to infer the author information from some sources (e.g., Git) (auto). Use --author-from git to only infer from Git configuration. Use --author-from none to avoid inferring the author information.

​
Python Configuration

​
--python
string
The Python interpreter to use to determine the minimum supported Python version.See uv help python to view supported request formats.Environment variable: UV_PYTHON
​
--no-pin-python
Do not create a .python-version file for the project.By default, uv will create a .python-version file containing the minor version of the discovered Python interpreter, which will cause subsequent uv commands to use that version.

​
Workspace Options

​
--no-workspace
Avoid discovering a workspace and create a standalone project.By default, uv searches for workspaces in the current directory or any parent directory.

​
Examples

​
Create a new application

uv init my-app
This creates a new application project in the my-app directory with a basic structure.

​
Create a new library

uv init --lib my-library
Creates a library project intended to be built and distributed as a Python package.

​
Create a PEP 723 script

uv init --script hello.py
Creates a standalone Python script with inline dependency metadata.

​
Create a project with a specific build backend

uv init --build-backend setuptools my-package
Creates a package project using setuptools as the build backend.

​
Create a bare project

uv init --bare
Creates only a pyproject.toml file without additional scaffolding.

​
Create a project with specific Python version

uv init --python 3.11
Creates a project configured for Python 3.11.

​
Common Patterns

​
Application Development

For web applications or CLI tools not intended for distribution: 
uv init --app my-web-app
cd my-web-app
uv add fastapi uvicorn

​
Library Development

For packages to be published to PyPI: 
uv init --lib my-library --build-backend hatchling
cd my-library
uv add --dev pytest black ruff

​
Script Development

For standalone scripts with dependencies: 
uv init --script data-processor.py
uv run data-processor.py
  • uv add - Add dependencies to the project
  • uv sync - Sync the project environment
  • uv run - Run a command in the project environment
  • uv lock - Update the project lockfile

Build docs developers (and LLMs) love

Get started for freeTalk to us