pypa-hatch/docs/how-to/run/python-scripts.md

How to run Python scripts

---

The run command supports executing Python scripts with inline metadata, such that a dedicated environment is automatically created with the required dependencies and with the correct version of Python.

A script metadata block is a comment block that starts with # /// script and ends with # ///. Every line between those two lines must be a comment line that starts with # and contains a TOML document when the comment characters are removed.

The top-level fields are:

• dependencies: A list of strings that specifies the runtime dependencies of the script. Each entry must be a valid dependency specifier.
• requires-python: A string that specifies the Python version(s) with which the script is compatible. The value of this field must be a valid version specifier.

The following is an example of Python script with a valid metadata block:

# /// script
# requires-python = ">=3.11"
# dependencies = [
#   "httpx",
#   "rich",
# ]
# ///

import httpx
from rich.pretty import pprint

resp = httpx.get("https://peps.python.org/api/peps.json")
data = resp.json()
pprint([(k, v["title"]) for k, v in data.items()][:10])

Run it directly:

$ hatch run /path/to/script.py
Creating environment: SyB4bPbL
Checking dependencies
Syncing dependencies
[
│   ('1', 'PEP Purpose and Guidelines'),
│   ('2', 'Procedure for Adding New Modules'),
│   ('3', 'Guidelines for Handling Bug Reports'),
│   ('4', 'Deprecation of Standard Modules'),
│   ('5', 'Guidelines for Language Evolution'),
│   ('6', 'Bug Fix Releases'),
│   ('7', 'Style Guide for C Code'),
│   ('8', 'Style Guide for Python Code'),
│   ('9', 'Sample Plaintext PEP Template'),
│   ('10', 'Voting Guidelines')
]

!!! note "notes" - The informational text in this example is only temporarily shown in your terminal on the first run. - Although the environment name is based on the script's absolute path, the command line argument does not have to be.

Environment configuration

You may use the [tool.hatch] table directly to control the script's environment. For example, if you wanted to disable UV (which is enabled by default for scripts), you could add the following:

# /// script
# ...
# [tool.hatch]
# installer = "pip"
# ///