# Run your first Python script with uv


[uv](https://pydevtools.com/handbook/reference/uv.md) can run [Python](https://pydevtools.com/handbook/explanation/what-is-python.md) scripts without any prior Python installation. This tutorial starts with a one-line script and builds up to using a third-party package through [inline script metadata](https://pydevtools.com/handbook/explanation/what-is-pep-723.md).

## Prerequisites

[Install uv](https://pydevtools.com/handbook/how-to/how-to-install-uv.md) on your system.

> [!TIP]
> Python does not need to be installed beforehand. uv downloads and manages Python interpreters automatically.

## Create and run a script

### Create a project directory

```bash
mkdir hello-uv
cd hello-uv
```
```powershell
mkdir hello-uv
cd hello-uv
```
### Write the script

Create a file called `hello.py` with the following content:

```python {filename="hello.py"}
print("Hello, World!")
```

### Run it

```console
$ uv run hello.py
Hello, World!
```

If you see `command not found: uv` instead, your shell cannot find the binary. Close and reopen your terminal so it picks up the install, or revisit the [uv install instructions](https://pydevtools.com/handbook/how-to/how-to-install-uv.md) to confirm it is on your `PATH`.

uv finds (or installs) a Python interpreter, then executes the script. No virtual environment setup, no activation step.

> [!NOTE]
> The first run on a clean machine is slower because uv downloads the Python interpreter. Subsequent runs reuse the cached interpreter and start almost instantly. Notice that you never had to create or activate a [virtual environment](https://pydevtools.com/handbook/explanation/what-is-a-virtual-environment.md); uv handled that for you.

## Add a third-party dependency

Most real scripts need packages beyond the standard library. uv supports [PEP 723](https://pydevtools.com/handbook/explanation/what-is-pep-723.md) inline script metadata, which lets a script declare its own dependencies.

Add the `requests` dependency to the script:

```console
$ uv add --script hello.py requests
Updated `hello.py`
```

Open `hello.py` and notice that uv prepended a `# /// script` block above your `print` line. That block is the PEP 723 metadata uv reads to know which packages to install before running the script. The exact field order and `requires-python` value depend on your uv version and the Python interpreter uv chose; what matters is the surrounding `# /// script` and `# ///` markers.

Now replace the script contents with:

```python {filename="hello.py"}
# /// script
# dependencies = ["requests"]
# requires-python = ">=3.10"
# ///

import requests

response = requests.get("https://api.github.com/zen")
print(response.text)
```

Run it again:

```console
$ uv run hello.py
Installed 5 packages in 95ms
Responsive is better than fast.
```

uv reads the `dependencies` list, installs `requests` (and its four transitive dependencies) into an isolated environment, then runs the script. The exact quote you see will vary; `https://api.github.com/zen` rotates through GitHub's design philosophy. Run the script a second time and notice that the `Installed 5 packages` line disappears: uv reuses the cached environment instead of resolving and downloading again.

If you see `error: failed to parse: ...` after editing the metadata block, double-check that every line between `# /// script` and `# ///` starts with `# ` and that both marker lines are present. PEP 723 is strict about the markers.

## Next steps

- [Create your first Python project](https://pydevtools.com/handbook/tutorial/create-your-first-python-project.md) moves from standalone scripts to a full project with pyproject.toml
- [Setting up testing with pytest and uv](https://pydevtools.com/handbook/tutorial/setting-up-testing-with-pytest-and-uv.md) adds a test suite to a uv project
- [What is PEP 723?](https://pydevtools.com/handbook/explanation/what-is-pep-723.md) explains inline script metadata in detail
- [uv reference](https://pydevtools.com/handbook/reference/uv.md) documents all uv commands