Ruby Regex Guide

Regex Literals

Ruby has dedicated syntax for regular expressions, so you rarely construct them from strings. The forward-slash literal is by far the most common:

re = /\d{4}-\d{2}-\d{2}/        # the usual form
re = %r{https?://[^\s]+}        # %r when the pattern contains slashes
re = Regexp.new("\\d+")         # from a string (note the doubled backslash)

Because the literal form does not go through string escaping, you write \d directly — there is no "raw string" concern as in Python. Reach for %r{...} when the pattern itself contains / (URLs, paths) so you do not have to escape every slash. Only use Regexp.new when the pattern is built dynamically at runtime.

The ^ and $ Trap

This is the single most important thing to know about Ruby regex. ^ and $ always match at line boundaries, not at the boundaries of the whole string — and there is no flag to change that:

"first\nsecond" =~ /^second/     # 6 — ^ matches at the start of the 2nd line!
"first\nsecond" =~ /\Asecond/    # nil — \A is the true start of the string

This breaks naive validation in a way attackers exploit. A check like /^https:/ can be slipped past with an input such as "evil\nhttps://ok", because ^ happily matches at the start of the second line. Always anchor validations to the whole string:

"evil\nhttps://x" =~ /^https:/    # matches — BAD for validation
"evil\nhttps://x" =~ /\Ahttps:/   # nil — GOOD, rejects the input

• \A — start of the entire string.
• \z — end of the entire string.
• \Z — end of the string, but allows a single trailing newline.

Rule: use \A and \z for anything that validates a complete value. Reserve ^ and $ for genuinely line-oriented matching.

The /m Flag Means Dotall

Ruby's /m modifier does not do what it does in Python, Java, or JavaScript. In Ruby it makes the dot match newlines — what other engines call "dotall" or "single-line" mode. It has no effect on ^ and $, which already match line boundaries unconditionally:

"a\nb" =~ /a.b/      # nil  — . does not match the newline by default
"a\nb" =~ /a.b/m     # 0    — /m lets . match the newline

If you came from another language expecting /m to change anchor behaviour, you will be confused. In Ruby, anchors are already line-based; /m only changes the dot. This is one of the most common cross-language regex mistakes.

Matching Methods

Ruby spreads regex operations across String and Regexp methods plus a couple of operators:

str.match?(/\d+/)         # true/false, NO global side effects (Ruby 2.4+) — preferred
str =~ /\d+/              # index of first match or nil; sets $~, $1, ...
str.match(/(\d+)/)        # MatchData or nil
str.scan(/\d+/)          # array of all matches: ["1", "22", "333"]
str[/\d+/]               # the matched substring (or nil) — handy one-liner
str.split(/\s*,\s*/)     # split on a pattern
str.gsub(/\d/, "#")      # replace all; sub replaces the first only

Prefer match? for boolean checks: it is faster and does not touch the global match variables, which keeps code free of hidden state:

if line.match?(/\AERROR/)
  handle_error(line)
end

Named Captures

Ruby uses (?<name>...) for named groups. Access them through MatchData with a symbol or string key:

m = "2026-06-10".match(/(?<year>\d{4})-(?<month>\d{2})-(?<day>\d{2})/)
m[:year]      # "2026"
m[:month]     # "06"
m[0]          # "2026-06-10" — the whole match
m.named_captures  # {"year"=>"2026", "month"=>"06", "day"=>"10"}

Ruby has a special trick: when a regex literal appears on the left of =~ and contains named captures, each becomes a local variable automatically:

if /(?<year>\d{4})-(?<month>\d{2})/ =~ "2026-06-10"
  puts year    # "2026" — year is now a local variable
  puts month   # "06"
end

This only works with a literal on the left of =~ known at parse time — not with String#match and not when the regex is stored in a variable. It is convenient but surprising, so use it deliberately.

Substitution with gsub and sub

gsub replaces every match, sub replaces the first. Backreferences in the replacement string use \1 or \k<name>:

"2026-06-10".gsub(/(\d{4})-(\d{2})-(\d{2})/, '\3/\2/\1')
# "10/06/2026"

"2026-06-10".gsub(/(?<y>\d{4})-(?<m>\d{2})-(?<d>\d{2})/, '\k<d>/\k<m>/\k<y>')
# "10/06/2026"

Use single-quoted replacement strings so \1 is not consumed by Ruby's string escaping (in a double-quoted string you would need "\\1"). For computed replacements, pass a block — its value replaces each match:

"hello world".gsub(/\w+/) { |word| word.capitalize }
# "Hello World"

gsub also accepts a hash for keyed replacement, which is perfect for escaping:

escapes = { "&" => "&amp;", "<" => "&lt;", ">" => "&gt;" }
html.gsub(/[&<>]/, escapes)

Flags and Inline Modifiers

Modifiers go after the closing slash of a literal:

/hello/i      # case-insensitive
/a.b/m        # dot matches newline (dotall)
/ \d{4} /x    # extended/verbose: ignore whitespace, allow # comments
/pattern/o    # interpolate any #{...} only once, on first use

• i — case-insensitive.
• m — dot matches newline (NOT a multiline anchor switch).
• x — extended mode: unescaped whitespace and # comments are ignored, so you can lay a pattern out across lines.
• o — perform #{} interpolation only once, even in a loop.

Inline forms work mid-pattern too: (?i:Hello) scopes case-insensitivity to one section, and (?i) / (?-i) turn it on and off from that point.

The Onigmo Engine

Ruby's regex is powered by Onigmo, a backtracking engine, so unlike Go or Rust it supports the full advanced feature set:

• Backreferences — \1 or \k<name> inside the pattern.
• All four lookarounds — (?=...), (?!...), (?<=...), (?<!...).
• Atomic groups (?>...) and possessive quantifiers *+, ++ for controlling backtracking.
• Subexpression calls \g<name> for recursive patterns, e.g. matching balanced brackets.
• Unicode property escapes like \p{L} for any letter, \p{Han} for a script.

The flip side of a backtracking engine is the risk of catastrophic backtracking on patterns like /(a+)+b/. Avoid nested quantifiers on untrusted input, and use atomic groups or possessive quantifiers to bound the work. For deeper coverage of assertions, see the lookahead and lookbehind guide.

Common Gotchas

• Using ^/$ to validate a whole value. They are line anchors in Ruby. Use \A and \z — this is a security issue, not a style nit.
• Expecting /m to change anchors. In Ruby /m only makes . match newlines.
• Relying on $1 after match?. match? deliberately does not set the global match variables — use =~ or match when you need captures.
• Double-quoted replacement strings. "\1" is consumed by string escaping; use single quotes '\1' or "\\1" in gsub.
• Expecting auto-assigned named-capture locals from String#match. That magic only happens with a literal on the left of =~.
• Catastrophic backtracking on nested quantifiers with hostile input. Prefer atomic groups or possessive quantifiers.