Shebang (Unix)
In computing, a shebang is the character sequence, consisting of the characters number sign and exclamation mark, at the beginning of a script. It is also called sharp-exclamation, sha-bang, hashbang, pound-bang, or hash-pling.
When a text file with a shebang is used as if it were an executable in a Unix-like operating system, the program loader mechanism parses the rest of the file's initial line as an interpreter directive. The loader executes the specified interpreter program, passing to it as an argument the path that was initially used when attempting to run the script, so that the program may use the file as input data. For example, if a script is named with the path path/to/script, and it starts with the line
#! /bin/sh, then the program loader is instructed to run the program /bin/sh, passing path/to/script as the first argument.The shebang line is usually ignored by the interpreter, because the "#" character is a comment marker in many scripting languages; some language interpreters that do not use the hash mark to begin comments still may ignore the shebang line in recognition of its purpose.
Syntax
The form of a shebang interpreter directive is as follows:#! interpreter
in which interpreter is a path to an executable program. The space between and interpreter is optional. There could be any number of spaces or tabs either before or after interpreter. The optional-arg will include any extra spaces up to the end-of-line.
In Linux, the file specified by interpreter can be executed if it has the execute rights and is one of the following:
- a native executable, such as an ELF binary
- any kind of file for which an interpreter was registered via the binfmt_misc mechanism
- another script starting with a shebang
In Solaris- and Darwin-derived operating systems, the file specified by interpreter must be an executable binary and cannot itself be a script.
If you invoke the script by explicitly calling the interpreter, the
#! line is never consulted.So, if you run
sh script.sh, the first line has no effect. If script2.sh’s first line is #!/usr/games/nibbles, running sh script2.sh will not try to open the script in nibbles.Examples
Some typical shebang lines:-
#! /bin/sh– Execute the file using the Bourne shell, or a compatible shell, assumed to be in the /bin directory -
#! /bin/bash– Execute the file using the Bash shell -
#! /usr/bin/pwsh– Execute the file using PowerShell -
#! /usr/bin/env python3– Execute with a Python interpreter, using the env program search path to find it -
#! /bin/false– Do nothing, but return a non-zero exit status, indicating failure. Used to prevent stand-alone execution of a script file intended for execution in a specific context, such as by the.command from sh/bash,sourcefrom csh/tcsh, or as a.profile,.cshrc, or.login file.
Purpose
Interpreter directives allow scripts and data files to be used as commands, hiding the details of their implementation from users and other programs, by removing the need to prefix scripts with their interpreter on the command line.For example, consider a script having the initial line
#! /bin/sh -x. It may be invoked simply by giving its file path, such as some/path/to/foo, and some parameters, such as bar and baz:some/path/to/foo bar baz
In this case
/bin/sh is invoked in its place, with parameters -x, some/path/to/foo, bar, and baz, as if the original command had been/bin/sh -x some/path/to/foo bar baz
Most interpreters make any additional arguments available to the script. If
/bin/sh is a POSIX-compatible shell, then bar and baz are presented to the script as the positional parameter array "$@", and individually as parameters "$1" and "$2" respectively.Because the initial # is the character used to introduce comments in the POSIX shell language, the whole shebang line is ignored by the interpreter. However, it is up to the interpreter to ignore the shebang line, and not all do so; thus, a script consisting of the following two lines simply outputs both lines when run:
#! /bin/cat
Hello world!
Strengths
When compared to the use of global association lists between file extensions and the interpreting applications, the interpreter directive method allows users to use interpreters not known at a global system level, and without administrator rights. It also allows specific selection of interpreter, without overloading the filename extension namespace, and allows the implementation language of a script to be changed without changing its invocation syntax by other programs. Invokers of the script need not know what the implementation language is as the script itself is responsible for specifying the interpreter to use.Portability
Program location
Shebangs must specify absolute paths to system executables; this can cause problems on systems that have a non-standard file system layout. 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. Python, for example, might be in /usr/bin/python3, /usr/local/bin/python3, or even something like /home/username/bin/python3 if installed by an ordinary user.A similar problem exists for the POSIX shell, since POSIX only required its name to be sh, but did not mandate a path. A common value is, but some systems such as Solaris have the POSIX-compatible shell at /usr/xpg4/bin/sh. In many Linux systems, /bin/sh is a hard or symbolic link to /bin/bash, the Bourne Again shell. Using bash-specific syntax while maintaining a shebang pointing to sh is also not portable.
Because of this it is sometimes required 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 reason and because POSIX does not standardize path names, POSIX does not standardize the feature. The GNU Autoconf tool can test for system support with the macro AC_SYS_INTERPRETER.
Often, the program can be used to circumvent this limitation by introducing a level of indirection. is followed by, followed by the desired command without full path, as in this example:
#!/usr/bin/env sh
This mostly works because the path is commonly used for the utility, and it invokes the first found in the user's $PATH, typically.
This particular example is of limited utility: neither nor is universal, with similar numbers of devices lacking each. More broadly using for any script still has some portability issues with OpenServer 5.0.6 and Unicos 9.0.2 which have only and no.
Using results in run-time indirection, which has the potential to degrade system security; for this reason some commentators recommend against its use in packaged software, reserving it only for "educational examples".
Argument splitting
Command arguments are split in different ways across platforms.Some systems do not split up the arguments; for example, when running the script with the first line,
#!/usr/bin/env python3 -c
all text after the first space is treated as a single argument, that is, will be passed as one argument to, rather than two arguments. Such systems include Linux and Cygwin.
Another approach is the use of a wrapper. FreeBSD 6.0 introduced a option to its as it changed the shebang-reading behavior to non-splitting. This option tells to split the string itself. The GNU utility since coreutils 8.30 also includes this feature. Although using this option mitigates the portability issue on the kernel end with splitting, it adds the requirement that supports this particular extension.
Character interpretation
Another problem is scripts containing a carriage return character immediately after the shebang line, perhaps as a result of being edited on a system that uses DOS line breaks, such as Microsoft Windows. Some systems interpret the carriage return character as part of the interpreter command, resulting in an error message.Magic number
The shebang is actually a human-readable instance of a magic number in the executable file, the magic byte string being, the two-character encoding in ASCII of. This magic number is detected by the "exec" family of functions, which determine whether a file is a script or an executable binary. The presence of the shebang will result in the execution of the specified executable, usually an interpreter for the script's language. It has been claimed that some old versions of Unix expect the normal shebang to be followed by a space and a slash, but this appears to be untrue; rather, blanks after the shebang have traditionally been allowed, and sometimes documented with a space, as described in the 1980 historical email below.The shebang characters are represented by the same two bytes in extended ASCII encodings, including UTF-8, which is commonly used for scripts and other text files on current Unix-like systems. However, UTF-8 files may begin with the optional byte order mark ; if the "exec" function specifically detects the bytes and, then the presence of the BOM before the shebang will prevent the script interpreter from being executed. Some authorities recommend against using the byte order mark in POSIX scripts, for this reason and for wider interoperability and philosophical concerns. Additionally, a byte order mark is not necessary in UTF-8, as that encoding does not have endianness issues; it serves only to identify the encoding as UTF-8.