nix-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

nix run [options] <flake-url>[#<attr>] [--] [args...]

--offline
    Do not attempt to connect to the Nix store or the network during evaluation and building.

--refresh
    Force re-fetching of flake inputs, ignoring cached versions.

--install
    After running, install the specified executable into the user's default profile (e.g., ~/.nix-profile).

--profile path
    Add the specified executable to the given Nix profile path instead of the default. Similar to --install.

--impure
    Allow the executed command to access environment variables and paths outside the clean Nix environment, potentially compromising reproducibility.

--extra-experimental-features features
    Enable specified experimental Nix features (e.g., flakes nix-command).

--
    Used to separate nix run options from arguments that should be passed directly to the program being executed.

The nix run command is a powerful subcommand of the Nix package manager, designed to execute applications or scripts defined in a Nix expression without requiring a permanent installation. It creates a temporary, isolated environment where the specified package and all its dependencies are made available, then runs the desired command within that sandboxed context.

This functionality is invaluable for a variety of use cases: trying out new tools or applications without cluttering your system, running one-off scripts with specific dependencies, or setting up reproducible development environments without polluting your user profile or global PATH. By leveraging Nix's content-addressable store, nix run efficiently fetches or builds necessary components, ensuring reproducibility and consistency across different machines.

By default, nix run operates in a highly isolated environment. This means the executed program will not have access to your system's default environment variables (like PATH) or user files unless specifically exposed or the --impure flag is used. First-time execution might be slower due to downloading or building dependencies. It requires Nix 2.4 or newer for flake support and the 'nix-command' experimental feature to be enabled.

nix run is deeply integrated with Nix Flakes. The <flake-url>[#<attr>] syntax allows users to reference applications or packages defined within a flake (e.g., nixpkgs#hello, github:NixOS/nixpkgs/nixos-23.11#cowsay, or .#my-app for local flakes), providing a consistent and reproducible way to execute specific entries from a project.

One of nix run's core strengths is its ephemeral nature. Unless explicitly told to install the program (via --install or --profile), it cleans up the temporary environment after execution, leaving no lasting traces or modifications to your system's configuration. This makes it perfect for testing, quick one-off tasks, or ensuring a clean development setup.

The nix run command emerged as part of the 'Nix command' re-architecture, which aimed to consolidate and streamline Nix's user-facing interface. Prior to its introduction (around Nix 2.4), similar functionality was often achieved by composing commands like nix-shell -p <pkg> --run <cmd>. nix run significantly simplified the 'run a single application' use case, particularly with the advent of Nix Flakes, providing a more intuitive and declarative way to specify and execute programs from Nix expressions directly.

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