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 filedesiderata.txt exists:

$ cat desiderata.txtGo 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 range0..7; these digits are prefixed with digit0 to form an octal value.

If no argument is given, the input record separator is0x00.

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

Examples:

$ 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: Split Input Lines into Fields↑

Option-a, when given with either of options-n or-p, splits the string at$_ into an array of strings at$F:

$ 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:

-c: Check Syntax↑

Option-c specifies that the specified Ruby program should be checked for syntax, but not actually executed:

$ 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 totrue↑

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 isfalse; option-d sets it totrue:

$ 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"'FooBar

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:

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:

-h: Print Short Help Message↑

Option-h prints a short help message that includes single-hyphen options (e.g.-I), and largely omits double-hyphen options (e.g.,--version).

Arguments and additional options are ignored.

For a longer help message, use option--help.

-i: Set ARGF In-Place Mode↑

Option-i sets the ARGF in-place mode for the invoked Ruby program; seeARGF#inplace_mode=:

$ 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:

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:

-n: Run Program ingets Loop↑

Option-n runs your program in aKernel#gets loop:

whilegets# Your Ruby code.end

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

$ ruby -n -e 'puts $_' desiderata.txtGo 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:

-p:-n, with Printing↑

Option-p is like option-n, but also prints each line:

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

See also:

-r: Require Library↑

The argument to option-r specifies a library to be required before executing the Ruby program; the option may be given more than once:

$ ruby -e 'p defined?(JSON); p defined?(CSV)'nilnil$ 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:

More than one custom option may be given:

$ cat t.rbp [$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 withoption -e

-S: Search Directories inENV['PATH']↑

Option-S specifies that the Ruby interpreter is to search (if necessary) the directories whose paths are in the program’sPATH environment variable; the program is executed in the shell’s current working directory (not necessarily in the directory where the program is found).

This example uses adds path'tmp/' to thePATH environment variable:

$ export PATH=/tmp:$PATH$ echo "puts File.basename(Dir.pwd)" > /tmp/t.rb$ ruby -S t.rbruby

-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 awarning message by calling methodKernel#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:

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

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

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

Warning[:experimental]# => trueWarning[:deprecated]# => falseWarning[:performance]# => false

They may also be set:

Warning[:experimental] =falseWarning[:deprecated]   =trueWarning[:performance]  =true

You can suppress a category by prefixingno- 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:

Example:

$ cat t.txtLeading garbage.#!rubyputs File.basename(Dir.pwd)__END__Trailing garbage.$ ruby -x t.txtruby

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.txttmp$

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.

SeeThread::Backtrace.limit.

--copyright: Print Ruby Copyright↑

Option--copyright prints a copyright message:

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

--debug: Alias for-d↑

Option--debug is an alias foroption -d.

--disable: Disable Features↑

Option--disable specifies features to be disabled; the argument is a comma-separated list of the features to be disabled:

ruby --disable=gems,rubyopt t.rb

The supported features:

See alsooption –enable.

--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:

For other argument values and examples, seeOption –dump.

--enable: Enable Features↑

Option--enable specifies features to be enabled; the argument is a comma-separated list of the features to be enabled.

ruby --enable=gems,rubyopt t.rb

For the features, seeoption –disable.

--encoding: Alias for-E.↑

Option--encoding is an alias foroption -E.

--external-encoding: Set Default External Encoding↑

Option--external-encoding sets the default external encoding for the invoked Ruby program; for values ofencoding, seeEncoding: Names and Aliases.

$ 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 ofencoding, seeEncoding: Names and Aliases.

$ 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 theYJIT documentation.

--verbose: Set$VERBOSE↑

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

--version: Print Ruby Version↑

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