--- name: "nix3-run" section: "1" platform: "linux" package: "nix-bin" version: "2.26.3+dfsg-1" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/nix3-run" --- # nix3-run(1) run a Nix application **Warning** \ This program is **experimental** ⟨@docroot@/development/experimental-features.md#xp-feature-nix-command⟩ and its interface is subject to change. ## Name `nix run` - run a Nix application ## Synopsis `nix run` \[*option*…\] *installable* *args*… ## Examples - • Run the default app from the `blender-bin` flake: ``` # nix run blender-bin ``` - • Run a non-default app from the `blender-bin` flake: ``` # nix run blender-bin#blender_2_83 ``` - Tip: you can find apps provided by this flake by running `nix flake` `show blender-bin`. - • Run `vim` from the `nixpkgs` flake: ``` # nix run nixpkgs#vim ``` - Note that `vim` (as of the time of writing of this page) is not an app but a package. Thus, Nix runs the eponymous file from the `vim` package. - • Run `vim` with arguments: ``` # nix run nixpkgs#vim -- --help ``` ## Description `nix run` builds and runs *installable* ⟨./nix.md#installables⟩\\c , which must evaluate to an *app* or a regular Nix derivation. If *installable* evaluates to an *app* (see below), it executes the program specified by the app definition. If *installable* evaluates to a derivation, it will try to execute the program `/bin/`, where *out* is the primary output store path of the derivation, and *name* is the first of the following that exists: - • The `meta.mainProgram` attribute of the derivation. - • The `pname` attribute of the derivation. - • The name part of the value of the `name` attribute of the derivation. For instance, if `name` is set to `hello-1.10`, `nix run` will run `$out/bin/hello`. ## Flake output attributes If no flake output attribute is given, `nix run` tries the following flake output attributes: - • `apps..default` - • `packages..default` If an attribute *name* is given, `nix run` tries the following flake output attributes: - • `apps..` - • `packages..` - • `legacyPackages..` ## Apps An app is specified by a flake output attribute named `apps..`. It looks like this: ``` apps.x86_64-linux.blender_2_79 = { type = "app"; program = "${self.packages.x86_64-linux.blender_2_79}/bin/blender"; meta.description = "Run Blender, a free and open-source 3D creation suite."; }; ``` The only supported attributes are: - • `type` (required): Must be set to `app`. - • `program` (required): The full path of the executable to run. It must reside in the Nix store. - • `meta.description` (optional): A description of the app. ## Options ### Common evaluation options - • `--arg` ⟨#opt-arg⟩ *name* *expr* - Pass the value *expr* as the argument *name* to Nix functions. - • `--arg-from-file` ⟨#opt-arg-from-file⟩ *name* *path* - Pass the contents of file *path* as the argument *name* to Nix functions. - • `--arg-from-stdin` ⟨#opt-arg-from-stdin⟩ *name* - Pass the contents of stdin as the argument *name* to Nix functions. - • `--argstr` ⟨#opt-argstr⟩ *name* *string* - Pass the string *string* as the argument *name* to Nix functions. - • `--debugger` ⟨#opt-debugger⟩ - Start an interactive environment if evaluation fails. - • `--eval-store` ⟨#opt-eval-store⟩ *store-url* - The URL of the Nix store ⟨@docroot@/store/types/index.md#store-url-format⟩ to use for evaluation, i.e. to store derivations (`.drv` files) and inputs referenced by them. - • `--impure` ⟨#opt-impure⟩ - Allow access to mutable paths and repositories. - • `--include` ⟨#opt-include⟩ / `-I` *path* - Add *path* to search path entries used to resolve lookup paths ⟨@docroot@/language/constructs/lookup-path.md⟩ - This option may be given multiple times. - Paths added through `-I` take precedence over the `nix-path` configuration setting ⟨@docroot@/command-ref/conf-file.md#conf-nix-path⟩ and the `NIX_PATH` environment variable ⟨@docroot@/command-ref/env-common.md#env-NIX\_PATH⟩\\c . - • `--override-flake` ⟨#opt-override-flake⟩ *original-ref* *resolved-ref* - Override the flake registries, redirecting *original-ref* to *resolved-ref*. ### Common flake-related options - • `--commit-lock-file` ⟨#opt-commit-lock-file⟩ - Commit changes to the flake’s lock file. - • `--inputs-from` ⟨#opt-inputs-from⟩ *flake-url* - Use the inputs of the specified flake as registry entries. - • `--no-registries` ⟨#opt-no-registries⟩ - Don’t allow lookups in the flake registries. - **DEPRECATED** - Use `--no-use-registries` ⟨@docroot@/command-ref/conf-file.md#conf-use-registries⟩ instead. - • `--no-update-lock-file` ⟨#opt-no-update-lock-file⟩ - Do not allow any updates to the flake’s lock file. - • `--no-write-lock-file` ⟨#opt-no-write-lock-file⟩ - Do not write the flake’s newly generated lock file. - • `--output-lock-file` ⟨#opt-output-lock-file⟩ *flake-lock-path* - Write the given lock file instead of `flake.lock` within the top-level flake. - • `--override-input` ⟨#opt-override-input⟩ *input-path* *flake-url* - Override a specific flake input (e.g. `dwarffs/nixpkgs`). This implies `--no-write-lock-file`. - • `--recreate-lock-file` ⟨#opt-recreate-lock-file⟩ - Recreate the flake’s lock file from scratch. - **DEPRECATED** - Use `nix flake update` ⟨@docroot@/command-ref/new-cli/nix3-flake-update.md⟩ instead. - • `--reference-lock-file` ⟨#opt-reference-lock-file⟩ *flake-lock-path* - Read the given lock file instead of `flake.lock` within the top-level flake. - • `--update-input` ⟨#opt-update-input⟩ *input-path* - Update a specific flake input (ignoring its previous entry in the lock file). - **DEPRECATED** - Use `nix flake update` ⟨@docroot@/command-ref/new-cli/nix3-flake-update.md⟩ instead. ### Logging-related options - • `--debug` ⟨#opt-debug⟩ - Set the logging verbosity level to ‘debug’. - • `--log-format` ⟨#opt-log-format⟩ *format* - Set the format of log output; one of `raw`, `internal-json`, `bar` or `bar-with-logs`. - • `--print-build-logs` ⟨#opt-print-build-logs⟩ / `-L` - Print full build logs on standard error. - • `--quiet` ⟨#opt-quiet⟩ - Decrease the logging verbosity level. - • `--verbose` ⟨#opt-verbose⟩ / `-v` - Increase the logging verbosity level. ### Miscellaneous global options - • `--help` ⟨#opt-help⟩ - Show usage information. - • `--offline` ⟨#opt-offline⟩ - Disable substituters and consider all previously downloaded files up-to-date. - • `--option` ⟨#opt-option⟩ *name* *value* - Set the Nix configuration setting *name* to *value* (overriding `nix.conf`). - • `--refresh` ⟨#opt-refresh⟩ - Consider all previously downloaded files out-of-date. - • `--repair` ⟨#opt-repair⟩ - During evaluation, rewrite missing or corrupted files in the Nix store. During building, rebuild missing or corrupted store paths. - • `--version` ⟨#opt-version⟩ - Show version information. ### Options that change environment variables - • `--ignore-env` ⟨#opt-ignore-env⟩ / `-i` - Clear the entire environment, except for those specified with `--keep-env-var`. - • `--keep-env-var` ⟨#opt-keep-env-var⟩ / `-k` *name* - Keep the environment variable *name*, when using `--ignore-env`. - • `--set-env-var` ⟨#opt-set-env-var⟩ / `-s` *name* *value* - Sets an environment variable *name* with *value*. - • `--unset-env-var` ⟨#opt-unset-env-var⟩ / `-u` *name* - Unset the environment variable *name*. ### Options that change the interpretation of **installables** - • `--expr` ⟨#opt-expr⟩ *expr* - Interpret *installables* ⟨@docroot@/command-ref/new-cli/nix.md#installables⟩ as attribute paths relative to the Nix expression *expr*. - • `--file` ⟨#opt-file⟩ / `-f` *file* - Interpret *installables* ⟨@docroot@/command-ref/new-cli/nix.md#installables⟩ as attribute paths relative to the Nix expression stored in *file*. If *file* is the character -, then a Nix expression will be read from standard input. Implies `--impure`. **Note** See `man nix.conf` ⟨@docroot@/command-ref/conf-file.md#command-line-flags⟩ for overriding configuration settings with command line flags.