> ## 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.

# Working with Projects

> A complete guide to creating and managing Python projects with uv

## Overview

uv supports managing Python projects with dependencies defined in `pyproject.toml`. This guide covers the full workflow from initialization to deployment.

## Creating a new project

You can create a new Python project using `uv init`:

<CodeGroup>
  ```bash Create in new directory theme={null}
  uv init hello-world
  cd hello-world
  ```

  ```bash Initialize in current directory theme={null}
  mkdir hello-world
  cd hello-world
  uv init
  ```
</CodeGroup>

uv creates the following files:

```text theme={null}
├── .gitignore
├── .python-version
├── README.md
├── main.py
└── pyproject.toml
```

Test your new project:

```bash theme={null}
uv run main.py
# Output: Hello from hello-world!
```

## Project structure

After running your first project command (`uv run`, `uv sync`, or `uv lock`), uv creates additional files:

```text theme={null}
.
├── .venv
│   ├── bin
│   ├── lib
│   └── pyvenv.cfg
├── .python-version
├── README.md
├── main.py
├── pyproject.toml
└── uv.lock
```

### Key files explained

<AccordionGroup>
  <Accordion title="pyproject.toml - Project metadata">
    Contains your project's dependencies and metadata:

    ```toml theme={null}
    [project]
    name = "hello-world"
    version = "0.1.0"
    description = "Add your description here"
    readme = "README.md"
    dependencies = []
    ```

    You can edit this file manually or use commands like `uv add` and `uv remove`.

    <Tip>See the official [pyproject.toml guide](https://packaging.python.org/en/latest/guides/writing-pyproject-toml/) for more details.</Tip>
  </Accordion>

  <Accordion title=".python-version - Python version pinning">
    Specifies the default Python version for your project. uv uses this file to determine which Python version to use when creating the virtual environment.
  </Accordion>

  <Accordion title=".venv - Virtual environment">
    Contains your project's isolated Python environment where dependencies are installed. See the [project environment documentation](../concepts/projects/layout.md#the-project-environment) for more details.
  </Accordion>

  <Accordion title="uv.lock - Lockfile">
    A cross-platform lockfile with exact dependency versions. Unlike `pyproject.toml` (which specifies broad requirements), the lockfile contains exact resolved versions.

    This file is human-readable TOML but managed by uv — don't edit it manually.

    <Note>Always commit `uv.lock` to version control for consistent installations across machines.</Note>
  </Accordion>
</AccordionGroup>

## Managing dependencies

<Steps>
  <Step title="Add a dependency">
    Add packages to your project with `uv add`:

    ```bash theme={null}
    uv add requests
    ```

    This updates `pyproject.toml`, `uv.lock`, and your virtual environment.
  </Step>

  <Step title="Add version constraints">
    Specify version constraints or alternative sources:

    <CodeGroup>
      ```bash Specific version theme={null}
      uv add 'requests==2.31.0'
      ```

      ```bash Git dependency theme={null}
      uv add git+https://github.com/psf/requests
      ```
    </CodeGroup>
  </Step>

  <Step title="Migrate from requirements.txt">
    Import all dependencies from an existing requirements file:

    ```bash theme={null}
    uv add -r requirements.txt -c constraints.txt
    ```
  </Step>

  <Step title="Remove dependencies">
    Remove packages you no longer need:

    ```bash theme={null}
    uv remove requests
    ```
  </Step>

  <Step title="Upgrade packages">
    Update specific packages to the latest compatible version:

    ```bash theme={null}
    uv lock --upgrade-package requests
    ```

    The `--upgrade-package` flag updates the specified package while keeping the rest of the lockfile intact.
  </Step>
</Steps>

## Running commands

`uv run` executes scripts or commands in your project environment:

```bash theme={null}
# Run a Python script
uv run example.py

# Run a tool (uv adds it first if needed)
uv add flask
uv run -- flask run -p 3000
```

<Note>
  `uv run` automatically syncs your environment before execution, ensuring dependencies match `uv.lock`.
</Note>

### Using the project environment directly

Alternatively, manually sync and activate the environment:

<CodeGroup>
  ```bash macOS / Linux theme={null}
  uv sync
  source .venv/bin/activate
  flask run -p 3000
  python example.py
  ```

  ```powershell Windows theme={null}
  uv sync
  .venv\Scripts\activate
  flask run -p 3000
  python example.py
  ```
</CodeGroup>

<Warning>
  The virtual environment must be active to run scripts without `uv run`. Activation differs per shell and platform.
</Warning>

## Viewing your version

Check your package version:

<CodeGroup>
  ```bash Full output theme={null}
  uv version
  # hello-world 0.7.0
  ```

  ```bash Short format theme={null}
  uv version --short
  # 0.7.0
  ```

  ```bash JSON format theme={null}
  uv version --output-format json
  # {
  #     "package_name": "hello-world",
  #     "version": "0.7.0",
  #     "commit_info": null
  # }
  ```
</CodeGroup>

See the [publishing guide](./packaging.mdx#updating-your-version) for details on updating your version.

## Building distributions

Build source distributions and wheels for your project:

```bash theme={null}
uv build
```

By default, artifacts are placed in a `dist/` subdirectory:

```bash theme={null}
ls dist/
# hello-world-0.1.0-py3-none-any.whl
# hello-world-0.1.0.tar.gz
```

See the [building projects documentation](../concepts/projects/build.md) for more details.

## Complete workflow example

Here's a complete project workflow from initialization to building:

<Steps>
  <Step title="Initialize project">
    ```bash theme={null}
    uv init my-app
    cd my-app
    ```
  </Step>

  <Step title="Add dependencies">
    ```bash theme={null}
    uv add fastapi uvicorn
    ```
  </Step>

  <Step title="Write your code">
    Create your application in `main.py`:

    ```python theme={null}
    from fastapi import FastAPI

    app = FastAPI()

    @app.get("/")
    def read_root():
        return {"message": "Hello from my-app!"}
    ```
  </Step>

  <Step title="Run your application">
    ```bash theme={null}
    uv run uvicorn main:app --reload
    ```
  </Step>

  <Step title="Add development dependencies">
    ```bash theme={null}
    uv add --dev pytest pytest-cov
    ```
  </Step>

  <Step title="Build for distribution">
    ```bash theme={null}
    uv build
    ```
  </Step>
</Steps>

## Next steps

<CardGroup cols={2}>
  <Card title="Projects concept" icon="folder" href="../concepts/projects/index.md">
    Learn more about how uv projects work
  </Card>

  <Card title="Export lockfiles" icon="file-export" href="../concepts/projects/export.md">
    Export to different formats
  </Card>

  <Card title="Running scripts" icon="play" href="./scripts.mdx">
    Learn about standalone Python scripts
  </Card>

  <Card title="Command reference" icon="terminal" href="../reference/cli.md#uv">
    View all uv commands
  </Card>
</CardGroup>