{{Short description|Symbol "#!", used in computing}} {{Use dmy dates|date=September 2020}} {{redirect|hash-bang|{{mono|#!}} in URLs|hash-bang fragment}} {{infobox punctuation |mark=<nowiki>#!</nowiki> |name = shebang }} In computing, a '''shebang''' is the character sequence {{mono|#!}}, consisting of the characters number sign (also known as sharp or hash) and exclamation mark (also known as bang), at the beginning of a script. It is also called '''sharp-exclamation''', '''sha-bang''',<ref>{{cite web|title=Advanced Bash Scripting Guide: Chapter 2. Starting Off With a Sha-Bang|url=http://tldp.org/LDP/abs/html/sha-bang.html|access-date=10 December 2019|url-status=live|archive-url=https://web.archive.org/web/20191210080709/http://tldp.org/LDP/abs/html/sha-bang.html|archive-date=10 December 2019}}</ref><ref>{{cite book |last=Cooper |first=Mendel |title=Advanced Bash Scripting Guide 5.3 Volume 1 |publisher=lulu.com |date=5 November 2010 |isbn=978-1-4357-5218-4 |page=5 |url=https://books.google.com/books?id=WPXkgFRd4OEC&q=sha-bang&pg=PA5 }}</ref> '''hashbang''',<ref>{{cite book |last=MacDonald |first=Matthew |title=HTML5: The Missing Manual |publisher=O'Reilly Media |location=Sebastopol, California |year=2011 |isbn=978-1-4493-0239-9 |page=373 |url=https://books.google.com/books?id=SR7HXy2XvBEC&pg=PA373 }}</ref><ref>{{cite book |last=Lutz |first=Mark |title=Learning Python |edition=4th |publisher=O'Reilly Media |date=September 2009 |isbn=978-0-596-15806-4 |page=48 |url=https://books.google.com/books?id=1HxWGezDZcgC&pg=PA48 }}</ref> '''pound-bang''',<ref>{{cite book |last=Guelich, Gundavaram and Birznieks |first=Scott, Shishir and Gunther |title=CGI Programming with PERL |edition=2nd |publisher=O'Reilly Media |date=29 July 2000 |isbn=978-1-56592-419-2 |page=[https://archive.org/details/cgiprogrammingwi00guel/page/358 358] |url=https://archive.org/details/cgiprogrammingwi00guel |url-access=registration }}</ref><ref>{{cite book |last=Lie Hetland |first=Magnus |title=Beginning Python: From Novice to Professional |publisher=Apress |date=4 October 2005 |isbn=978-1-59059-519-0 |page=21 |url=https://books.google.com/books?id=S0l1YFpRFVAC&q=pound+bang&pg=PA21 }}</ref> or '''hash-pling'''.<ref>{{cite book |last=Schitka |first=John |title=Linux+ Guide to Linux Certification |publisher=Course Technology |date=24 December 2002 |isbn=978-0-619-13004-6 |page=353 |url=https://books.google.com/books?id=l7JhL9rJLEgC&q=hashpling&pg=PA353 }}</ref>
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.<ref name="linux">{{cite web|title=execve(2) - Linux man page |url=http://linux.die.net/man/2/execve |access-date=21 October 2010}}</ref> For example, if a script is named with the path ''path/to/script'', and it starts with the line <code>#!/bin/sh</code>, 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.<ref>{{cite web|url=http://srfi.schemers.org/srfi-22/|title=SRFI 22}}</ref>
==Syntax== The form of a shebang interpreter directive is as follows:<ref name="linux" /> #!''interpreter'' [''optional-one-arg-only''] in which ''interpreter'' is a path to an executable program. It is optional to have a space between {{mono|#!}} and ''interpreter''. 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 (such as for executing Microsoft .exe binaries using wine) * another script starting with a shebang
On Linux and Minix, an interpreter can also be a script. A chain of shebangs and wrappers yields a directly executable file that gets the encountered scripts as parameters in reverse order. For example, if file ''/bin/A'' is an executable file in ELF format, file ''/bin/B'' contains the shebang {{code|#!/bin/A optparam}}, and file ''/bin/C'' contains the shebang {{code|#!/bin/B}}, then executing file ''/bin/C'' resolves to {{code|/bin/B /bin/C}}, which finally resolves to {{code|/bin/A optparam /bin/B /bin/C}}.
In Solaris- and Darwin-derived operating systems (such as macOS), the file specified by ''interpreter'' must be an executable binary and cannot itself be a script.<ref>{{Cite web |url=https://stackoverflow.com/questions/45444823/python3-shebang-line-not-working-as-expected |title = Python - Python3 shebang line not working as expected}}</ref>
If the script is invoked by explicitly calling the interpreter, the <code>#!</code> line is never consulted. For example, if <code>script.sh</code>’s first line is <code>#!/usr/games/nibbles</code>, running <code>sh script.sh</code> will '''not''' try to open the script in <code>nibbles</code>, but <code>./script.sh</code> will.
==Examples== Some typical shebang lines: * <code>#!/bin/sh</code> – Execute the file using the Bourne shell, or a compatible shell, assumed to be in the /bin directory * <code>#!/bin/bash</code> – Execute the file using the Bash shell * <code>#!/usr/bin/pwsh</code> – Execute the file using PowerShell * <code>#!/usr/bin/env python3</code> – Execute with a Python interpreter, using the env program search path to find it * <code>#!/bin/false</code> – 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 <code>'''.'''</code> command from sh/bash, <code>source</code> from csh/tcsh, or as a .profile, .cshrc, or .login file.
Shebang lines may include specific options that are passed to the interpreter. However, implementations vary in the parsing behavior of options; for portability, only one option should be specified without any embedded whitespace.<ref name="blankreq">{{cite web |last1=Maschek |first1=Sven |title=The #! magic, details about the shebang/hash-bang mechanism: Blank after #! required? |url=https://www.in-ulm.de/~mascheck/various/shebang/#blankrequired |website=www.in-ulm.de |access-date=18 January 2024 |date=30 December 2010}}</ref> Further portability guidelines are found below.
==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 <code>#!/bin/sh -x</code>. It may be invoked simply by giving its file path, such as <code><i>some/path/to/foo</i></code>,<ref>if permitted by the file's ''exec'' permission bits</ref> and some parameters, such as <code>bar</code> and <code>baz</code>:
some/path/to/foo bar baz
In this case <code>/bin/sh</code> is invoked in its place, with parameters <code>-x</code>, <code><i>some/path/to/foo</i></code>, <code>bar</code>, and <code>baz</code>, 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 <code>/bin/sh</code> is a POSIX-compatible shell, then <code>bar</code> and <code>baz</code> are presented to the script as the positional parameter array <code>"$@"</code>, and individually as parameters <code>"$1"</code> and <code>"$2"</code> respectively.
Because the initial # is the character used to introduce comments in the POSIX shell language (and in the languages understood by many other interpreters), 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 (where one file extension refers to more than one file type), 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 (or paths relative to current working directory) 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 {{tt|/bin/sh}}, but some systems such as Solaris have the POSIX-compatible shell at ''/usr/xpg4/bin/sh''.<ref>{{cite web |url=http://pubs.opengroup.org/onlinepubs/9699919799/utilities/sh.html#tag_20_117_16|title=The Open Group Base Specifications Issue 7 |year=2008|access-date=5 April 2010}}</ref> In many Linux systems, ''/bin/sh'' is a hard or symbolic link to ''/bin/bash'', the Bourne Again shell (BASH). Using bash-specific syntax while maintaining a shebang pointing to ''sh'' is also not portable.<ref>{{cite web|url=http://www.pixelbeat.org/programming/shell_script_mistakes.html|title=pixelbeat.org: Common shell script mistakes|quote=It's much better to test scripts directly in a POSIX compliant shell if possible. The `bash --posix` option doesn't suffice as it still accepts some 'bashisms'}}</ref>
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.<ref>{{citation |chapter-url=https://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html|title=The Open Group Base Specifications (IEEE Std 1003.1-2017)|quote=If the first line of a file of shell commands starts with the characters "#!", the results are unspecified |year=2018|orig-year =2008|edition=Issue 7| chapter=Chapter 2. Shell Command Language| publisher=IEEE}}</ref> The GNU Autoconf tool can test for system support with the macro AC_SYS_INTERPRETER.<ref>{{citation |url=https://www.gnu.org/software/autoconf/manual/autoconf-2.67/autoconf.html#System-Services|title=Autoconf|publisher=Free Software Foundation|quote=Macro: AC_SYS_INTERPRETER: Check whether the system supports starting scripts with a line of the form ‘#!/bin/sh’ to select the interpreter to use for the script.}}</ref>
Often, the program {{tt|/usr/bin/env}} can be used to circumvent this limitation by introducing a level of indirection. {{code|#!}} is followed by {{tt|/usr/bin/env}}, followed by the desired command without full path, as in this example: #!/usr/bin/env sh
This mostly works because the path {{tt|/usr/bin/env}} is commonly used for the {{tt|env}} utility, and it invokes the first {{tt|sh}} found in the user's $PATH, typically {{tt|/bin/sh}}.
This particular example (using {{tt|sh}}) is of limited utility: neither {{tt|/bin/sh}} nor {{tt|/usr/bin/env}} is universal, with similar numbers of devices lacking each. More broadly using {{tt|#!/usr/bin/env}} for any script still has some portability issues with OpenServer 5.0.6 and Unicos 9.0.2 which have only {{tt|/bin/env}} and no {{tt|/usr/bin/env}}.
Using {{tt|#!/usr/bin/env}} results in ''run-time'' indirection, which has the potential to degrade system security; for this reason some commentators recommend against its use<ref>{{cite web |url=https://burnthewhich.github.io/shbangenv/shbangenv |title=What's with #!/usr/bin/env bash? | access-date=2024-03-06}}</ref> 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, {{code|python3 -c}} will be passed as one argument to {{tt|/usr/bin/env}}, rather than two arguments. Such systems include Linux<ref>{{cite web|url=https://man7.org/linux/man-pages/man2/execve.2.html|title=execve(2) man page}}, section "Interpreter scripts"</ref><ref>{{cite web|url=http://mail-index.netbsd.org/netbsd-users/2008/11/09/msg002388.html |title=/usr/bin/env behaviour |publisher=Mail-index.netbsd.org |date=9 November 2008 |access-date=18 November 2010}}</ref> and Cygwin.
Another approach is the use of a wrapper. FreeBSD 6.0 (2005) introduced a {{tt|-S}} option to its {{tt|env}} as it changed the shebang-reading behavior to non-splitting. This option tells {{tt|env}} to split the string itself.<ref>{{man|1|env|FreeBSD}}</ref> The GNU {{tt|env}} utility since coreutils 8.30 (2018) also includes this feature.<ref>{{cite web |title=env invocation |url=https://www.gnu.org/software/coreutils/manual/html_node/env-invocation.html#g_t_002dS_002f_002d_002dsplit_002dstring-usage-in-scripts |website=GNU Coreutils |access-date=11 February 2020}}</ref> Although using this option mitigates the portability issue on the kernel end with splitting, it adds the requirement that {{tt|env}} 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.<ref>{{cite web |url=http://askubuntu.com/questions/372672/what-could-cause-a-script-to-fail-to-find-python-when-it-has-usr-bin-env-pyt/372691#372691 |title=Carriage Return causes bash to fail| date=8 November 2013}}</ref>
===Magic number=== The shebang is actually a human-readable instance of a magic number in the executable file, the magic byte string being {{mono|0x23 0x21}}, the two-character encoding in ASCII of {{mono|#!}}. 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<ref>{{cite web|title=GNU Autoconf Manual v2.57, Chapter 10: Portable Shell Programming|url=http://www.gnu.org/software/autoconf/manual/autoconf-2.57/html_chapter/autoconf_10.html |archive-url=https://web.archive.org/web/20080118164924/http://www.gnu.org/software/autoconf/manual/autoconf-2.57/html_chapter/autoconf_10.html |access-date=14 May 2020|archive-date=18 January 2008}}</ref> that some old versions of Unix expect the normal shebang to be followed by a space and a slash (''{{code|#! /}}''), but this appears to be untrue;<ref name="blankreq" /> 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 (BOM); if the "exec" function specifically detects the bytes {{mono|0x23}} and {{mono|0x21}}, then the presence of the BOM ({{mono|0xEF 0xBB 0xBF}}) before the shebang will prevent the script interpreter from being executed. Some authorities recommend against using the byte order mark in POSIX (Unix-like) scripts,<ref name="utf8-byte-order-mark" /> 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.<ref name="utf8-byte-order-mark">{{cite web |title=FAQ UTF-8, UTF-16, UTF-32 & BOM: Can a UTF-8 data stream contain the BOM character (in UTF-8 form)? If yes, then can I still assume the remaining UTF-8 bytes are in big-endian order? |url=https://www.unicode.org/faq/utf_bom.html#bom5 |website=Unicode |access-date=10 November 2023}}</ref>
==Etymology== An executable file starting with an interpreter directive is simply called a script, often prefaced with the name or general classification of the intended interpreter. The name ''shebang'' for the distinctive two characters may have come from an inexact contraction of ''SHArp bang'' or ''haSH bang'', referring to the two typical Unix names for them. Another theory on the ''sh'' in ''shebang'' is that it is from the default shell ''sh'', usually invoked with shebang.<ref>{{cite web|url=http://catb.org/jargon/html/S/shebang.html |title=Jargon File entry for shebang |website=Catb.org |access-date=16 June 2010}}</ref> This usage was current by December 1989,<ref>{{cite web|url=https://groups.google.com/group/comp.sources.bugs/msg/96bbbe2b019464c5?dmode=source&output=gplain&noredirect|title=Perl didn't grok setuid scripts that had a space on the first line between the shebang and the interpreter name|publisher=USENET|last=Wall|first=Larry|author-link=Larry Wall}}</ref> and probably earlier.
==History== The shebang was introduced by Dennis Ritchie between Edition 7 and 8 at Bell Laboratories. It was also added to the BSD releases from Berkeley's Computer Science Research (present at 2.8BSD<ref>{{citation |title=2.8/usr/kernel/sys/sys/sys1.c |work=The CSRG Archives CD-ROM 1: Berkeley Systems 1978-1986 |date=August 1998 |last=McKusick |first=Marshall Kirk |author-link=Marshall Kirk McKusick |url=https://www.mckusick.com/csrg/ |archive-url=https://archive.org/download/The_CSRG_Archives_CD-ROM_1_August_1998_Marshall_Kirk_McKusick/The%20CSRG%20Archives%20CD-ROM%201%20(August%201998)%20(Marshall%20Kirk%20McKusick).ISO/2.8%2Fusr%2Fkernel%2Fsys%2Fsys%2Fsys1.c |archive-date=2017-07-08 |url-status=live |at=line 43 |quote=<code># define SCRMAG '#!'</code>}}</ref> and activated by default by 4.2BSD). As AT&T Bell Laboratories Edition 8 Unix, and later editions, were not released to the public, the first widely known appearance of this feature was on BSD.
The lack of an interpreter directive, but support for shell scripts, is apparent in the documentation from Version 7 Unix in 1979,<ref>{{citation|url=http://cm.bell-labs.com/7thEdMan/v7vol2a.pdf|title=Unix Time-Sharing System: Unix Programmer's Manual |edition=Seventh |volume=2A|date=January 1979 |archive-url=https://web.archive.org/web/20010605052449/http://cm.bell-labs.com/7thEdMan/v7vol2a.pdf |archive-date=2001-06-05}}</ref>{{page needed|date=January 2026}} which describes instead a facility of the Bourne shell where files with execute permission would be handled specially by the shell, which would (sometimes depending on initial characters in the script, such as ":" or "#") spawn a subshell which would interpret and run the commands contained in the file. In this model, scripts would only behave as other commands if called from within a Bourne shell. An attempt to directly execute such a file via the operating system's own ''exec()'' system call would fail, preventing scripts from behaving uniformly as normal system commands.
=== Version 8 improved shell scripts === In later versions of Unix-like systems, this inconsistency was removed. Dennis Ritchie introduced kernel support for interpreter directives in January 1980, for Version 8 Unix, with the following description:<ref>{{citation |title=4.0/usr/src/sys/newsys/sys1.c |work=The CSRG Archives CD-ROM 1: Berkeley Systems 1978-1986 |date=August 1998 |last=McKusick |first=Marshall Kirk |author-link=Marshall Kirk McKusick |url=https://www.mckusick.com/csrg/ |archive-url=https://archive.org/download/The_CSRG_Archives_CD-ROM_1_August_1998_Marshall_Kirk_McKusick/The%20CSRG%20Archives%20CD-ROM%201%20(August%201998)%20(Marshall%20Kirk%20McKusick).ISO/4.0%2Fusr%2Fsrc%2Fsys%2Fnewsys%2Fsys1.c |archive-date=2017-07-08 |url-status=live}}</ref>
From uucp Thu Jan 10 01:37:58 1980 >From dmr Thu Jan 10 04:25:49 1980 remote from research The system has been changed so that if a file being executed begins with the magic characters #! , the rest of the line is understood to be the name of an interpreter for the executed file. Previously (and in fact still) the shell did much of this job; it automatically executed itself on a text file with executable mode when the text file's name was typed as a command. Putting the facility into the system gives the following benefits. 1) It makes shell scripts more like real executable files, because they can be the subject of 'exec.' 2) If you do a 'ps' while such a command is running, its real name appears instead of 'sh'. Likewise, accounting is done on the basis of the real name. 3) Shell scripts can be set-user-ID.{{efn|The setuid feature is disabled in most modern operating systems following the realization that a race condition can be exploited to change the script while it is being processed.<ref>{{cite web |author1=Gilles |title=linux - Why is SUID disabled for shell scripts but not for binaries? |url=https://security.stackexchange.com/a/194174 |website=Information Security Stack Exchange}}</ref>}} 4) It is simpler to have alternate shells available; e.g. if you like the Berkeley csh there is no question about which shell is to interpret a file. 5) It will allow other interpreters to fit in more smoothly. To take advantage of this wonderful opportunity, put #! /bin/sh at the left margin of the first line of your shell scripts. Blanks after ! are OK. Use a complete pathname (no search is done). At the moment the whole line is restricted to 16 characters but this limit will be raised.
=== Unnamed shell script feature === The feature's creator didn't give it a name, however:<ref>{{cite web |last1=Richie |first1=Dennis |title=Dennis Ritchie and Hash-Bang |url=https://www.talisman.org/~erlkonig/documents/dennis-ritchie-and-hash-bang.shtml |publisher=Talisman.org |access-date=3 December 2020}}</ref> <syntaxhighlight lang="email"> From: "Ritchie, Dennis M (Dennis)** CTR **" <dmr@[redacted]> To: <[redacted]@talisman.org> Date: Thu, 19 Nov 2009 18:37:37 -0600 Subject: RE: What do -you- call your #!<something> line?
I can't recall that we ever gave it a proper name. It was pretty late that it went in--I think that I got the idea from someone at one of the UCB conferences on Berkeley Unix; I may have been one of the first to actually install it, but it was an idea that I got from elsewhere.
As for the name: probably something descriptive like "hash-bang" though this has a specifically British flavor, but in any event I don't recall particularly using a pet name for the construction. </syntaxhighlight>
Kernel support for interpreter directives spread to other versions of Unix, and one modern implementation can be seen in the Linux kernel source in ''fs/binfmt_script.c''.<ref>{{cite news | url=http://www.linuxjournal.com/article/2568 | title=Playing with Binary Formats | work=Linux Journal | date=31 December 1997 | first=Alessandro | last=Rubini | access-date=1 January 2015 }}</ref>
This mechanism allows scripts to be used in virtually any context normal compiled programs can be, including as full system programs, and even as interpreters of other scripts. As a caveat, though, some early versions of kernel support limited the length of the interpreter directive to roughly 32 characters (just 16 in its first implementation), would fail to split the interpreter name from any parameters in the directive, or had other quirks. Additionally, some modern systems allow the entire mechanism to be constrained or disabled for security purposes (for example, set-user-id support has been disabled for scripts on many systems).
Note that, even in systems with full kernel support for the ''#!'' magic number, some scripts lacking interpreter directives (although usually still requiring execute permission) are still runnable by virtue of the legacy script handling of the Bourne shell, still present in many of its modern descendants. Scripts are then interpreted by the user's default shell.
==See also== * binfmt_misc * CrunchBang Linux * File association * URI fragment
== Notes == {{notelist|30em}}
==References== {{Reflist|30em}}
==External links== * [https://www.in-ulm.de/~mascheck/various/shebang/ Details about the shebang mechanism on various Unix flavours] * [https://homepages.cwi.nl/~aeb/std/hashexclam.html #! - the Unix truth as far as I know it] (a more generic approach) * [https://foldoc.org/shebang FOLDOC shebang article]
Category:Unix