uvrs 0.6.1

Create and run uv scripts with POSIX standardized shebang line

uvrs

This program is meant to be used in a shebang line, like this:

#!/usr/bin/env uvrs

Unlike the shebang line recommended by uv's documentation, the above shebang does not rely on the non-standard -S option (see uv issue 11876).

Installation

This should be installed as a globally available tool (so the above shebang line works):

uv tool install -p 3.14 uvrs

That will install uvrs using Python 3.14 (for nicely colorized help text).

Primary Usage

The primary purpose of the uvrs command is to accept a filename to be run as a uv script.

The uvrs command is not designed to run a script on its own. If you need to run a script, use uv run for that.

The uvrs command can also be used to:

1. Create new uv scripts with a uvrs shebang line
2. Update existing uv scripts to use a uvrs shebang line

Creating new uv scripts

To initialize a new uv script with a uvrs shebang line use the init command:

uvrs init ~/bin/my-script --python 3.12

This will create the file ~/bin/my-script using uv init --script ~/bin/my-script --python 3.12 and then add an appropriate shebang line to the beginning of the script:

#!/usr/bin/env uvrs
# /// script
# requires-python = ">=3.12"
# dependencies = []
# ///


def main() -> None:
    print("Hello from my-script!")


if __name__ == "__main__":
    main()

Updating existing uv scripts

To update an existing uv script to use the uvrs shebang, use the fix command:

uvrs fix ~/bin/my-script

If the file does not yet have a shebang line, this shebang line will be added:

#!/usr/bin/env uvrs

If the file being fixed already has a shebang line which uses uv run, the shebang will be updated to use uvrs instead.

Managing dependencies

To update the dependencies within inline script metadata, use uvrs add and uvrs remove.

To add a new dependency:

uvrs add ~/bin/my-script 'rich'

This runs uv add --script ~/bin/my-script 'rich' followed by uv sync --script ~/bin/my-script, so the dependency is installed immediately.

To remove a new dependency:

uvrs remove ~/bin/my-script 'rich'

This runs uv remove --script ~/bin/my-script 'rich' and then uv sync --script ~/bin/my-script to keep the resolved environment up to date.

The goal

Eventually, I would like to see a similar tool integrated into uv.

Until that time, I plan to maintain this uvrs tool.