Ruby Command-Line Options

About the Examples

Some examples here use command-line option -e, which passes the Ruby code to be executed on the command line itself:

$ ruby -e 'puts "Hello, World."'

Some examples here assume that file desiderata.txt exists:

$ cat desiderata.txt
Go placidly amid the noise and the haste,
and remember what peace there may be in silence.
As far as possible, without surrender,
be on good terms with all persons.

Options

-0: Set $/ (Input Record Separator)

Option -0 defines the input record separator $/ for the invoked Ruby program.

The optional argument to the option must be octal digits, each in the range 0..7; these digits are prefixed with digit 0 to form an octal value.

If no argument is given, the input record separator is 0x00.

If an argument is given, it must immediately follow the option (no intervening whitespace or equal-sign character '='); argument values:

• 0: the input record separator is ''; see Line Separator Values[file.li>.html"code console">$ ruby -0 -e 'p $/' "\x00" ruby -00 -e 'p $/' "" $ ruby -012 -e 'p $/' "\n" $ ruby -015 -e 'p $/' "\r" $ ruby -0377 -e 'p $/' "\xFF" $ ruby -0400 -e 'p $/' nil

  See also:

  • -a[file.li>.html"code console">$ ruby -an -e 'p $F' desiderata.txt ["Go", "placidly", "amid", "the", "noise", "and", "the", "haste,"] ["and", "remember", "what", "peace", "there", "may", "be", "in", "silence."] ["As", "far", "as", "possible,", "without", "surrender,"] ["be", "on", "good", "terms", "with", "all", "persons."]

    For the splitting, the default record separator is $/, and the default field separator is $;.

    See also:

    • -0[file.li>.html"code console">$ ruby -e 'puts "Foo"' Foo $ ruby -c -e 'puts "Foo"' Syntax OK

      -C: Set Working Directory

      The argument to option -C specifies a working directory for the invoked Ruby program; does not change the working directory for the current process:

      $ basename `pwd`
      ruby
      $ ruby -C lib -e 'puts File.basename(Dir.pwd)'
      lib
      $ basename `pwd`
      ruby
      

      Whitespace between the option and its argument may be omitted.

      -d: Set $DEBUG to true

      Some code in (or called by) the Ruby program may include statements or blocks conditioned by the global variable $DEBUG (e.g., if $DEBUG); these commonly write to $stdout or $stderr.

      The default value for $DEBUG is false; option -d sets it to true:

      $ ruby -e 'p $DEBUG'
      false
      $ ruby -d -e 'p $DEBUG'
      true
      

      Option --debug is an alias for option -d.

      -e: Execute Given Ruby Code

      Option -e requires an argument, which is Ruby code to be executed; the option may be given more than once:

      $ ruby -e 'puts "Foo"' -e 'puts "Bar"'
      Foo
      Bar
      

      Whitespace between the option and its argument may be omitted.

      The command may include other options, but should not include arguments (which, if given, are ignored).

      -E: Set Default Encodings

      Option -E requires an argument, which specifies either the default external encoding, or both the default external and internal encodings for the invoked Ruby program:

      # No option -E.
      $ ruby -e 'p [Encoding::default_external, Encoding::default_internal]'
      [#<Encoding:UTF-8>, nil]
      # Option -E with default external encoding.
      $ ruby -E cesu-8 -e 'p [Encoding::default_external, Encoding::default_internal]'
      [#<Encoding:CESU-8>, nil]
      # Option -E with default external and internal encodings.
      $ ruby -E utf-8:cesu-8 -e 'p [Encoding::default_external, Encoding::default_internal]'
      [#<Encoding:UTF-8>, #<Encoding:CESU-8>]
      

      Whitespace between the option and its argument may be omitted.

      See also:

      • --external-encoding[options_md.html#label--external-encoding-3A+Set+Default+External+Encoding]: Set default external encoding.
      • --internal-encoding[options_md.html#label--internal-encoding-3A+Set+Default+Internal+Encoding]: Set default internal encoding.

      Option --encoding is an alias for option -E.

      -F: Set Input Field Separator

      Option -F, when given with option -a, specifies that its argument is to be the input field separator to be used for splitting:

      $ ruby -an -Fs -e 'p $F' desiderata.txt
      ["Go placidly amid the noi", "e and the ha", "te,\n"]
      ["and remember what peace there may be in ", "ilence.\n"]
      ["A", " far a", " po", "", "ible, without ", "urrender,\n"]
      ["be on good term", " with all per", "on", ".\n"]
      

      The argument may be a regular expression:

      $ ruby -an -F'[.,]\s*' -e 'p $F' desiderata.txt
      ["Go placidly amid the noise and the haste"]
      ["and remember what peace there may be in silence"]
      ["As far as possible", "without surrender"]
      ["be on good terms with all persons"]
      

      The argument must immediately follow the option (no intervening whitespace or equal-sign character '=').

      See also:

      • -0[file.li>.html"code console">$ ruby -e 'p ARGF.inplace_mode' nil $ ruby -i -e 'p ARGF.inplace_mode' "" $ ruby -i.bak -e 'p ARGF.inplace_mode' ".bak"

        -I: Add to $LOAD_PATH

        The argument to option -I specifies a directory to be added to the array in global variable $LOAD_PATH; the option may be given more than once:

        $ pushd /tmp
        $ ruby -e 'p $LOAD_PATH.size'
        8
        $ ruby -I my_lib -I some_lib -e 'p $LOAD_PATH.size'
        10
        $ ruby -I my_lib -I some_lib -e 'p $LOAD_PATH.take(2)'
        ["/tmp/my_lib", "/tmp/some_lib"]
        $ popd
        

        Whitespace between the option and its argument may be omitted.

        -l: Set Output Record Separator; Chop Lines

        Option -l, when given with option -n or -p, modifies line-ending processing by:

        • Setting global variable output record separator $\ to the current value of input record separator $/; this affects line-oriented output (such a the output from Kernel#puts).
        • Calling String#chop! on each line read.

        Without option -l (unchopped):

        $ ruby -n -e 'p $_' desiderata.txt
        "Go placidly amid the noise and the haste,\n"
        "and remember what peace there may be in silence.\n"
        "As far as possible, without surrender,\n"
        "be on good terms with all persons.\n"
        

        With option -l (chopped):

        $ ruby -ln -e 'p $_' desiderata.txt
        "Go placidly amid the noise and the haste,"
        "and remember what peace there may be in silence."
        "As far as possible, without surrender,"
        "be on good terms with all persons."
        

        See also:

        • -0[file.li>.html"code ruby">while gets # Your Ruby code. end

          Note that gets reads the next line and sets global variable $_ to the last read line:

          $ ruby -n -e 'puts $_' desiderata.txt
          Go placidly amid the noise and the haste,
          and remember what peace there may be in silence.
          As far as possible, without surrender,
          be on good terms with all persons.
          

          See also:

          • -0[file.li>.html"code console">$ ruby -p -e 'puts $_.size' desiderata.txt 42 Go placidly amid the noise and the haste, 49 and remember what peace there may be in silence. 39 As far as possible, without surrender, 35 be on good terms with all persons.

            See also:

            • -0[file.li>.html"code console">$ ruby -e 'p defined?(JSON); p defined?(CSV)' nil nil $ ruby -r CSV -r JSON -e 'p defined?(JSON); p defined?(CSV)' "constant" "constant"

              Whitespace between the option and its argument may be omitted.

              -s: Define Global Variable

              Option -s specifies that a "custom option" is to define a global variable in the invoked Ruby program:

              • The custom option must appear after the program name.
              • The custom option must begin with single hyphen (e.g., -foo), not two hyphens (e.g., --foo).
              • The name of the global variable is based on the option name: global variable $foo for custom option-foo.
              • The value of the global variable is the string option argument if given, true otherwise.

              More than one custom option may be given:

              $ cat t.rb
              p [$foo, $bar]
              $ ruby t.rb
              [nil, nil]
              $ ruby -s t.rb -foo=baz
              ["baz", nil]
              $ ruby -s t.rb -foo
              [true, nil]
              $ ruby -s t.rb -foo=baz -bar=bat
              ["baz", "bat"]
              

              The option may not be used with -e[file.p> .html"code console">$ export PATH=/tmp:$PATH $ echo "puts File.basename(Dir.pwd)" > /tmp/t.rb $ ruby -S t.rb ruby

              -v: Print Version; Set $VERBOSE

              Options -v prints the Ruby version and sets global variable $VERBOSE:

              $ ruby -e 'p $VERBOSE'
              false
              $ ruby -v -e 'p $VERBOSE'
              ruby 3.3.0 (2023-12-25 revision 5124f9ac75) [x64-mingw-ucrt]
              true
              

              -w: Synonym for -W1

              Option -w (lowercase letter) is equivalent to option -W1 (uppercase letter).

              -W: Set \Warning Policy

              Any Ruby code can create a warning message by calling method Kernel#warn; methods in the Ruby core and standard libraries can also create warning messages. Such a message may be printed on $stderr (or not, depending on certain settings).

              Option -W helps determine whether a particular warning message will be written, by setting the initial value of global variable $-W:

              • -W0: Sets $-W to 0 (silent; no warnings).
              • -W1: Sets $-W to 1 (moderate verbosity).
              • -W2: Sets $-W to 2 (high verbosity).
              • -W: Same as -W2 (high verbosity).
              • Option not given: Same as -W1 (moderate verbosity).

              The value of $-W, in turn, determines which warning messages (if any) are to be printed to $stdout (see Kernel#warn):

              $ ruby -W1 -e 'p $foo'
              nil
              $ ruby -W2 -e 'p $foo'
              -e:1: warning: global variable '$foo' not initialized
              nil
              

              Ruby code may also define warnings for certain categories; these are the default settings for the defined categories:

              Warning[:experimental] # => true
              Warning[:deprecated]   # => false
              Warning[:performance]  # => false

              They may also be set:

              Warning[:experimental] = false
              Warning[:deprecated]   = true
              Warning[:performance]  = true

              You can suppress a category by prefixing no- to the category name:

              $ ruby -W:no-experimental -e 'p IO::Buffer.new'
              #<IO::Buffer>
              

              -x: Execute Ruby Code Found in Text

              Option -x executes a Ruby program whose code is embedded in other, non-code, text:

              The ruby code:

              • Begins after the first line beginning with '#! and containing string 'ruby'.

              • Ends before any one of:

                • End-of-file.
                • A line consisting of '__END__',
                • Character Ctrl-D or Ctrl-Z.

              Example:

              $ cat t.txt
              Leading garbage.
              #!ruby
              puts File.basename(Dir.pwd)
              __END__
              Trailing garbage.
              
              $ ruby -x t.txt
              ruby
              

              The optional argument specifies the directory where the text file is to be found; the Ruby code is executed in that directory:

              $ cp t.txt /tmp/
              $ ruby -x/tmp t.txt
              tmp
              $
              
              

              If an argument is given, it must immediately follow the option (no intervening whitespace or equal-sign character '=').

              --backtrace-limit: Set Backtrace Limit

              Option --backtrace-limit sets a limit on the number of entries to be displayed in a backtrace.

              See Thread::Backtrace.limit.

              --copyright: Print Ruby Copyright

              Option --copyright prints a copyright message:

              $ ruby --copyright
              ruby - Copyright (C) 1993-2024 Yukihiro Matsumoto
              

              --debug: Alias for -d

              Option --debug is an alias for -d[file.p> .html"code sh">ruby --disable=gems,rubyopt t.rb

              The supported features:

              • gems: Rubygems (default: enabled).
              • did_you_mean: did_you_mean (default: enabled).
              • rubyopt: RUBYOPT environment variable (default: enabled).
              • frozen-string-literal: Freeze all string literals (default: disabled).
              • jit: JIT compiler (default: disabled).

              See also --enable[options_md.html#label--enable-3A+Enable+Features].

              --dump: Dump Items

              Option --dump specifies items to be dumped; the argument is a comma-separated list of the items.

              Some of the argument values cause the command to behave as if a different option was given:

              • --dump=copyright: Same as --copyright[options_md.html#label--copyright-3A+Print+Ruby+Copyright].
              • --dump=help: Same as --help[options_md.html#label--help-3A+Print+Help+Message].
              • --dump=syntax: Same as -c[file.li>.html"code sh">ruby --enable=gems,rubyopt t.rb

                For the features, see --disable[options_md.html#label--disable-3A+Disable+Features].

                --encoding: Alias for -E.

                Option --encoding is an alias for -E[file.p> .html"code console">$ ruby -e 'puts Encoding::default_external' UTF-8 $ ruby --external-encoding=cesu-8 -e 'puts Encoding::default_external' CESU-8

                --help: Print Help Message

                Option --help prints a long help message.

                Arguments and additional options are ignored.

                For a shorter help message, use option -h.

                --internal-encoding: Set Default Internal \Encoding

                Option --internal-encoding sets the default internal encoding for the invoked Ruby program; for values of encoding, see Names and Aliases[file.p>

                $ ruby -e 'puts Encoding::default_internal.nil?'
                true
                $ ruby --internal-encoding=cesu-8 -e 'puts Encoding::default_internal'
                CESU-8
                

                --jit

                Option --jit is an alias for option --yjit, which enables YJIT; see additional YJIT options in the YJIT documentation.

                --verbose: Set $VERBOSE

                Option --verbose sets global variable $VERBOSE to true and disables input from $stdin.

                --version: Print Ruby Version

                Option --version prints the version of the Ruby interpreter, then exits.