Usage of the New CLI
Once you have enabled the nix-command and flakes features, you can start using the new generation Nix command-line tools provided by New Nix Commands. In this section, we will focus on two commands: nix shell and nix run. Other important commands like nix build will be discussed in detail in nix develop & pkgs.mkShell
nix shell
The nix shell command allows you to enter an environment with the specified Nix package and opens an interactive shell within that environment:
# hello is not available
› hello
hello: command not found
# Enter an environment with the 'hello' package
› nix shell nixpkgs#hello
# hello is now available
› hello
Hello, world!# hello is not available
› hello
hello: command not found
# Enter an environment with the 'hello' package
› nix shell nixpkgs#hello
# hello is now available
› hello
Hello, world!nix run
On the other hand, nix run creates an environment with the specified Nix package and directly runs that package within the environment (without installing it into the system environment):
# hello is not available
› hello
hello: command not found
# Create an environment with the 'hello' package and run it
› nix run nixpkgs#hello
Hello, world!# hello is not available
› hello
hello: command not found
# Create an environment with the 'hello' package and run it
› nix run nixpkgs#hello
Hello, world!Since nix run directly executes the Nix package, the package specified as the argument must generate an executable program.
According to the nix run --help documentation, nix run executes the command <out>/bin/<name>, where <out> is the root directory of the derivation and <name> is selected in the following order:
- The
meta.mainProgramattribute of the derivation - The
pnameattribute of the derivation - The content of the
nameattribute of the derivation with the version number removed
For example, in the case of the 'hello' package we tested earlier, nix run actually executes the program $out/bin/hello.
Here are two more examples with detailed explanations of the relevant parameters:
# Explanation of the command:
# `nixpkgs#ponysay` means the 'ponysay' package in the 'nixpkgs' flake.
# `nixpkgs` is a flake registry id, and Nix will find the corresponding GitHub repository address
# from <https://github.com/NixOS/flake-registry/blob/master/flake-registry.json>.
# Therefore, this command creates a new environment, installs, and runs the 'ponysay' package provided by the 'nixpkgs' flake.
# Note: It has been mentioned earlier that a Nix package is one of the outputs of a flake.
echo "Hello Nix" | nix run "nixpkgs#ponysay"
# This command has the same effect as the previous one, but it uses the complete flake URI instead of the flake registry id.
echo "Hello Nix" | nix run "github:NixOS/nixpkgs/nixos-unstable#ponysay"# Explanation of the command:
# `nixpkgs#ponysay` means the 'ponysay' package in the 'nixpkgs' flake.
# `nixpkgs` is a flake registry id, and Nix will find the corresponding GitHub repository address
# from <https://github.com/NixOS/flake-registry/blob/master/flake-registry.json>.
# Therefore, this command creates a new environment, installs, and runs the 'ponysay' package provided by the 'nixpkgs' flake.
# Note: It has been mentioned earlier that a Nix package is one of the outputs of a flake.
echo "Hello Nix" | nix run "nixpkgs#ponysay"
# This command has the same effect as the previous one, but it uses the complete flake URI instead of the flake registry id.
echo "Hello Nix" | nix run "github:NixOS/nixpkgs/nixos-unstable#ponysay"Common Use Cases for nix run and nix shell
These commands are commonly used for running programs temporarily. For example, if I want to clone my configuration repository using Git on a new NixOS host without Git installed, I can use the following command:
nix run nixpkgs#git clone git@github.com:ryan4yin/nix-config.gitnix run nixpkgs#git clone git@github.com:ryan4yin/nix-config.gitAlternatively, I can use nix shell to enter an environment with Git and then run the git clone command:
nix shell nixpkgs#git
git clone git@github.com:ryan4yin/nix-config.gitnix shell nixpkgs#git
git clone git@github.com:ryan4yin/nix-config.git