man pages section 1: User Commands

Exit Print View

Updated: July 2014

zsh (1)


zsh - the Z shell


Please see following description for synopsis


User Commands                                              ZSH(1)

     zsh - the Z shell

     Because  zsh contains many features, the zsh manual has been
     split into a number of sections:

     zsh          Zsh overview (this section)
     zshroadmap   Informal introduction to the manual
     zshmisc      Anything not fitting into the other sections
     zshexpn      Zsh command and parameter expansion
     zshparam     Zsh parameters
     zshoptions   Zsh options
     zshbuiltins  Zsh built-in functions
     zshzle       Zsh command line editing
     zshcompwid   Zsh completion widgets
     zshcompsys   Zsh completion system
     zshcompctl   Zsh completion control
     zshmodules   Zsh loadable modules
     zshcalsys    Zsh built-in calendar functions
     zshtcpsys    Zsh built-in TCP functions
     zshzftpsys   Zsh built-in FTP client
     zshcontrib   Additional zsh functions and utilities
     zshall       Meta-man page containing all of the above

     Zsh is a UNIX  command  interpreter  (shell)  usable  as  an
     interactive  login  shell and as a shell script command pro-
     cessor.  Of the standard shells, zsh most closely  resembles
     ksh  but  includes  many enhancements.  Zsh has command line
     editing, builtin spelling correction,  programmable  command
     completion,  shell  functions  (with autoloading), a history
     mechanism, and a host of other features.

     Zsh was originally written  by  Paul  Falstad  <>.
     Zsh  is  now  maintained  by  the members of the zsh-workers
     mailing list <>.  The development is cur-
     rently  coordinated  by Peter Stephenson <>.  The
     coordinator can be contacted at  <>,  but
     matters  relating  to  the  code  should generally go to the
     mailing list.

     Zsh is available from the  following  anonymous  FTP  sites.
     These  mirror  sites  are  kept  frequently up to date.  The
     sites  marked  with  (H)  may  be  mirroring
     instead of the primary site.

     Primary site

zsh 5.0.5          Last change: January 5, 2014                 1

User Commands                                              ZSH(1)



          The  up-to-date  source code is available via anonymous
          CVS  and  Git  from  Sourceforge.   See  http://source-
  for  details.   A  summary  of
          instructions for the CVS and Git archives can be  found

     Zsh has 3 mailing lists:

          Announcements  about  releases,  major  changes  in the
          shell and the monthly posting of the Zsh FAQ.   (moder-

          User discussions.

          Hacking, development, bug reports and patches.

     To  subscribe  or  unsubscribe,  send mail to the associated
     administrative address for the mailing list.


     NESTED.   All  submissions to zsh-announce are automatically
     forwarded to zsh-users.  All submissions  to  zsh-users  are
     automatically forwarded to zsh-workers.

     If you have problems subscribing/unsubscribing to any of the
     mailing lists, send mail to <>.  The mail-
     ing    lists    are    maintained    by   Karsten   Thygesen

     The mailing lists are archived; the archives can be accessed
     via  the  administrative  addresses  listed above.  There is
     also  a  hypertext  archive,  maintained   by   Geoff   Wing

zsh 5.0.5          Last change: January 5, 2014                 2

User Commands                                              ZSH(1)

     <>, available at

     Zsh  has  a  list of Frequently Asked Questions (FAQ), main-
     tained by Peter Stephenson <>.  It  is  regularly
     posted to the newsgroup and the zsh-announce
     mailing list.  The latest version can be found at any of the
     Zsh  FTP  sites, or at  The contact
     address for FAQ-related matters is <>.

     Zsh has a web page which is located at
     This  is maintained by Karsten Thygesen <>, of
     SunSITE Denmark.  The contact address for  web-related  mat-
     ters is <>.

     A  userguide is currently in preparation.  It is intended to
     complement the manual, with explanations and hints on issues
     where  the manual can be cabbalistic, hierographic, or down-
     right mystifying (for example, the word `hierographic'  does
     not  exist).   It  can  be  viewed  in  its current state at  At the time of  writing,
     chapters  dealing  with startup files and their contents and
     the new completion system were essentially complete.

     A `wiki' website for zsh has been created at http://www.zsh-   This  is a site which can be added to and modi-
     fied directly by users without any special permission.   You
     can add your own zsh tips and configurations.

     The  following  flags  are  interpreted  by  the  shell when
     invoked to determine where  the  shell  will  read  commands

     -c   Take the first argument as a command to execute, rather
          than reading commands from a script or standard  input.
          If  any  further  arguments are given, the first one is
          assigned to $0, rather than being used as a  positional

     -i   Force shell to be interactive.  It is still possible to
          specify a script to execute.

     -s   Force shell to read commands from the  standard  input.
          If the -s flag is not present and an argument is given,
          the first argument is taken to be  the  pathname  of  a
          script to execute.

zsh 5.0.5          Last change: January 5, 2014                 3

User Commands                                              ZSH(1)

     If  there  are any remaining arguments after option process-
     ing, and neither of the options -c or -s was  supplied,  the
     first  argument  is  taken as the file name of a script con-
     taining shell  commands  to  be  executed.   If  the  option
     PATH_SCRIPT  is  set,  and  the file name does not contain a
     directory path (i.e. there is no `/' in the name), first the
     current  directory  and  then  the command path given by the
     variable PATH are searched for the script.  If the option is
     not set or the file name contains a `/' it is used directly.

     After the first one or two arguments have been  appropriated
     as  described above, the remaining arguments are assigned to
     the positional parameters.

     For further options, which are common to invocation and  the
     set builtin, see zshoptions(1).

     Options  may  be  specified by name using the -o option.  -o
     acts like a single-letter  option,  but  takes  a  following
     string as the option name.  For example,

          zsh -x -o shwordsplit scr

     runs the script scr, setting the XTRACE option by the corre-
     sponding letter `-x' and the SH_WORD_SPLIT option  by  name.
     Options may be turned off by name by using +o instead of -o.
     -o can be stacked up with preceding  single-letter  options,
     so  for  example  `-xo  shwordsplit'  or `-xoshwordsplit' is
     equivalent to `-x -o shwordsplit'.

     Options may also be specified by name  in  GNU  long  option
     style,  `--option-name'.   When this is done, `-' characters
     in the option name are permitted: they are  translated  into
     `_',    and   thus   ignored.    So,   for   example,   `zsh
     --sh-word-split' invokes zsh with the  SH_WORD_SPLIT  option
     turned  on.   Like  other  option  syntaxes,  options can be
     turned off by replacing the initial `-'  with  a  `+';  thus
     `+-sh-word-split'  is  equivalent  to  `--no-sh-word-split'.
     Unlike other option syntaxes, GNU-style long options  cannot
     be   stacked   with   any  other  options,  so  for  example
     `-x-shwordsplit' is an error, rather than being treated like
     `-x --shwordsplit'.

     The  special  GNU-style  option  `--version'  is handled; it
     sends to standard output the  shell's  version  information,
     then exits successfully.  `--help' is also handled; it sends
     to standard output a list of options that can be  used  when
     invoking the shell, then exits successfully.

     Option  processing may be finished, allowing following argu-
     ments that start with `-' or `+' to  be  treated  as  normal
     arguments,  in two ways.  Firstly, a lone `-' (or `+') as an

zsh 5.0.5          Last change: January 5, 2014                 4

User Commands                                              ZSH(1)

     argument by itself ends option processing.  Secondly, a spe-
     cial  option  `--'  (or `+-'), which may be specified on its
     own (which is the standard POSIX usage) or  may  be  stacked
     with  preceding options (so `-x-' is equivalent to `-x --').
     Options are not permitted  to  be  stacked  after  `--'  (so
     `-x-f' is an error), but note the GNU-style option form dis-
     cussed above, where `--shwordsplit' is  permitted  and  does
     not end option processing.

     Except  when  the sh/ksh emulation single-letter options are
     in effect, the option `-b' (or `+b') ends option processing.
     `-b' is like `--', except that further single-letter options
     can be stacked after the `-b' and will take effect  as  nor-

     Zsh  tries  to emulate sh or ksh when it is invoked as sh or
     ksh respectively; more precisely, it looks at the first let-
     ter  of the name by which it was invoked, excluding any ini-
     tial `r' (assumed to stand for `restricted'), and if that is
     `s'  or  `k'  it  will  emulate  sh or ksh.  Furthermore, if
     invoked as su (which happens on  certain  systems  when  the
     shell  is executed by the su command), the shell will try to
     find an alternative name from the SHELL environment variable
     and perform emulation based on that.

     In  sh  and ksh compatibility modes the following parameters
     are not special and not  initialized  by  the  shell:  ARGC,
     argv,  cdpath, fignore, fpath, HISTCHARS, mailpath, MANPATH,
     manpath, path, prompt, PROMPT,  PROMPT2,  PROMPT3,  PROMPT4,
     psvar, status, watch.

     The  usual  zsh  startup/shutdown  scripts are not executed.
     Login shells source /etc/profile followed by $HOME/.profile.
     If  the  ENV environment variable is set on invocation, $ENV
     is sourced after the profile scripts.  The value of  ENV  is
     subjected  to parameter expansion, command substitution, and
     arithmetic expansion before being interpreted as a pathname.
     Note  that  the PRIVILEGED option also affects the execution
     of startup files.

     The following options are set if the shell is invoked as  sh
     TERS,  SH_WORD_SPLIT.    Additionally   the   BSD_ECHO   and
     IGNORE_BRACES  options  are  set  if  zsh  is invoked as sh.
     PROMPT_SUBST  and  SINGLE_LINE_ZLE options are set if zsh is
     invoked as ksh.

zsh 5.0.5          Last change: January 5, 2014                 5

User Commands                                              ZSH(1)

     When the basename of the command used to invoke  zsh  starts
     with  the letter `r' or the `-r' command line option is sup-
     plied at invocation, the shell becomes  restricted.   Emula-
     tion  mode is determined after stripping the letter `r' from
     the  invocation  name.   The  following  are   disabled   in
     restricted mode:

     o    changing directories with the cd builtin

     o    changing or unsetting the PATH, path, MODULE_PATH, mod-
          ule_path, SHELL, HISTFILE, HISTSIZE,  GID,  EGID,  UID,
          LD_PRELOAD and  LD_AOUT_PRELOAD parameters

     o    specifying command names containing /

     o    specifying command pathnames using hash

     o    redirecting output to files

     o    using the exec builtin command  to  replace  the  shell
          with another command

     o    using  jobs -Z to overwrite the shell process' argument
          and environment space

     o    using the  ARGV0  parameter  to  override  argv[0]  for
          external commands

     o    turning  off  restricted  mode  with set +r or unsetopt

     These restrictions are enforced after processing the startup
     files.   The  startup files should set up PATH to point to a
     directory of commands which can be  safely  invoked  in  the
     restricted  environment.  They may also add further restric-
     tions by disabling selected builtins.

     Restricted mode can also be activated any  time  by  setting
     the  RESTRICTED  option.   This  immediately enables all the
     restrictions described above even if the shell still has not
     processed all startup files.

     Commands  are  first  read  from /etc/zshenv; this cannot be
     overridden.  Subsequent behaviour is modified by the RCS and
     GLOBAL_RCS  options;  the  former affects all startup files,
     while the second only affects global  startup  files  (those
     shown  here  with an path starting with a /).  If one of the
     options is  unset  at  any  point,  any  subsequent  startup
     file(s)  of  the corresponding type will not be read.  It is

zsh 5.0.5          Last change: January 5, 2014                 6

User Commands                                              ZSH(1)

     also  possible  for  a  file  in   $ZDOTDIR   to   re-enable
     GLOBAL_RCS. Both RCS and GLOBAL_RCS are set by default.

     Commands  are then read from $ZDOTDIR/.zshenv.  If the shell
     is a login shell, commands are read from  /etc/zprofile  and
     then $ZDOTDIR/.zprofile.  Then, if the shell is interactive,
     commands are read from /etc/zshrc and then  $ZDOTDIR/.zshrc.
     Finally,  if  the  shell  is  a login shell, /etc/zlogin and
     $ZDOTDIR/.zlogin are read.

     When a login shell exits, the  files  $ZDOTDIR/.zlogout  and
     then  /etc/zlogout  are  read.   This happens with either an
     explicit exit  via  the  exit  or  logout  commands,  or  an
     implicit  exit  by  reading  end-of-file  from the terminal.
     However, if the shell terminates  due  to  exec'ing  another
     process,  the  logout  files  are  not read.  These are also
     affected by the RCS and GLOBAL_RCS options.  Note also  that
     the  RCS option affects the saving of history files, i.e. if
     RCS is unset when the shell exits, no history file  will  be

     If  ZDOTDIR  is  unset,  HOME is used instead.  Files listed
     above as being in /etc may be in another directory,  depend-
     ing on the installation.

     As /etc/zshenv is run for all instances of zsh, it is impor-
     tant that it be kept as small as possible.   In  particular,
     it  is  a good idea to put code that does not need to be run
     for every single shell behind a test of the form `if  [[  -o
     rcs  ]];  then ...' so that it will not be executed when zsh
     is invoked with the `-f' option.

     Any of these files may be  pre-compiled  with  the  zcompile
     builtin  command  (see  zshbuiltins(1)).  If a compiled file
     exists (named for the original file plus the .zwc extension)
     and  it  is  newer than the original file, the compiled file
     will be used instead.

     ${TMPPREFIX}*   (default is /tmp/zsh*)
     /etc/zlogout    (installation-specific - /etc is the

zsh 5.0.5          Last change: January 5, 2014                 7

User Commands                                              ZSH(1)

     See   attributes(5)   for   descriptions  of  the  following

     |Availability   | shell/zsh        |
     |Stability      | Volatile         |
     sh(1),  csh(1),  tcsh(1),  rc(1),  bash(1),   ksh(1),   zsh-
     builtins(1),  zshcompwid(1),  zshcompsys(1),  zshcompctl(1),
     zshexpn(1), zshmisc(1), zshmodules(1),  zshoptions(1),  zsh-
     param(1), zshzle(1)

     IEEE  Standard for information Technology - Portable Operat-
     ing System Interface (POSIX) - Part 2: Shell and  Utilities,
     IEEE Inc, 1993, ISBN 1-55937-255-9.

     This   software   was   built   from   source  available  at   The   original
     community   source   was   downloaded   from    http://down-

     Further  information about this software can be found on the
     open source community website at

zsh 5.0.5          Last change: January 5, 2014                 8