View source for Nix-shell shebang

You can use <code>nix-shell</code> as a script interpreter to

* run scripts in arbitrary languages
* provide dependencies with Nix

To do this, start the script with multiple shebang (<code>#!</code>) lines.<br>
The first shebang line is always <code>#! /usr/bin/env nix-shell</code>.<br>
The second shebang line declares the script language and the script dependencies.

As of Nix 2.19.0 you can also use the new CLI <code>nix shell</code> and flakes to define shebangs. See [https://nixos.org/manual/nix/stable/command-ref/new-cli/nix.html?highlight=shebang#shebang-interpreter docs].

== Examples ==

=== Bash ===

To run bash scripts, set the interpreter with <code>-i bash</code>

<syntaxHighlight lang="bash">
#! /usr/bin/env nix-shell
#! nix-shell -i bash -p bash

echo hello world
</syntaxHighlight>

You can use <code>nix-shell -p ...</code> to add dependencies:

<syntaxHighlight lang="bash">
#! /usr/bin/env nix-shell
#! nix-shell -i bash -p imagemagick cowsay

# scale image by 50%
convert "$1" -scale 50% "$1.s50.jpg" &&
cowsay "done $1.q50.jpg"
</syntaxHighlight>

=== Python ===

<syntaxHighlight lang="python">
#! /usr/bin/env nix-shell
#! nix-shell -i python3 -p python3

print("hello world")
</syntaxHighlight>

<syntaxHighlight lang="python">
#! /usr/bin/env nix-shell
#! nix-shell -i python3 -p python3Packages.pillow python3Packages.ansicolor

# scale image by 50%
import sys, PIL.Image, ansicolor
path = sys.argv[1]
image = PIL.Image.open(path)
factor = 0.5
image = image.resize((round(image.width * factor), round(image.height * factor)))
path = path + ".s50.jpg"
image.save(path)
print(ansicolor.green(f"done {path}"))
</syntaxHighlight>

=== Rust ===

==== No dependencies ====

<syntaxHighlight lang="bash">
#!/usr/bin/env nix-shell
#![allow()] /*
#!nix-shell -i bash -p rustc
rsfile="$(readlink -f $0)"
binfile="/tmp/$(basename "$rsfile").bin"
rustc "$rsfile" -o "$binfile" --edition=2021 && exec "$binfile" $@ || exit $?
*/
fn main() {
    for argument in std::env::args().skip(1) {
        println!("{}", argument);
    };
    println!("{}", std::env::var("HOME").expect(""));
}
</syntaxHighlight>

==== With dependencies ====

uses [https://github.com/fornwall/rust-script rust-script]

<syntaxHighlight lang="bash">
#!/usr/bin/env nix-shell
//! ```cargo
//! [dependencies]
//! time = "0.1.25"
//! ```
/*
#!nix-shell -i rust-script -p rustc -p rust-script -p cargo
*/
fn main() {
    for argument in std::env::args().skip(1) {
        println!("{}", argument);
    };
    println!("{}", std::env::var("HOME").expect(""));
    println!("{}", time::now().rfc822z());
}
</syntaxHighlight>

=== Haskell ===
<syntaxHighlight lang="haskell">
#! /usr/bin/env nix-shell
#! nix-shell -p "haskellPackages.ghcWithPackages (p: with p; [turtle])" -i runghc

{-# LANGUAGE OverloadedStrings #-}

import Turtle

main = echo "Hello world!"
</syntaxHighlight>

== Pinning nixpkgs ==

To pin nixpkgs to a specific version, add a third shebang line:

<syntaxHighlight lang="bash">
#! /usr/bin/env nix-shell
#! nix-shell -i bash
#! nix-shell -I nixpkgs=https://github.com/NixOS/nixpkgs/archive/aed4b19d312525ae7ca9bceb4e1efe3357d0e2eb.tar.gz

echo hello world
</syntaxHighlight>

== Flake ==

It is also possible to make it work for flake like in:
<syntaxHighlight lang="bash">
#!/usr/bin/env -S nix shell nixpkgs#bash nixpkgs#hello nixpkgs#cowsay --command bash

hello | cowsay
</syntaxHighlight>

The [https://nix.dev/manual/nix/2.19/command-ref/new-cli/nix3-shell doc] mentions that it should be possible to run more complex commands using multiple lines, but it does not work for me as reported [https://github.com/NixOS/nixpkgs/issues/280033 here].


== Performance ==

TODO ... why the startup delay? how to make it faster?

* [https://discourse.nixos.org/t/speeding-up-nix-shell-shebang/4048 Speeding up nix-shell shebang]
* [https://github.com/xzfc/cached-nix-shell cached-nix-shell] - Instant startup time for nix-shell
* [https://www.tweag.io/blog/2020-06-25-eval-cache/ Nix Flakes, Part 2: Evaluation caching - Tweag]

== See also ==

* [https://nixos.org/manual/nix/unstable/command-ref/nix-shell.html?highlight=shebang#use-as-a--interpreter nix-shell: Use As a #!-Interpreter] in nix manual
* [https://www.mankier.com/1/nix-shell#Use_As_a_%23!-Interpreter nix-shell: Use As a #!-Interpreter] man page
* [https://gist.github.com/travisbhartwell/f972aab227306edfcfea nix-shell and Shebang Lines]
* [https://notes.yukiisbo.red/posts/2021/07/Spice_up_with_Nix_Scripts.html Spice up with Nix: Scripts with magical dependencies]

[[Category:Nix]]
[[Category:Shell]]