> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/astral-sh/uv/llms.txt
> Use this file to discover all available pages before exploring further.

# uv init

> Create a new Python project

Create a new Python project or script.

## Usage

```bash theme={null}
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

<ParamField path="PATH" type="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.
</ParamField>

## Options

### Project Configuration

<ParamField path="--name" type="string">
  The name of the project.

  Defaults to the name of the directory. Cannot be used with `--script`.
</ParamField>

<ParamField path="--package" flag>
  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.
</ParamField>

<ParamField path="--no-package" flag>
  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`.
</ParamField>

<ParamField path="--app" flag>
  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.
</ParamField>

<ParamField path="--lib" flag>
  Create a project for a library.

  A library is a project that is intended to be built and distributed as a Python package.
</ParamField>

<ParamField path="--script" flag>
  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.
</ParamField>

<ParamField path="--bare" flag>
  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.
</ParamField>

<ParamField path="--description" type="string">
  Set the project description.
</ParamField>

<ParamField path="--no-description" flag>
  Disable the description for the project.
</ParamField>

### Build Configuration

<ParamField path="--build-backend" type="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`
</ParamField>

### Version Control

<ParamField path="--vcs" type="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.
</ParamField>

<ParamField path="--no-readme" flag>
  Do not create a `README.md` file.
</ParamField>

<ParamField path="--author-from" type="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.
</ParamField>

### Python Configuration

<ParamField path="--python" type="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`
</ParamField>

<ParamField path="--no-pin-python" flag>
  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.
</ParamField>

### Workspace Options

<ParamField path="--no-workspace" flag>
  Avoid discovering a workspace and create a standalone project.

  By default, uv searches for workspaces in the current directory or any parent directory.
</ParamField>

## Examples

### Create a new application

```bash theme={null}
uv init my-app
```

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

### Create a new library

```bash theme={null}
uv init --lib my-library
```

Creates a library project intended to be built and distributed as a Python package.

### Create a PEP 723 script

```bash theme={null}
uv init --script hello.py
```

Creates a standalone Python script with inline dependency metadata.

### Create a project with a specific build backend

```bash theme={null}
uv init --build-backend setuptools my-package
```

Creates a package project using setuptools as the build backend.

### Create a bare project

```bash theme={null}
uv init --bare
```

Creates only a `pyproject.toml` file without additional scaffolding.

### Create a project with specific Python version

```bash theme={null}
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:

```bash theme={null}
uv init --app my-web-app
cd my-web-app
uv add fastapi uvicorn
```

### Library Development

For packages to be published to PyPI:

```bash theme={null}
uv init --lib my-library --build-backend hatchling
cd my-library
uv add --dev pytest black ruff
```

### Script Development

For standalone scripts with dependencies:

```bash theme={null}
uv init --script data-processor.py
uv run data-processor.py
```

## Related Commands

* [`uv add`](/cli/add) - Add dependencies to the project
* [`uv sync`](/cli/sync) - Sync the project environment
* [`uv run`](/cli/run) - Run a command in the project environment
* [`uv lock`](/cli/lock) - Update the project lockfile