Single-file scripts that download their dependencies

Nix

The Nix package manager can act as a #! interpreter and start another program with a list of dependencies available to it.

#! /usr/bin/env nix-shell
#! nix-shell -i python3 -p python310 python310Packages.ansicolors

from colors import bold

print(bold("Hello, world!".rjust(20, "-")))

Scriptisto

Scriptisto is a “language-agnostic ‘shebang interpreter’ that enables you to write scripts in compiled languages.”

#! /usr/bin/env scriptisto

# scriptisto-begin
# script_src: test.py
# build_once_cmd: python3 -m venv . && . ./bin/activate && pip install ansicolors
# build_cmd: . ./bin/activate && chmod +x ./run.sh
# target_bin: ./run.sh
# files:
#   - path: run.sh
#     content: |
#       #! /bin/sh
#       export DIR=$(dirname "$0")
#       . "$DIR"/bin/activate
#       python3 "$DIR"/test.py "$@"
# scriptisto-end

from colors import bold

print(bold("Hello, world!".rjust(20, "-")))

Bun

Bun resolves NPM dependencies in scripts.

#! /usr/bin/env bun

import leftPad from "left-pad";

console.log(leftPad("Hello, world!", 20, "-"));

Deno

Deno downloads dependencies like a browser. Deno 1.28 and later can also import from NPM packages. Current versions of Deno require you to pass a run argument to deno. One way to accomplish this from a script is with a form of exec magic. Here the magic is modified from a comment by Rafał Pocztarski.

#! /bin/sh
":" //#; exec /usr/bin/env deno run "$0" "$@"

import leftPad from "npm:left-pad";

console.log(leftPad("Hello, world!", 20, "-"));

You can replace the magic with env -S on systems that support it.

#! /usr/bin/env -S deno run

import leftPad from "npm:left-pad";

console.log(leftPad("Hello, world!", 20, "-"));

fades

fades runs Python scripts with dependencies. It offers four ways to specify dependencies:

• In comments, normally on imports;
• With one or more command-line option -d or --dependency;
• With the command-line option -r or --requirements and a requirements.txt file;
• In the script docstring.

Here is the comments method:

#! /usr/bin/env fades

from colors import bold  # fades ansicolors>=1,<2

print(bold("Hello, world!".rjust(20, "-")))

The option -d with env -S:

#! /usr/bin/env -S fades -d ansicolors>=1,<2

from colors import bold

print(bold("Hello, world!".rjust(20, "-")))

A docstring:

#! /usr/bin/env fades
"""
fades:
    ansicolors>=1,<2
"""

from colors import bold

print(bold("Hello, world!".rjust(20, "-")))

Hatch

Hatch is a Python project-mamanagement tool. It can run tasks and scripts for projects with the commamd hatch run. Version 1.10.0 extended this command to support inline script metadata derived from PEP 723.

The following example is identical to pipx and uv, which implements the same standard. You will need env -S to make the script run as a command.

#! /usr/bin/env -S hatch run
# /// script
# dependencies = ["ansicolors>=1,<2"]
# requires-python = ">=3.8"
# ///

from colors import bold

print(bold("Hello, world!".rjust(20, "-")))

If your system does not support env -S, you can instead use exec magic:

#! /bin/sh
"exec" "/usr/bin/env" "hatch" "run" "$0" "$@"

pip-run

One feature of pip-run is running Python scripts with dependencies. The script can declare its dependencies in several ways:

• In the env -S shebang line (in the example)
• Using the special variable __requires__
• In a top commment, which can be either PEP 722-style or inline script metadata like Hatch and pipx.

An example of env -S:

#! /usr/bin/env -S pip-run ansicolors>=1,<2

from colors import bold

print(bold("Hello, world!".rjust(20, "-")))

A PEP 722 top comment:

#! /usr/bin/env pip-run
# Requirements:
#     ansicolors>=1,<2

from colors import bold

print(bold("Hello, world!".rjust(20, "-")))

pip-wtenv

pip-wtenv is my counterpart to pip.wtf. See the next item. pip-wtenv differs from pip.wtf in that it uses venvs, supports Windows, and has a free license. It requires newer Python.

#! /usr/bin/env python3

def pip_wtenv(*args: str, name: str = "", venv_parent_dir: str = "") -> None:
    """
    Download and install dependencies in a virtual environment.
    See https://github.com/dbohdan/pip-wtenv.

    Warning: this function will restart Python
    if Python is not running in a venv.

    pip-wtenv requires Python >= 3.6 on POSIX systems
    and Python >= 3.8 on Windows.
    """

    from os import execl
    from pathlib import Path
    from subprocess import run
    from sys import argv, base_prefix, platform, prefix
    from venv import create as create_venv

    me = Path(__file__)
    venv_dir = (
        Path(venv_parent_dir).expanduser() if venv_parent_dir else me.parent
    ) / f".venv.{name or me.name}"

    if not venv_dir.exists():
        create_venv(venv_dir, with_pip=True)

    ready_marker = venv_dir / "ready"
    venv_python = venv_dir / (
        "Scripts/python.exe" if platform == "win32" else "bin/python"
    )

    if not ready_marker.exists():
        run(
            [venv_python, "-m", "pip", "install", "--quiet", "--upgrade", "pip"],
            check=True,
        )
        run([venv_python, "-m", "pip", "install", *args], check=True)
        ready_marker.touch()

    # If we are not running in a venv, restart with `venv_python`.
    if prefix == base_prefix:
        execl(venv_python, venv_python, *argv)


pip_wtenv("ansicolors")

from colors import bold

print(bold("Hello, world!".rjust(20, "-")))

pip.wtf

pip.wtf is a self-contained code snippet born out of its author’s frustration with Python packaging. It is a single function that you can copy into your script and call to install the script’s dependencies.

#! /usr/bin/env python3

# https://pip.wtf
def pip_wtf(command):
    import os, os.path, sys
    t = os.path.join(os.path.dirname(os.path.abspath(__file__)), ".pip_wtf." + os.path.basename(__file__))
    sys.path = [p for p in sys.path if "-packages" not in p] + [t]
    os.environ["PATH"] = t + os.path.sep + "bin" + os.pathsep + os.environ["PATH"]
    os.environ["PYTHONPATH"] = os.pathsep.join(sys.path)
    if os.path.exists(t): return
    os.system(" ".join([sys.executable, "-m", "pip", "install", "-t", t, command]))


pip_wtf("ansicolors")

from colors import bold

print(bold("Hello, world!".rjust(20, "-")))

pipx

pipx version 1.3.0 and higher supports running scripts in addition to packages. Version 1.4.2 brought it in sync with the latest revision of PEP 723.

The following example is identical to Hatch and uv, which implements the same standard. You will need env -S to make the script run as a command.

#! /usr/bin/env -S pipx run
# /// script
# dependencies = ["ansicolors>=1,<2"]
# requires-python = ">=3.8"
# ///

from colors import bold

print(bold("Hello, world!".rjust(20, "-")))

If your system does not support env -S, you can instead use exec magic:

#! /bin/sh
"exec" "/usr/bin/env" "pipx" "run" "$0" "$@"

uv

The package and project manager uv can run scripts with dependencies. This was implemented in version 0.3.0. The dependencies can be specified in the shebang line using env -S or exec magic or as standard inline script metadata.

Use of the shebang line looks like this:

#! /usr/bin/env -S uv run --with ansicolors>=1,<2

from colors import bold

print(bold("Hello, world!".rjust(20, "-")))

The following example is identical to Hatch and pipx, which implements the same standard. You will need env -S to make the script run as a command.

#! /usr/bin/env -S uv run
# /// script
# dependencies = ["ansicolors>=1,<2"]
# requires-python = ">=3.8"
# ///

from colors import bold

print(bold("Hello, world!".rjust(20, "-")))

If your system does not support env -S, you can instead use exec magic:

#! /bin/sh
"exec" "/usr/bin/env" "uv" "run" "$0" "$@"

Comparison

#! /usr/bin/env python3

from __future__ import annotations

import shlex
import subprocess
from pathlib import Path

CONTAINER_IMAGE = "python:3.12.4"
CONTAINER_RUNTIME = "podman"
DIR_IN_CONTAINER = Path("/mnt")
RUNS = 10

TARGETS_WITH_DEPS = [
    ("fades.py", ["fades==9.0.2"]),
    ("hatch.py", ["hatch==1.12.0"]),
    ("pip-run-destroy.py", ["pip-run==13.0.0"]),
    ("pip-run-persist.py", ["pip-run==13.0.0"]),
    ("pip-wtenv.py", []),
    ("pip.wtf.py", []),
    ("pipx.py", ["pipx==1.7.1"]),
    ("uv.py", ["uv==0.3.3"]),
]


def benchmark_script_text(target: str, deps: list[str]) -> str:
    target_path = DIR_IN_CONTAINER / target

    pip_install_line = (
        f"python3 -m pip --quiet install {shlex.join(deps)}" if deps else ""
    )

    return f"""#! /bin/sh
        set -eu

        apt-get -qq update
        apt-get -qq -y install time
        {pip_install_line}

        for _ in $(seq {RUNS}); do
            time \\
                --append \\
                --format '%e' \\
                --output {shlex.quote(str(target_path.with_suffix(".times")))} \\
                {shlex.quote(str(target_path))}

        done
        """


def main() -> None:
    benchmark_script = Path("bench.sh")
    benchmark_script.touch(0o755)

    for target, deps in TARGETS_WITH_DEPS:
        print(f"=== {target}")

        benchmark_script.write_text(benchmark_script_text(target, deps))

        subprocess.run(
            [
                CONTAINER_RUNTIME,
                "run",
                "--rm",
                "--interactive",
                "--tty",
                "--mount",
                f"type=bind,source={Path.cwd()},target={DIR_IN_CONTAINER}",
                CONTAINER_IMAGE,
                DIR_IN_CONTAINER / benchmark_script,
            ],
            check=False,
        )


if __name__ == "__main__":
    main()

Ammonite

The scripting environment in Ammonite lets you import Ivy dependencies.

#! /usr/bin/env amm

import $ivy.`org.apache.commons:commons-lang3:3.12.0`,
  org.apache.commons.lang3.StringUtils

println(StringUtils.leftPad("Hello, world!", 20, "-"))

Scala CLI

Scala CLI is a newer tool that understands a subset of Ammonite’s imports.

#! /usr/bin/env scala-cli

import $ivy.`org.apache.commons:commons-lang3:3.12.0`,
  org.apache.commons.lang3.StringUtils

println(StringUtils.leftPad("Hello, world!", 20, "-"))