Configuration reference

A consolidated list of CRuby's runtime configuration knobs: command-line flags, environment variables, and build-time switches.

Command-line flags

./ruby --help prints the full list. Most-used:

Flag	Purpose
-e CODE	Run CODE inline.
-r LIBRARY	require LIBRARY before running.
-I PATH	Prepend PATH to $LOAD_PATH.
-C PATH	chdir to PATH first.
-S	Look up the script via $PATH.
-d / --debug	Enable $DEBUG.
-w / --warn=...	Enable warnings.
-W0 / -W1 / -W2	Warning levels.
-v / --version	Print version.
-h / --help	Brief help.
--copyright	Print copyright.
-x	Discard everything before the first #!ruby.
-K	Set source encoding (legacy).
-E external[:internal]	Default external/internal encodings.
-U	Internal encoding = UTF-8.
-c	Syntax-check only, do not run.
--dump=FORMAT	Dump and exit (yydebug, parsetree, parsetree_with_comment, insns, insns_without_opt).
--enable=FEATURE / --disable=FEATURE	Toggle features (gems, rubyopt, did_you_mean, error_highlight, syntax_suggest, frozen-string-literal, jit, yjit, zjit, mjit).
--parser=parse.y / --parser=prism	Select parser.
--yjit / --no-yjit	Toggle YJIT at startup.
--zjit / --no-zjit	Toggle ZJIT.
--jit-stats / --yjit-stats / --zjit-stats	Print stats at exit.
--profile-stats	Print profile stats.

YJIT options

Flag	Purpose
--yjit-call-threshold=N	Compile after N calls (default 30).
--yjit-cold-threshold=N	Skip compilation if iseq is hotter than this (heuristic).
--yjit-exec-mem-size=N	Code memory in MiB (default 64).
--yjit-stats	Counters at exit.
--yjit-stats=quiet	Counters only on RubyVM::YJIT.runtime_stats.
--yjit-trace-exits	Record every side exit.
--yjit-perf	Generate perf jitdump for Linux perf.
--yjit-dump-disasm=NAME	Print disassembly for compiled methods matching NAME (requires --enable-yjit-dev).
--yjit-disable	Build YJIT in but don't enable at boot.

ZJIT options

Flag	Purpose
--zjit-call-threshold=N	Compile after N calls.
--zjit-stats	Runtime counters.
--zjit-dump-hir=NAME	Print initial HIR for matching methods.
--zjit-dump-hir-opt=NAME	HIR after each optimization pass.
--zjit-dump-lir=NAME	LIR.
--zjit-dump-disasm=NAME	Final machine code.
--zjit-debug	Enable extra debug logging.
--zjit-disable	Build ZJIT but don't enable at boot.

Environment variables

Runtime

Variable	Purpose
RUBYOPT	Extra command-line options applied to every Ruby invocation.
RUBYLIB	Extra $LOAD_PATH directories.
RUBYPATH	Default search path for -S.
RUBYSHELL	Shell used by system/exec.
RUBY_TZ	Default timezone.
RUBY_DEBUG	Generic debug.
RUBY_VERBOSE	Default $VERBOSE.
RUBY_DESCRIPTION	Override RUBY_DESCRIPTION constant.

GC

Variable	Purpose
RUBY_GC_HEAP_INIT_SLOTS	Initial slot budget per page.
RUBY_GC_HEAP_FREE_SLOTS	Min free slots after GC.
RUBY_GC_HEAP_FREE_SLOTS_MIN_RATIO	Min ratio of free slots.
RUBY_GC_HEAP_FREE_SLOTS_MAX_RATIO	Max ratio of free slots.
RUBY_GC_HEAP_GROWTH_FACTOR	Heap growth on miss.
RUBY_GC_HEAP_GROWTH_MAX_SLOTS	Cap on per-grow allocation.
RUBY_GC_HEAP_REMEMBERED_WB_UNPROTECTED_OBJECTS_LIMIT	Cap on un-protected old objects.
RUBY_GC_HEAP_OLDOBJECT_LIMIT_FACTOR	When old object count triggers major GC.
RUBY_GC_MALLOC_LIMIT	Bytes of malloc to trigger minor GC.
RUBY_GC_MALLOC_LIMIT_MAX	Max malloc limit.
RUBY_GC_MALLOC_LIMIT_GROWTH_FACTOR	Malloc-limit growth on miss.
RUBY_GC_OLDMALLOC_LIMIT	Bytes of malloc to trigger major GC.
RUBY_GC_OLDMALLOC_LIMIT_MAX	Max old-malloc limit.
RUBY_GC_OLDMALLOC_LIMIT_GROWTH_FACTOR	Old-malloc-limit growth.
RUBY_GC_STRESS	Run GC on every allocation.
RUBY_GC_STRESS_COMPACT	Compact on every chance.
RUBY_FREE_AT_EXIT	Free everything at exit (catches use-after-free).

Threads / Fibers

Variable	Purpose
RUBY_THREAD_TIMESLICE	Thread switch cadence in ms.
RUBY_THREAD_VM_STACK_SIZE	Per-thread VM stack size.
RUBY_THREAD_MACHINE_STACK_SIZE	Per-thread native stack size.
RUBY_FIBER_VM_STACK_SIZE	Per-fiber VM stack size.
RUBY_FIBER_MACHINE_STACK_SIZE	Per-fiber native stack size.
RUBY_MN_THREADS	Enable M:N scheduler.
RUBY_MAX_CPU	Cap effective CPU count for M:N.

Crash handling

Variable	Purpose
RUBY_CRASH_REPORT	Path to write SEGV crash reports.
RUBY_DUMP_YJIT_STATS	Auto-print YJIT stats at exit.
RUBY_NUMA_INTERLEAVE	Use NUMA interleaved memory allocation.

Regexp

Variable	Purpose
RUBY_RE_TIMEOUT	Default Regexp.timeout in seconds.

Stdlib

Variable	Purpose
BUNDLE_*	Bundler config.
GEM_HOME / GEM_PATH	Per-user gem locations.
IRBRC	IRB config file.
OPENSSL_CONF	OpenSSL config.

Build-time switches (configure)

See build/configure.md for the comprehensive list. Selected:

Flag	Effect
--enable-yjit / --enable-zjit	Include the JITs.
--with-gc=mmtk	Use MMTk-backed GC.
--enable-shared	Build libruby.so.
--disable-install-doc	Skip RDoc generation.
--with-ext=A,B / --without-ext=A,B	Pick extensions.
--with-baseruby=PATH	Override base Ruby.
--enable-multiarch	Multi-arch install layout.
--enable-debug-env	Honour more RUBY_*_DEBUG env vars.

Build-time switches (compile flags)

Variable	Purpose
optflags	Optimisation level (default -O3).
debugflags	Debug info (default -ggdb3).
warnflags	Warning flags.
cflags	Persistent extra CFLAGS.
RUSTFLAGS	Extra rustc flags for YJIT/ZJIT.
LDFLAGS	Linker flags.

Magic comments (per-file)

Comment	Effect
# encoding: NAME	Source file encoding.
# frozen_string_literal: true	All "..." literals are frozen.
# warn_indent: false	Disable indent warnings.
# shareable_constant_value: literal	Shareability mode for constants in this file (Ractor).

Magic comments must appear on the first or second line.

Pragmas inside code

Pragma	Effect
using Module	Activate refinements from Module within current scope.
Warning[:deprecated] = true	Toggle deprecation warnings.
$VERBOSE = true/false/nil	Set verbosity globally.
Thread.report_on_exception = false	Suppress per-thread crash logs.

Where these are read

• Command-line flags: ruby.c::process_options.
• RUBYOPT: prepended to ARGV in ruby.c.
• GC env vars: gc/default/gc.c::ruby_gc_set_params.
• Thread/fiber stack sizes: thread.c::thread_stack_size_calc, cont.c::fiber_stack_size_init.
• Encoding env vars (LANG, LC_*): encoding.c.