.\" -*- mode: troff; coding: utf-8 -*-
.TH "nix3-run" "1" ""
.PP
\fBWarning\fR: This program is \fBexperimental\fR and its interface is subject to change.
.SH Name
\fCnix run\fR - run a Nix application
.SH Synopsis
\fCnix run\fR [\fIoption\fR\[u2026]] \fIinstallable\fR \fIargs\fR\[u2026]
.SH Examples
.IP "\(bu" 2
Run the default app from the \fCblender-bin\fR flake:
.LP
.EX
# nix run blender-bin
.EE
.IP "\(bu" 2
Run a non-default app from the \fCblender-bin\fR flake:
.LP
.EX
# nix run blender-bin#blender_2_83
.EE
.IP
Tip: you can find apps provided by this flake by running \fCnix flake
show blender-bin\fR.
.IP "\(bu" 2
Run \fCvim\fR from the \fCnixpkgs\fR flake:
.LP
.EX
# nix run nixpkgs#vim
.EE
.IP
Note that \fCvim\fR (as of the time of writing of this page) is not an
app but a package. Thus, Nix runs the eponymous file from the \fCvim\fR
package.
.IP "\(bu" 2
Run \fCvim\fR with arguments:
.LP
.EX
# nix run nixpkgs#vim -- --help
.EE
.SH Description
\fCnix run\fR builds and runs \fIinstallable\fR, which must evaluate to an
\fIapp\fR or a regular Nix derivation.
.PP
If \fIinstallable\fR evaluates to an \fIapp\fR (see below), it executes the
program specified by the app definition.
.PP
If \fIinstallable\fR evaluates to a derivation, it will try to execute the
program \fC<out>/bin/<name>\fR, where \fIout\fR is the primary output store
path of the derivation, and \fIname\fR is the first of the following that
exists:
.IP "\(bu" 2
The \fCmeta.mainProgram\fR attribute of the derivation.
.if n \
.sp -1
.if t \
.sp -0.25v
.IP "\(bu" 2
The \fCpname\fR attribute of the derivation.
.if n \
.sp -1
.if t \
.sp -0.25v
.IP "\(bu" 2
The name part of the value of the \fCname\fR attribute of the derivation.
.LP
For instance, if \fCname\fR is set to \fChello-1.10\fR, \fCnix run\fR will run
\fC$out/bin/hello\fR.
.SH Flake output attributes
If no flake output attribute is given, \fCnix run\fR tries the following
flake output attributes:
.IP "\(bu" 2
\fCapps.<system>.default\fR
.IP "\(bu" 2
\fCpackages.<system>.default\fR
.LP
If an attribute \fIname\fR is given, \fCnix run\fR tries the following flake
output attributes:
.IP "\(bu" 2
\fCapps.<system>.<name>\fR
.IP "\(bu" 2
\fCpackages.<system>.<name>\fR
.IP "\(bu" 2
\fClegacyPackages.<system>.<name>\fR
.SH Apps
An app is specified by a flake output attribute named
\fCapps.<system>.<name>\fR. It looks like this:
.LP
.EX
apps.x86_64-linux.blender_2_79 = {
  type = \(dqapp\(dq;
  program = \(dq${self.packages.x86_64-linux.blender_2_79}/bin/blender\(dq;
};
.EE
.PP
The only supported attributes are:
.IP "\(bu" 2
\fCtype\fR (required): Must be set to \fCapp\fR.
.IP "\(bu" 2
\fCprogram\fR (required): The full path of the executable to run. It
must reside in the Nix store.
.SH Options
\fBCommon evaluation options:\fR
.IP "\(bu" 2
\fC--arg\fR \fIname\fR \fIexpr\fR
.br
Pass the value \fIexpr\fR as the argument \fIname\fR to Nix functions.
.IP "\(bu" 2
\fC--argstr\fR \fIname\fR \fIstring\fR
.br
Pass the string \fIstring\fR as the argument \fIname\fR to Nix functions.
.IP "\(bu" 2
\fC--eval-store\fR \fIstore-url\fR
.br
The Nix store to use for evaluations.
.IP "\(bu" 2
\fC--impure\fR
.br
Allow access to mutable paths and repositories.
.IP "\(bu" 2
\fC--include\fR / \fC-I\fR \fIpath\fR
.br
Add \fIpath\fR to the list of locations used to look up \fC<...>\fR file names.
.IP "\(bu" 2
\fC--override-flake\fR \fIoriginal-ref\fR \fIresolved-ref\fR
.br
Override the flake registries, redirecting \fIoriginal-ref\fR to \fIresolved-ref\fR.
.LP
\fBCommon flake-related options:\fR
.IP "\(bu" 2
\fC--commit-lock-file\fR
.br
Commit changes to the flake\[u2019]s lock file.
.IP "\(bu" 2
\fC--inputs-from\fR \fIflake-url\fR
.br
Use the inputs of the specified flake as registry entries.
.IP "\(bu" 2
\fC--no-registries\fR
.br
Don\[u2019]t allow lookups in the flake registries. This option is deprecated; use \fC--no-use-registries\fR.
.IP "\(bu" 2
\fC--no-update-lock-file\fR
.br
Do not allow any updates to the flake\[u2019]s lock file.
.IP "\(bu" 2
\fC--no-write-lock-file\fR
.br
Do not write the flake\[u2019]s newly generated lock file.
.IP "\(bu" 2
\fC--override-input\fR \fIinput-path\fR \fIflake-url\fR
.br
Override a specific flake input (e.g. \fCdwarffs/nixpkgs\fR). This implies \fC--no-write-lock-file\fR.
.IP "\(bu" 2
\fC--recreate-lock-file\fR
.br
Recreate the flake\[u2019]s lock file from scratch.
.IP "\(bu" 2
\fC--update-input\fR \fIinput-path\fR
.br
Update a specific flake input (ignoring its previous entry in the lock file).
.LP
\fBOptions that change the interpretation of installables:\fR
.IP "\(bu" 2
\fC--derivation\fR
.br
Operate on the store derivation rather than its outputs.
.IP "\(bu" 2
\fC--expr\fR \fIexpr\fR
.br
Interpret installables as attribute paths relative to the Nix expression \fIexpr\fR.
.IP "\(bu" 2
\fC--file\fR / \fC-f\fR \fIfile\fR
.br
Interpret installables as attribute paths relative to the Nix expression stored in \fIfile\fR. If \fIfile\fR is the character -, then a Nix expression will be read from standard input.