nix3-run

Run the default application in the flake in the current directory

$ nix run

$ nix run nixpkgs#[pkg]

$ nix run nixpkgs#[vim] -- [path/to/file]

$ nix run [remote_name]:[owner]/[repo]

$ nix run [remote_name]:[owner]/[repo]/[reference]

$ nix run "[remote_name]:[owner]/[repo]?dir=[dir_name]#[app]"

$ nix run github:[owner]/[repo]/pull/[number]/head

nix3-run [options] flake-url [-- program-args...]
nix3-run [options] package-name [-- program-args...]

flake-url
    The URL or path to a Nix flake containing the program to run (e.g., nixpkgs#hello, gitlab:my-org/my-project, or . for the current directory's flake).

package-name
    A package name from nixpkgs (e.g., nixpkgs#cowsay) or a specific attribute path within a flake.

--
    A special separator. All arguments following -- are passed directly to the program being executed by nix3-run.

program-args...
    Arguments to be passed to the program launched by nix3-run.

--help
    Display help information for the command.

--json
    Produce command output in JSON format, useful for scripting.

--refresh
    Force a refresh of flake inputs and any associated data, ensuring the latest versions are used.

--impure
    Allow the command to access impure system paths, potentially breaking reproducibility.

--offline
    Do not attempt to access the network during execution.

The nix3-run command is a shim or legacy alias for the modern nix run command within the Nix package manager. Its primary purpose is to fetch and execute a program or package defined in a Nix flake or from nixpkgs directly, without needing to explicitly build or install it into your user environment. This makes it ideal for ad-hoc tool usage, quickly testing applications, or running executables from a specific version of a package.

When invoked, nix3-run (or nix run) will first ensure that the specified package or executable is built and present in the Nix store. If it's not available locally, Nix will download or build it along with all its dependencies in a reproducible manner. Once ready, the program is executed in a clean, isolated environment, inheriting only what's necessary for its operation. This command leverages Nix's content-addressable store and strict dependency management to guarantee that you're running precisely the specified version of a program, free from environmental pollution.

The nix3-run command is largely a legacy alias. Users are encouraged to use the canonical nix run command for all modern Nix workflows. This command (and nix run) requires Nix 2.4 or newer, typically with the 'flakes' experimental feature enabled. While convenient, running commands this way can incur a one-time build or download cost for dependencies if they are not already in your Nix store, potentially consuming network bandwidth and disk space.

Run a program from nixpkgs:
nix3-run nixpkgs#cowsay
nix3-run nixpkgs#cowsay -- 'Hello Nix!'

Run an executable from the current directory's flake:
Assume your flake.nix defines an app or package named my-app:
nix3-run .#my-app

Run a specific version of a program from a remote flake:
nix3-run 'github:NixOS/nixpkgs/nixos-23.11#hello'

The nix run command was introduced as a part of the new, experimental command-line interface (CLI) for Nix, alongside the 'flakes' feature. This new CLI aimed to simplify common Nix operations and make them more intuitive. The nix3-run alias (and similar nix3-* commands) emerged during the transition period from the older nix-* commands to the unified nix CLI. It served as a compatibility layer or a bridge, allowing scripts and users accustomed to older naming conventions to gradually adopt the new syntax while still benefiting from the new features. Over time, as the new CLI matured, the need for these aliases diminished, with nix run becoming the standard way to execute packages directly.

nix(1), nix-build(1), nix build(1), nix-shell(1), nix shell(1), nix-store(1)