← Full reference

getopts

Parsing a script's short options (-v, -o file) — the option string, OPTARG, OPTIND, silent mode, getopt vs getopts

getopts is a bash builtin for parsing options in a script or function: -v, -o file, combined -vo file. You call it in a while loop: each call extracts one option, puts its letter into a variable and the option's argument into OPTARG. getopts can't handle long options (--verbose) — for those there's the external getopt utility or manual parsing with case. Help — help getopts.

Syntax

while getopts 'optstring' name; do
    case $name in
        …
    esac
done
shift $((OPTIND - 1))     # drop the parsed options, leaving the positional arguments

Option string

NotationMeaning
vhoptions -v and -h without arguments
o:option -o with a required argument: -o file or -ofile
:vo:a colon at the start — silent mode: errors aren't printed, your case handles them

Variables

VariableWhat it holds
name (from getopts … name)the letter of the option found; ? — unknown option; : — missing argument (silent mode only)
OPTARGthe option's argument; in silent mode on error — the offending letter itself
OPTINDindex of the next argument to parse; 1 at the start of the script
OPTERR=0disable error messages without enabling silent mode

Errors: normal and silent mode

SituationNormal mode (vo:)Silent mode (:vo:)
unknown option -xprints illegal option -- x, name=?, OPTARG unsetsilent, name=?, OPTARG=x
-o without an argumentprints option requires an argument -- o, name=?silent, name=:, OPTARG=o

getopts returns code 1 and the loop ends when the options run out: it hit the first argument not starting with -, a standalone --, or the end of the arguments.

Examples

#!/bin/bash
# a script with options: -v, -o file, -h
usage() { echo "usage: $0 [-v] [-o file] argument…" >&2; }

verbose=0
out=/dev/stdout
while getopts ':vo:h' opt; do
    case $opt in
        v)  verbose=1 ;;
        o)  out=$OPTARG ;;
        h)  usage; exit 0 ;;
        :)  echo "option -$OPTARG requires an argument" >&2; usage; exit 2 ;;
        \?) echo "unknown option -$OPTARG" >&2; usage; exit 2 ;;
    esac
done
shift $((OPTIND - 1))

(( $# > 0 )) || { usage; exit 2; }
echo "verbose=$verbose out=$out arguments: $*"
# how this script parses different calls
./script.sh -v -o res.txt a b   # verbose=1 out=res.txt arguments: a b
./script.sh -vores.txt a        # same: options combined, argument attached
./script.sh -- -v               # after -- everything is an argument: arguments: -v
./script.sh a -v                # parsing stops at a: -v is a regular argument

# a repeatable option: collect the values into an array
tags=()
while getopts 't:' opt; do
    [[ $opt == t ]] && tags+=("$OPTARG")
done

# getopts in a function: reset OPTIND, otherwise the second call parses nothing
f() {
    local OPTIND opt
    while getopts 'a' opt; do echo "option $opt"; done
}
f -a; f -a

# long options — via the external getopt (util-linux)
args=$(getopt -o vo: -l verbose,output: -- "$@") || exit 2
eval set -- "$args"
while true; do
    case $1 in
        -v|--verbose) verbose=1; shift ;;
        -o|--output)  out=$2; shift 2 ;;
        --) shift; break ;;
    esac
done

getopts or getopt

getopts (builtin)getopt (util-linux)
long options --namenoyes: -l name,output:
options after arguments (file -v)no, parsing stopsyes, moves options to the front
portabilityany POSIX shellLinux with util-linux only
how to usea while getopts loopeval set -- "$(getopt …)", then a loop over $1

Pitfalls

  • Forgotten shift $((OPTIND - 1)). Without it $1 still points to the first option, not the first positional argument.
  • getopts doesn't understand long options. It parses --verbose as a set of letters -, v, e, r, … and reports an error for each unknown one. Need long options — use getopt.
  • The next word becomes the option's argument, even if it looks like an option. -o -v gives OPTARG=-v, and -v as a separate option doesn't take effect.
  • Parsing stops at the first positional argument. In script.sh file -v the -v option isn't recognized. Put options before arguments.
  • OPTIND doesn't reset on its own. In a function called several times, declare local OPTIND, otherwise the second call won't see the options.
  • ? in case must be escaped: \?) or '?'). Without that, ?) is the pattern "any single character" and matches every option.
  • Check getopt's exit code before eval: args=$(getopt …) || exit 2. On an unknown option getopt prints an error and returns 1.

See also

functions · conditions-loops · variables · exit-codes