Shebang(Unix)

In computing, a shebang (also called a hashbang, hashpling, or pound bang) refers to the characters "#!" when they are the first two characters in a text file. Unix-like operating systems take the presence of these two characters as an indication that the file is a script, and try to execute that script using the interpreter specified by the rest of the first line in the file. For instance, shell scripts for the Bourne shell start with the first line:

#!/bin/sh

More precisely, a shebang line consists of a number sign and an exclamation point character ("#!"), then optionally any amount of whitespace, then followed by the (absolute) path to the interpreter program that will provide the interpretation. The shebang is looked for and used when a script is invoked directly (as with a regular executable), and largely to the end of making scripts look and act similarly to regular executables, to the operating system and to the user.

Because the "#" character is often used as the comment marker in scripting languages, the contents of the shebang line will be automatically ignored by the interpreter itself; the shebang line only exists to specify to the operating system the correct interpreter to use.

Etymology

The name shebang comes from an inexact contraction of SHArp bang or haSH bang, referring to the two typical Unix names of the two characters. Unix jargon uses sharp or hash (and sometimes, even, mesh) to refer to the number sign character and bang to refer to the exclamation point, hence shebang. Another theory on sh in shebang's name is from default shell sh, usually invoked with shebang.

History

The shebang was introduced by Dennis Ritchie between Version 7 Unix and 8 at Bell Laboratories. It was then also added to the BSD line at Berkeley (present in 4BSD and activated by default in 4.2BSD). As Version 8 and later versions were not released to the public, the first widely known appearance of this feature was on BSD.

Portability

Shebangs specify absolute paths to system executables; this can cause problems on systems which have non-standard file system layouts (such as GoboLinux or NixOS). Even when systems have fairly standard paths, it is quite possible for variants of the same operating system to have different locations for the desired interpreter.

In the absence of rigidly standardized locations for each interpreter, the shebang would on some systems try to execute something that doesn't exist where the shebang says it is. Therefore shebangs can limit the portability of the file.

Because of this it is not uncommon to need to edit the shebang line after copying a script from one computer to another because the path that was coded into the script may not apply on a new machine, depending on the consistency in past convention of placement of the interpreter. For this and other reasons, POSIX does not standardize the feature.

Often, the program /usr/bin/env can be used to circumvent this limitation. Care should be taken with this approach as while it increases portability it may introduce vulnerabilities to gain unauthorized root access. There are still some portability issues with OpenServer 5.0.6 and Unicos 9.0.2 which have only /bin/env and no /usr/bin/env.

Another portability problem is the interpretation of the command arguments. Some systems do not split up the arguments; for example, when running the script with the first line like,

#!/usr/bin/env python -c

it will be invoked as,

/usr/bin/env "python -c"

That is, "python -c" will be passed as one argument to /usr/bin/env, rather than two arguments, "python" and "-c". On Linux, this will lead to the error message,

/usr/bin/env: python -c: No such file or directory

Cygwin also behaves this way. Some other systems handle the arguments differently.

To this end, it is possible to explot slight differences in command syntax between the shell and the interpreter, and make the header use /bin/sh. This is a very simple instance of a polyglot program; for example, Tcl comments are continued by backslashes, but shell comments are not:

#!/bin/sh
# Run wish from the users PATH \
exec wish -- "$0" ${1+"$@"}

and Perl statements can span multiple lines even when the shell would consider the command finished:

#!/bin/sh
eval 'exec perl -ST $0 ${1+"$@"}'
if 0;

Another common problem are scripts accidentally stored using DOS newlines with a shebang. Some systems then interpret the carriage return character as part of the interpreter's name, resulting in error messages like this:

-bash: ./test.sh: /bin/sh^M: bad interpreter: No such file or directory 

Plan 9 from Bell Labs demands a shebang when trying to execute a text file because it needs to know how to run the file. For example, a shell script could have the line

#!/bin/rc

at the top. If one is forgotten, the system would say "exec header invalid."

In many Linux systems, /bin/sh is a symlink to /bin/bash, since bash implements all the commands available in the Bourne shell. Some distributions link this to other shells, however. Ubuntu and Debian use Debian Almquist shell, for instance, for better performance. When script developers erroneously use the #!/bin/sh in scripts that contain bash-specific commands (bashisms), they will fail on systems that use a different default shell. The problem can be fixed by using only sh-compatible commands or by explicitly stating #!/bin/bash as the shebang.

Unicode

Unicode byte order marks at the beginning of a script cause problems, as the shebang #! is no longer the first two bytes of a script file. It is advised that, if writing scripts on a unicode-compliant text editor, the byte-order mark feature be turned off.

As magic number

The shebang is actually a human-readable instance of a magic number in the executable file, the magic byte string being 0x23 0x21, the two-character encoding in ASCII. (Executable files that do not require an interpreter program start with other magic combinations. See File format for more details of magic numbers.)

There have been rumours that some old versions of UNIX look for the normal shebang followed by a space and a slash ("#! /"), but this appears to be untrue.

On Unix-like operating systems, new image files are started by the "exec" family functions. This is where the operating system will detect that an image file is either a script or an executable binary. The presence of the shebang will result in the execution of the specified (usually script language) executable. This is described on the Solaris and Linux man page "execve".

Examples

Some typical interpreters for shebang lines:

  • #!/bin/bash — Execute using the Bourne-again shell
  • #!/bin/sh — On some systems, such as Solaris, this is the Bourne shell. On Linux systems there is usually no Bourne shell and this is a link to another shell, such as bash. According to the Single UNIX Specification's requirements for /bin/sh, such a shell will usually mimic the Bourne shell's behaviour, but be aware that using #!/bin/sh in shell scripts may invoke different Bourne-compatible shells on different systems.
  • #!/usr/bin/perl — Execute using Perl
  • #!/usr/bin/emacs --script — Execute using Emacs, need Emacs 22.

Shebang lines can also include specific options that will be passed to the interpreter; see the examples below. However, implementations differ widely on how options are parsed.

This file is a shell script, the Unix equivalent of a DOS batch file:

#!/bin/sh
echo "Hi there.";
# The rest of the shell script.
# ...

This file is a Perl script, to be run with warnings enabled (-w):

#!/usr/bin/perl -w
print "Hello world!\n";
# The rest of the Perl script.
# ...
Comments