uv Init Types

UV has the ability to create a few project structures

Lib & Package

• uv init --lib
• uv init --package

I'm not clear on the difference between the two but they produce a file structure like so.

test-lib
├── README.md
├── pyproject.toml
└── src
    └── test_lib
        ├── __init__.py
        └── py.typed

test-pkg
├── README.md
├── pyproject.toml
└── src
    └── test_pkg
        └── __init__.py

The only difference appears to be the presence of a py.typed file.

App

Running uv init --app appears to create the same structure as just a plain uv init run.

Script

This one is pretty interesting, if you run uv init --script myscript.py, you will get a file with a special header.

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


def main() -> None:
    print("Hello from myscript.py!")


if __name__ == "__main__":
    main()

This is PEP 723 Inline script metadata.

Notice the dependencies array? Yes, you can use UV to run scripts outside of a virtual environment and still declare third party dependencies.

Declare them like so.

uv add --script myscript.py httpx

Now you'll notice the dependency was added.

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


def main() -> None:
    print("Hello from myscript.py!")


if __name__ == "__main__":
    main()

Run like so.

uv run -s myscript.py