Ruby Command Line and Environment

Reading the whole program before running it matters for a point the older books get wrong. A Ruby file is not "parsed and executed line by line": the complete file is parsed first (by Prism since 3.4), compiled to YARV bytecode, and only then run. That is why a syntax error anywhere in a file stops the program before its first line runs, and why ruby -c can check a file without executing it. The parser and the bytecode are shown later in this page with --dump.

When the file does not exist, or the code does not compile, the interpreter exits with status 1:

Source: Ruby 4.0 documentation: Ruby Command-Line Options

The exit status is the program’s result for the shell: 0 for success, the number given to exit (ruby -e 'exit 3' ends with status 3), and 1 for an uncaught exception, a syntax error or a missing file. Exit statuses are covered in Command-Line Programs.

ruby -v prints the version and sets $VERBOSE (see below); ruby --version prints the same line and exits, and --copyright prints the copyright line. The line is built from constants that a program can read too:

Source: Ruby 4.0 documentation: Ruby Command-Line Options

The tokens at the end of the version line describe the build: +PRISM (the default parser since Ruby 3.4) appears unless the parser was changed, +YJIT appears once YJIT is enabled, and the bracketed part is the platform. RUBY_ENGINE distinguishes CRuby ("ruby") from JRuby and TruffleRuby, and RbConfig::CONFIG (require "rbconfig") exposes the build configuration, for example RbConfig.ruby for the path of the running interpreter, which is what a program should use to start another Ruby of the same version.

The following script prints how the interpreter that runs it was started. It is used below to show the effect of options and environment variables:

Source: Ruby 4.0 documentation: Warning

Run it plainly, then with several options at once (Warning.categories is Ruby 3.4+):

Source: Ruby 4.0 documentation: Ruby Command-Line Options

The second run shows four independent effects: -w turned $VERBOSE on and enabled the deprecated warning category, --yjit added +YJIT and made RubyVM::YJIT.enabled? true, -E replaced the two default encodings, and -I added a ninth $LOAD_PATH entry. The load-path count depends on the installation.

-T (taint checking) and $SAFE were removed with the taint system: on Ruby 3.2, 3.3, 3.4 and 4.0, ruby -T -e 1 fails with invalid option -T. --rjit was removed in 4.0 (invalid option --rjit), and MJIT before it. The manual page installed with 4.0.7 still mentions -T, and also describes -w as "level 1" like the options guide does; the observed behaviour of both is described in the sections below, and the observed behaviour is what this page documents.

Source: Ruby 4.0 documentation: Ruby Command-Line Options

Shell quoting is the usual trap: wrap the code in single quotes so that $_, #{...} and ! reach Ruby untouched. A program that must contain a single quote is better put in a file, or written with %q and %Q literals.

A program can be piped in. With no file, ruby reads standard input to the end and then runs it; - makes that explicit and lets arguments follow:

Source: Ruby 4.0 documentation: Ruby Command-Line Options

--verbose and -v without a program do not read standard input: they print (or set) and exit, so echo 'p 1' | ruby -v shows only the version. -w and -W do read it.

ruby -c file.rb parses without running. Adding -w includes the parse-time warnings, which is why this page’s examples are all checked with ruby -wc:

Source: Ruby 4.0 documentation: Ruby Command-Line Options

The warning appears at parse time, so -wc shows it without executing anything. ruby -wc is a cheap CI step and an editor on-save check; static analysers that go much further are in Style, Linting and Static Analysis.

-C changes directory before the program (and relative -I paths) is resolved, without changing the caller’s shell:

Source: Ruby 4.0 documentation: Ruby Command-Line Options

where where.rb prints Dir.pwd.split("/").last. In the first run the program’s working directory is cdir; in the second it is the directory the shell was in (called w here).

-x skips leading text up to a #! line that mentions ruby. It is for programs shipped inside a mail, a shell script or a document:

Source: Ruby 4.0 documentation: Ruby Command-Line Options

A script is made executable with a shebang line and the executable bit. The portable form uses env so that the first ruby on the PATH is chosen, which is what version managers (mise, rbenv, asdf, chruby) rely on:

Source: Ruby 4.0 documentation: Ruby Command-Line Options

Source: Ruby 4.0 documentation: Ruby Command-Line Options

-S with no match fails with No such file or directory — shelf-tool (LoadError). Directories in RUBYPATH are searched before those in PATH.

Options can also be written on the shebang line itself: ruby scans the #! line of a script for options when the line contains the word ruby, so a file that starts with #!/usr/bin/env ruby -w run through ruby file.rb or ./file.rb has warnings on (verified on macOS). Operating systems differ in how a shebang with several words is split before it reaches env; the portable spelling for passing options is #!/usr/bin/env -S ruby -w with GNU and BSD env -S. Prefer putting options a program needs into the program (Warning[:deprecated] = true) or into RUBYOPT, rather than into the shebang.

With -s, switches written after the program name and before any argument are removed from ARGV and turned into global variables: -term=Picnic sets $term to "Picnic", a bare -all sets $all to true, and dashes inside the name become underscores (-foo-bar=1 sets $foo_bar). This is a feature for tiny scripts; anything larger should use OptionParser (see Command-Line Programs) because -s has no validation, no help and no --long options.

Source: Ruby 4.0 documentation: Ruby Command-Line Options

The rubocop:disable comment is deliberate: reading a user-defined global variable is exactly what the example is about, and the default Style/GlobalVars cop forbids it.

Source: Ruby 4.0 documentation: Ruby Command-Line Options

Three of these four runs leave the variables unset: -- ends switch parsing, and without -s the word is just an argument. A switch placed after the first ordinary argument is not parsed either (ruby -s s2.rb file -a leaves $a unset).

ruby -run -e name loads the standard un library and runs one of its small file commands, a cross-platform replacement for cp, mv, rm, mkdir, touch, chmod, install, ln, rmdir, wait_writable, mkmf, colorize, httpd and help. It is -r plus un, which is why the odd spelling works: -r followed by un.

Source: Ruby 4.0 documentation: Ruby Command-Line Options

The -- separates the ruby options from those of the un command. httpd needs the webrick gem, which has not been part of Ruby since 3.0, so without that gem the command stops with a message that webrick is not found.

Source: Ruby 4.0 documentation: Ruby Command-Line Options

The last command uses a flip-flop: a range literal used as a condition is compared with the line number $., so 2..3 is true for lines 2 and 3. The flip-flop is explained with the conditional forms in Control Expressions. $_ keeps the newline unless -l is given, which is why the first command prints no blank lines but p $_ shows "...\n".

Source: Ruby 4.0 documentation: Ruby Command-Line Options

The cluster -lane is four options in one word (-l -a -n -e), with -e last because it takes the program as its argument. Note the total: the header’s "year".to_i is 0, so it does not disturb the sum, which is also why -F, is only a sketch of CSV reading. Fields with quoted commas need the csv library (see Serialization: JSON, YAML, CSV and Marshal). In the last command -l was not given, so the final field still carries its newline.

-p is for filters that change each line. A next inside a -p program skips the print for that line, which makes next a delete:

Source: Ruby 4.0 documentation: Ruby Command-Line Options

The second command drops the header line (no print) and converts the commas of the others to tabs.

-i makes the output replace the input file. With an extension the original is kept; without, it is gone:

Source: Ruby 4.0 documentation: ARGF

Always give -i an extension while experimenting (ruby -i -pe ... has no way back), and try the command without -i first. -i sets ARGF.inplace_mode, which is nil without the option, "" for a bare -i and the extension otherwise.

The input record separator $/ decides what gets (and therefore -n) calls a line:

Source: Ruby 4.0 documentation: Ruby Command-Line Options

-0777 reads each file whole (slurp mode); -00 splits on blank lines (paragraph mode); -0073 uses the semicolon, character code 073 in octal. A trap for the careful: String#lines and String#each_line also default to $/. After -0777, $_.lines is a one-element array and $_.lines("\n") is the way to get the four lines; in paragraph mode the same happens with $/ set to the empty string.

ARGF is the object behind gets and $<; a one-liner without -n can use it directly, which also gives access to several files at once:

Source: Ruby 4.0 documentation: ARGF

Both lines are short enough to be useful in a shell history and long enough that a script file is the better home once it grows; ARGF, $stdin and the other process-level streams are developed in Command-Line Programs and IO, Files and Directories.

Ruby has three warning levels, stored in $VERBOSE (and as a number in $-W). The options set them at startup:

The table is what Ruby 4.0.7 does when asked, using ruby -W1 -e 'p [$VERBOSE, $-W]' and so on (for -w it prints [true, 2], for -W1 [false, 1]); the same results come out of 3.2, 3.3 and 3.4. The options guide and ruby --help call -w a "synonym for -W1`", which does not match: `-w is the verbose level, and -W1 is the default. -d additionally sets $DEBUG.

Source: Ruby 4.0 documentation: Ruby Command-Line Options

(The [true, 2, false] of -v is the last line of its output: -v prints the version line first.) Code can read and change $VERBOSE at runtime ($VERBOSE = nil silences warnings inside a block of code, restored in an ensure), but a library should not change a global that belongs to its caller. $DEBUG makes the interpreter print each exception as it is raised, including the ones raised and rescued inside RubyGems during startup (a line starting Exception 'LoadError' at and ending with cannot load such file -- rubygems/defaults/operating_system), which is noisy but useful when something rescues too much.

Individual categories can be switched with -W:name and -W:no-name, and from code with Warning[:name] = true. Warning.categories lists them (Ruby 3.4+; on 3.3 the call is a NoMethodError):

Source: Ruby 4.0 documentation: Warning

An unknown category is itself a warning (ruby: warning: unknown warning category: 'foo'). -W0 turns every category off, but a later -W:performance turns one back on; the order of options matters.

Kernel#warn takes a category: keyword, so a library can emit a message that follows the user’s choice, and an uplevel: keyword to point at the caller’s line:

Source: Ruby 4.0 documentation: Kernel#warn

Source: Ruby 4.0 documentation: Warning

In the third run -W0 silenced both the plain warn and the categories, but the program’s own puts is, of course, unaffected. Libraries that deprecate an API should call warn ..., category: :deprecated so that users see the notice when they run with -w or -W:deprecated, and do not see it otherwise.

Two categories matter for the migration advice in this section:

--backtrace-limit=n trims long backtraces, which is the setting for noisy frameworks; the omitted part is summarised:

Source: Ruby 4.0 documentation: Thread::Backtrace

The format of the lines ('Object#c' with a single quote and the class name) is the 3.4 style; older books show a backtick before the method name and no class. The error message formats are in Exceptions and Error Handling.

Three helper gems that ship with Ruby print better diagnostics, and each can be disabled with --disable:

Source: Ruby 4.0 documentation: Ruby Command-Line Options

error_highlight underlines the call that failed (it needs a source file, so -e code gets no marker), did_you_mean suggests names, and syntax_suggest points at the unbalanced end when a file does not parse:

Source: Ruby 4.0 documentation: Ruby Command-Line Options

The interactive debugger and the debug gem are in IRB and Debugging, and TracePoint and tracing in Reflection, Introspection and Tracing.

--enable=frozen-string-literal (or --enable-frozen-string-literal) freezes every string literal of the program, the switch that lets a team try the future default:

Source: Ruby 4.0 documentation: Ruby Command-Line Options

--debug-frozen-string-literal records where each literal was created, so that the error message of a FrozenError (or the chilled-string warning above) names the creation site. The magic comment of a file wins over the switch, in both directions: a file with # frozen_string_literal: false stays modifiable under --enable-frozen-string-literal, and one with # frozen_string_literal: true stays frozen under --disable-frozen-string-literal.

Source: Ruby 4.0 documentation: Comments (magic comments)

Source: Ruby 4.0 documentation: Comments (magic comments)

where frozen_probe2.rb is the same file with true. The strings page (Strings) shows the idioms for building strings without relying on mutating a literal. Frozen literals are still not the default in 4.0, even though some books say that 3.4 made them the default: 3.4 added the chilled-string warning, not the freeze.

The default external encoding comes from the locale (LANG, LC_ALL, LC_CTYPE) and the default internal encoding is nil. -E external:internal overrides them, -U sets the internal one to UTF-8:

Source: Ruby 4.0 documentation: Encoding

__ENCODING__ is the source encoding, which is UTF-8 unless a # encoding: magic comment (or the legacy -K) says otherwise; it does not follow the locale. A container or cron job with LANG unset starts with US-ASCII as the default external encoding, which is a classic source of Encoding::UndefinedConversionError when reading UTF-8 files; setting LANG=C.UTF-8 or passing -E UTF-8 fixes it. More in Encodings and Unicode.

--dump=item prints an internal form and, for the dump items, does not run the program. The items are insns (YARV bytecode), parsetree (the AST), yydebug (the parse.y parse trace); version, copyright, usage, help and syntax behave like --version, --copyright, -h, --help and -c. Modifiers: -optimize (compile without optimisation), and +error-tolerant (affects the yydebug and parsetree items) and +comment (adds comments to the AST of parse.y). Several items are separated by commas.

Source: Ruby 4.0 documentation: Option --dump

Reading the first listing: 1 + 2 was compiled to the specialised instruction opt_plus, and with -optimize it becomes a generic send of +. The putchilledstring in the last listing is the chilled literal from the previous section. The same bytecode is available to a program as RubyVM::InstructionSequence:

Source: Ruby 4.0 documentation: RubyVM::InstructionSequence

It prints the same disassembly as --dump=insns (with <compiled> in place of the file name). The AST dump under Prism is Prism’s own text form; under --parser=parse.y it is the older NODE_* format, which begins with a banner saying it must "not be used for any purpose other than debug and research": none of these formats is a stable interface. The VM, the instruction set and the JIT that consumes the bytecode are in YJIT, ZJIT and the VM.

ruby -y and --yydebug ask the parse.y parser for its trace; under the default Prism parser they print nothing, so add --parser=parse.y (or use --dump=yydebug). Unknown dump items are reported and ignored: ruby: warning: don't know how to dump 'foo', but only [version, copyright, usage, help, yydebug, syntax, parsetree, insns]. (note that prism_parsetree is not an item; parsetree prints the Prism tree on a Prism build).

Compiling during start-up wastes memory on code that runs once. RubyVM::YJIT.enable (Ruby 3.3) turns the compiler on from Ruby code, typically after the application has loaded (or in a forked worker, after fork); the optional mem_size: and call_threshold: keywords were added in Ruby 4.0 (on 3.3 and 3.4 passing them is an ArgumentError):

Source: Ruby 4.0 documentation: RubyVM::YJIT

Source: Ruby 4.0 documentation: RubyVM::YJIT

The second run is the useful one in practice: any --yjit-* tuning option otherwise starts YJIT at boot, and --yjit-disable says "keep the tuning, delay the start".

ZJIT was introduced in Ruby 4.0 as an experimental method-based compiler. The NEWS file for 4.0 says it is faster than the interpreter but not yet as fast as YJIT, and advises against production use; the stated goal is to make it faster than YJIT and production-ready in 4.1. ZJIT needs a Rust toolchain when Ruby is built; in a build without it (like the one used for this page) the option only warns:

Source: Ruby 4.0 documentation: ZJIT

When it is available it has options of its own (--zjit-mem-size, --zjit-call-threshold, --zjit-num-profiles, --zjit-stats, --zjit-disable, --zjit-perf, --zjit-log-compiled-iseqs, --zjit-trace-exits) and RubyVM::ZJIT.enable. These are described in the ZJIT guide and were not run here. Treat ZJIT as something to experiment with, not to deploy.

RUBYOPT holds options that are added to the command line of every Ruby process that sees the variable, including the ones started by a Ruby program, bundle exec, gem, rake and tests. That reach is both its use and its danger: a stray RUBYOPT=-w in a shell profile floods the output of every tool with warnings from gems. Only options that do not choose the program or change how it is read are accepted. Observed on 4.0.7:

Source: Ruby 4.0 documentation: Ruby Command-Line Options

The rules, as observed:

bundle exec is the best-known user of the variable: it sets RUBYOPT to -r/path/to/bundler/setup (plus BUNDLE_GEMFILE) in the child process so that the Gemfile’s gem set is the only one that require sees:

Source: Bundler: bundle exec

(The paths are abbreviated.) That is also the explanation for a common surprise: a Ruby program started from inside a bundle exec shell (a subprocess, a test runner, system("ruby ...")) inherits Bundler’s environment and cannot load gems that are not in the bundle. Bundler.with_unbundled_env removes it. RubyGems and Bundler are in RubyGems and Bundler.

Source: Ruby 4.0 documentation: Ruby Command-Line Options

Source: Ruby 4.0 documentation: Ruby Command-Line Options

Three of them can be observed directly:

Source: Ruby 4.0 documentation: Ruby::Box

Ruby::Box is experimental in 4.0 and may change; it is mentioned here only as a switch and described in Code Loading: require and autoload. RUBY_MN_THREADS is the entry point to the scheduler of Threads and the GVL; Ractors and fibers are in Ractors and Fibers and the Fiber Scheduler.

The stack-size variables decide how deep a thread’s recursion can go before SystemStackError. A smaller stack lets a program keep more threads or fibers alive, a larger stack allows deeper recursion; too small a machine stack combined with C extensions risks a segmentation fault instead of an exception, so change them only with measurements. The numbers below are for the 64-bit macOS build used here and depend on the platform and the size of each frame:

Source: Ruby 4.0 documentation: Thread

Source: Ruby 4.0 documentation: Thread

The garbage collector reads a family of RUBY_GC_* variables at start-up. The page Garbage Collection and Memory explains the heap, generations and the tools (GC.stat, GC.config); the table is the reference of the variables in the 4.0.7 manual page:

Source: Ruby 4.0 documentation: GC

The malloc limits are observable:

Source: Ruby 4.0 documentation: GC

Source: Ruby 4.0 documentation: GC

The reported limits are not exactly the requested values (the first is adjusted at start-up; the second is the requested 2000000 multiplied by its growth factor 1.2), but they move with the variables. A Ruby 3.2 to 3.3 migration note, verified by running both: on 3.2 RUBY_GC_HEAP_INIT_SLOTS enlarges the initial heap, on 3.3 and later it is ignored and the per-heap RUBY_GC_HEAP_0_INIT_SLOTS (to _4_) takes its place. Tuning the collector is a measured activity: change one variable at a time and compare GC.stat and the run time, see Performance, Benchmarking and Profiling.

RubyGems reads its own variables (they are documented by gem help environment and the RubyGems guides); the ones a developer meets constantly:

Source: Ruby 4.0 documentation: Gem

Source: Ruby 4.0 documentation: Gem

(Paths abbreviated.) Setting GEM_HOME to a project directory is the manual way to isolate gems per project; Bundler’s bundle config set path does the same with a setting instead of an environment variable. The detail is in RubyGems and Bundler and in Creating and Publishing Gems, and Rake. A secret (an API key, a token) belongs in an environment variable read with ENV.fetch at run time, never in a file in the repository; see Security.