Using uv as your shebang line

Original Article ↗ Hacker News Discussion ↗

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.