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

# Quickstart

> Get started with uv in minutes - from installation to your first working Python project

uv is an extremely fast Python package and project manager. This guide will get you from installation to running your first project in minutes.

## Install uv

<CodeGroup>
  ```bash macOS and Linux theme={null}
  curl -LsSf https://astral.sh/uv/install.sh | sh
  ```

  ```powershell Windows theme={null}
  powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
  ```

  ```bash pip theme={null}
  pip install uv
  ```

  ```bash pipx theme={null}
  pipx install uv
  ```
</CodeGroup>

Verify the installation:

```bash theme={null}
uv --version
```

<Tip>
  If installed via the standalone installer, you can update uv with `uv self update`
</Tip>

## Create your first project

<Steps>
  <Step title="Initialize a new project">
    Create a new Python project with `uv init`:

    ```console theme={null}
    $ uv init example
    Initialized project `example` at `/home/user/example`
    ```

    This creates a project structure with:

    * `pyproject.toml` - Project metadata and dependencies
    * `.python-version` - Python version pin
    * `main.py` - Sample Python file
    * `README.md` - Project documentation
  </Step>

  <Step title="Add a dependency">
    Navigate to your project and add a package:

    ```console theme={null}
    $ cd example

    $ uv add ruff
    Creating virtual environment at: .venv
    Resolved 2 packages in 170ms
       Built example @ file:///home/user/example
    Prepared 2 packages in 627ms
    Installed 2 packages in 1ms
     + example==0.1.0 (from file:///home/user/example)
     + ruff==0.5.0
    ```

    uv automatically:

    * Creates a virtual environment (`.venv`)
    * Updates `pyproject.toml` with the dependency
    * Generates a lockfile (`uv.lock`)
    * Installs the package
  </Step>

  <Step title="Run a command">
    Execute commands in your project environment with `uv run`:

    ```console theme={null}
    $ uv run ruff check
    All checks passed!
    ```

    Run your Python script:

    ```console theme={null}
    $ uv run main.py
    Hello from example!
    ```
  </Step>
</Steps>

## Working with dependencies

### Lock and sync workflow

Generate or update the lockfile without installing:

```console theme={null}
$ uv lock
Resolved 2 packages in 0.33ms
```

Sync your environment with the lockfile:

```console theme={null}
$ uv sync
Resolved 2 packages in 0.70ms
Audited 1 package in 0.02ms
```

<Tip>
  `uv run` automatically syncs before running, so you don't need to manually run `uv sync` in most cases
</Tip>

### Add dependencies with version constraints

```console theme={null}
# Specific version
$ uv add 'requests==2.31.0'

# Version range
$ uv add 'requests>=2.30.0,<3.0.0'

# Git dependency
$ uv add git+https://github.com/psf/requests
```

### Remove dependencies

```console theme={null}
$ uv remove requests
```

## Manage Python versions

uv can install and manage Python versions for you.

### Install Python

```console theme={null}
$ uv python install 3.12 3.13 3.14
Installed 3 versions in 972ms
 + cpython-3.12.12-macos-aarch64-none (python3.12)
 + cpython-3.13.9-macos-aarch64-none (python3.13)
 + cpython-3.14.0-macos-aarch64-none (python3.14)
```

### Use a specific Python version

Pin your project to a specific Python version:

```console theme={null}
$ uv python pin 3.11
Pinned `.python-version` to `3.11`
```

Create a virtual environment with a specific Python version:

```console theme={null}
$ uv venv --python 3.12.0
Using Python 3.12.0
Creating virtual environment at: .venv
Activate with: source .venv/bin/activate
```

### View installed Python versions

```console theme={null}
$ uv python list
```

## Run tools with uvx

Execute Python tools without installing them using `uvx` (an alias for `uv tool run`):

```console theme={null}
$ uvx pycowsay 'hello world!'
Resolved 1 package in 167ms
Installed 1 package in 9ms
 + pycowsay==0.0.0.2
  """

  ------------
< hello world! >
  ------------
   \   ^__^
    \  (oo)\_______
       (__)\       )\/\
           ||----w |
           ||     ||
```

Run a specific version of a tool:

```console theme={null}
$ uvx ruff@0.3.0 check
```

### Install tools globally

For tools you use frequently, install them to make them available system-wide:

```console theme={null}
$ uv tool install ruff
Resolved 1 package in 6ms
Installed 1 package in 2ms
 + ruff==0.5.0
Installed 1 executable: ruff

$ ruff --version
ruff 0.5.0
```

## Next steps

Now that you have uv set up, explore more capabilities:

<CardGroup cols={2}>
  <Card title="Working on Projects" icon="folder-open" href="/guides/projects">
    Learn about project structure, managing dependencies, and building distributions
  </Card>

  <Card title="Running Scripts" icon="file-code" href="/guides/scripts">
    Execute single-file scripts with inline dependency declarations
  </Card>

  <Card title="Python Installation" icon="snake" href="/guides/install-python">
    Deep dive into installing and managing Python versions
  </Card>

  <Card title="Using Tools" icon="wrench" href="/guides/tools">
    Master tool installation and management with uv and uvx
  </Card>
</CardGroup>

<Tip>
  **New to Python packaging?** Check out our [concepts guide](/concepts/projects) to understand how uv manages projects, dependencies, and environments.
</Tip>