Feature request: Strip "Nix-style consecutive shebangs" or introduce limited `#` line comments

[dpc]

I'm trying to write a script that uses nix hashbang, to import Rust toolchain, and then use cargo-script from it, but Rust side is very picky about the hashbangs:

> cat cargo-script-test.rs
#!/usr/bin/env nix
#!nix shell github:nix-community/fenix?rev=80dbdab137f2809e3c823ed027e1665ce2502d74#minimal.toolchain -c cargo -q -Zscript
---
[dependencies]
duct = "*"
snafu = "*"
---

use duct::cmd;
use snafu::Whatever;
use snafu::ResultExt;

fn main() -> Result<(), Whatever> {
    println!("Hello from cargo-script");
    cmd!("echo", "hi").run().whatever_context("Failed to run command")?;
    Ok(())
}

> ./cargo-script-test.rs
error: expected `[`, found `nix`
 --> cargo-script-test.rs:2:3
  |
2 | #!nix shell github:nix-community/fenix?rev=80dbdab137f2809e3c823ed027e1665ce2502d74#minimal.toolchain -c cargo -q -Zscript
  |   ^^^ expected `[`
  |
  = note: the token sequence `#!` here looks like the start of a shebang interpreter directive but it is not
  = help: if you meant this to be a shebang interpreter directive, move it to the very start of the file

> cargo --version -v
cargo 1.91.0-nightly (a6c58d430 2025-08-26)
release: 1.91.0-nightly
commit-hash: a6c58d43051d01d83f55a3e61ef5f5b2b0dd6bd9
commit-date: 2025-08-26
host: x86_64-unknown-linux-gnu
libgit2: 1.9.1 (sys:0.20.2 vendored)
libcurl: 8.14.1-DEV (sys:0.4.82+curl-8.14.1 vendored ssl:OpenSSL/3.5.0)
ssl: OpenSSL 3.5.0 8 Apr 2025
os: NixOS 25.5.0 [64-bit]

Notably moving one line fixes it:

> cat cargo-script-test.rs
#!/usr/bin/env nix
---
#!nix shell github:nix-community/fenix?rev=80dbdab137f2809e3c823ed027e1665ce2502d74#minimal.toolchain -c cargo -q -Zscript
[dependencies]
duct = "*"
snafu = "*"
---

use duct::cmd;
use snafu::Whatever;
use snafu::ResultExt;


fn main() -> Result<(), Whatever> {
    println!("Hello from cargo-script");
    cmd!("echo", "hi").run().whatever_context("Failed to run command")?;
    Ok(())
}
> ./cargo-script-test.rs
Hello from cargo-script
hi
>

But this is only because nix seems much more liberal and persistent at looking for its own directive, and this might not work with other tooling like this.

It seems to me that it would be preferable if cargo-script accepted and ignored any amount of leading newlines and lines starting with a hash, permitting shenanigans like this.

[fmease]

It seems to me that it would be preferable if cargo-script accepted and ignored any amount of leading newlines and lines starting with a hash, permitting shenanigans like this.

To clear things up, it's not Cargo that reads the shebang interpreter directives #!/usr/bin/env nix, it's the OS's program loader which in this case invokes nix (I don't know much about NixOS, so details may vary).

Next up, the #! directives on subsequent lines are not true Unix interpreter directives, they're a Nix-specific feature. I don't know much about Nix lang (so excuse me if I get anything wrong) but I've just read https://nix.dev/manual/nix/2.28/command-ref/new-cli/nix.html#shebang-interpreter and https://nix.dev/manual/nix/2.28/language/syntax#comments.

Cargo (executed indirectly by nix) doesn't read the contents of the shebang, it only reads the frontmatter. Anyway, ultimately rustc reads the file, skips the Unix shebang interpreter directive (see also) and the frontmatter and compiles the crate.

---

So basically, this requires a language change, namely to lexically admit "Nix-style shebangs" in subsequent lines (I do wonder, are there any other scripting languages which feature consecutive shebangs?).

[fmease]

namely to lexically admit "Nix-style shebangs" in subsequent lines.

without regressing crate-level inner attributes, of course (see below); so there would likely be certain restrictions in place if this were to be accepted just like it's the case today already for the true shebang (†).

#!directive
#![first]
#![second]
// ^ the two lines above obv need to keep being parsed as attrs, not lexed as shebangs

(†) E.g., for the true shebang interpreter directive, the program path can't really be equal to [ or /*file*/[, rustc would complain later with a parse error even tho these two are perfectly fine program paths from the perspective of the program loader (edit: some restrictions seem to apply for e.g., [ but not for /*file*/[).

[dpc]

Next up, the #! directives on subsequent lines are not true Unix interpreter directives,

So basically, this requires a language change, namely to lexically admit "Nix-style shebangs" in subsequent lines (I do wonder, are there any other scripting languages which feature consecutive shebangs?).

There isn't really anything like "consecutive shebangs". There can only be one command to execute the script's path as an argument for.

However software dealing with shebang shenanigans expects to be used in shell scripts where lines starting with # are comments. So typically they piggyback on that fact and put any extra data/trickery into "commented out lines". Just like here nix invents kind of a consecutive shebang thing, but I guess it's just to let people write some comments/stuff between real shebang and nix-"shebang". So this would work:

#!/usr/bin/env nix
# This script uses nix shell.
#!nix shell nushell

<some nushell syntax>

Arguably cargo-script is turning rs files into "shell-script"s. Not really, but ... kind of? At very least the usage becomes shell-script like, and the shebang syntax is very shell-script-like.

Anyway, ultimately rustc reads the file, skips the Unix shebang interpreter directive (see also) and the frontmatter and compiles the crate.

Oh, I forgot about crate-inner attributes. That makes this proposed change a bit more gnarly and less elegant, but oh well.

[fmease]

However software dealing with shebang shenanigans expects to be used in shell scripts where lines starting with # are comments.

I don't know if that's generally expected. I know that # line comments and shebangs go hand in hand, historically speaking. However, nowadays, shebangs are simply a special case in the grammar of various languages and are disconnected from the original # line comments.

E.g., take ECMAScript/JavaScript. It also features shebang interpreter directives in its grammar (https://tc39.es/ecma262/2025/multipage/ecmascript-language-lexical-grammar.html#sec-hashbang). And just like in Rust, they're only permitted on the very first line of the input stream and JavaScript doesn't feature # line comments either¹.

There isn't really anything like "consecutive shebangs". There can only be one command to execute the script's path as an argument for.

That I'm aware of. As I've outlined above, I'm familiar with the precise mechanisms behind shebangs. I'm talking about the newly coined "consecutive shebangs" as if they were something extra … well because they would be from the perspective of the Rust grammar (assuming they'd be of the form #!).

Ofc, there might be a way / the concrete proposal might be to introduce limited # comments to Rust instead in which case the term "consecutive shebangs" wouldn't make sense, so fair enough.

Footnotes

1. It does feature HTML block comments <!-- --> in its grammar though :P next to its normal C-style ones. ↩

[fmease]

I can tell you in advance though that the likelihood of (restricted) # line comments getting accepted into the language to support this use case is astronomically low. That's why I was focusing on "consecutive" #!s instead (however, I don't know if those are any more likely to get accepted).

[dpc]

Well, it comes down to - if the command used in the shebang needs some additional data passed that that can't be part of the shebang line (like in the nix shebang example) how should it achieve it?

It's not exactly some super commonly used mechanism. There is no standard for it. Other than nix shebang I can't remember previous time I was nesting or even "parameterizing" a shebang. In principle I can imagine shebangs nesting used e.g. like this:

• nix shebang to reproduce all the necessary tools,
• something like tor sandbox shebang to wrap a command in Tor ([oniux](https://blog.torproject.org/introducing-oniux-tor-isolation-using-linux-namespaces/ or orjail), or some other "jailing/namespacing" tool,
• then cargo-script to execute the Rust-script

Completely made up, but plausible.

I can tell you in advance though that the likelihood of (restricted) # line comments getting accepted into the language to support this use case is astronomically low. That's why I was focusing on "consecutive" #!s instead (however, I don't know if those are any more likely to get accepted).

Oh well. It's a long shot. Worst case, hopefully the issue might help someone find the workaround (moving extra comments to Cargo's manifest which does use # as comments.