Using uv as your shebang line

Original Article ↗ Hacker News Discussion ↗

Using the `uv` tool as a shebang line for Python scripts lets a single file declare its own dependencies, automatically create an isolated environment, and “just run” without manual virtualenv or pip setup. Commenters weigh this convenience and speed—uv also manages Python versions and can replace tools like pip, pyenv, and Poetry—against concerns about portability, complexity, and the proliferation of yet another dependency manager. The thread also explores related tricks such as `env -S` for multi-argument shebangs, inline metadata standards (PEP 723), and parallels in other ecosystems like Nix, Deno, Bun, and Ruby’s Bundler.

What uv is and what it replaces

  • Described as a very fast Python package & project manager that combines roles of pip, venv, pyenv, pipx/tool installers, and Python version management.
  • Several commenters say they now use it as a drop‑in replacement for pip or Poetry, or as their main way to manage Python runtimes and environments.
  • Strong praise that it “makes Python actually usable” and removes much of the usual environment/packaging friction.

Shebang + inline dependencies (PEP 723)

  • New PEP lets scripts declare dependencies in a special comment block at the top of the file.
  • uv run --script can read those comments, create an isolated environment, install dependencies, and run the script.
  • Using #!/usr/bin/env -S uv run --script as the shebang makes such scripts “just run” (once uv itself is installed).
  • Inline metadata is optional; for larger projects, pyproject.toml is still recommended.

Benefits and use cases

  • Great for ad‑hoc or one‑off scripts that need third‑party packages without manual venv setup or polluting global installs.
  • Helpful when sharing scripts with non‑developers or across machines: dependencies are self‑described and reproducible.
  • Some use uv as a generic installer for complex CLI tools, bundling Python and deps into isolated tool environments.

Concerns and skepticism

  • Worries it’s “yet another all‑in‑one tool” like npm/yarn/Poetry that may age poorly vs. small focused tools.
  • Some dislike mixing code and dependency lists in the same file conceptually, preferring separate config.
  • Question raised whether one‑off personal scripts really need isolated envs; counter‑argument is long‑term hygiene and avoiding version conflicts (e.g., NumPy 1 vs 2).
  • uv still requires initial installation; without it, scripts won’t run.

Shebang mechanics and portability

  • env -S is highlighted as a neat trick to pass multiple arguments from the shebang; works well on Linux, more nuanced on macOS and not universal on all Unix variants.
  • Discussion of limitations: max shebang length, inconsistent support, Android paths.
  • Various multi‑line / polyglot shebang hacks are shared (Tcl, Guile, Prolog, C) as related techniques.

Comparisons and ecosystem parallels

  • uv vs Poetry/conda/pip: uv is praised for speed, lockfile behavior, Python version management, and fewer “gotchas.”
  • Similar patterns noted in other ecosystems: nix‑shell, Deno, Bun, Ruby bundler, swift‑sh, and task runners using embedded scripts.