rubyguides

Kernel#warn 

warn(string[, category: :optional]) -> true or false
Returns Boolean· Updated May 30, 2026· Kernel Methods
warningsstderrdebuggingdeprecation

The warn method outputs a warning message to STDERR. It’s commonly used to alert users about deprecated features, potential issues, or informational notices during program execution.

Basic Usage

# Simple warning
warn "This feature will be removed in version 2.0"
# Outputs: Warning: This feature will be removed in version 2.0

# Multiple warnings
warn "Deprecation warning"
warn "Another warning"

The basic usage shows warn at its simplest: a single string goes to STDERR, prefixed with “Warning:” in some Ruby versions. The method returns true on success, which is rarely checked but can be useful in wrapper methods that want to confirm the warning was delivered. Multiple calls to warn each produce their own line, so the output stays readable even when several warnings fire in sequence.

Practical Examples

Deprecation Warnings

def old_method
  warn "old_method is deprecated, use new_method instead"
  new_method
end

def new_method
  # New implementation
end

Deprecation warnings are one of the most common patterns for warn because they give library authors a way to signal upcoming changes without breaking existing code. The old method still works, but the warning tells callers that a migration path exists. This pattern is used extensively in Rails and popular gems to manage API evolution over multiple release cycles.

Conditional Warnings

def process_data(data)
  if data.empty?
    warn "Warning: Empty data set provided"
    return
  end
  
  if data.size > 1000
    warn "Warning: Large dataset (#{data.size} items) may take longer"
  end
  
  # Processing...
end

The conditional warning pattern shows warn being used as a guard against problematic input. The method is called only when the data looks suspicious, so the warning is a signal rather than a constant stream of noise. This is a good fit for methods that accept a wide range of inputs but want to alert the caller when the data might cause slow or incorrect behavior.

With category (Ruby 2.5+)

warn "Using deprecated API", category: :deprecated
warn "This is experimental", category: :experimental

# Suppress specific categories
# Run with: ruby -W:no-experimental script.rb

The category parameter, introduced in Ruby 2.5, lets you tag warnings with a semantic label. The Ruby interpreter can then suppress specific categories at startup, which gives library authors a way to emit warnings without overwhelming users who only care about certain kinds of messages. This is especially useful for gems that want to signal deprecations without cluttering the output for unrelated code.

Verbose mode warnings

# Only warn in verbose mode
def experimental_feature
  warn "Experimental feature" if $VERBOSE
end

The $VERBOSE guard is a common Ruby idiom for conditional warnings. It follows the principle that verbose output should only appear when the caller has explicitly opted in, which is the same convention used by Ruby’s own interpreter warnings. Wrapping the warn call in this check keeps quiet runs quiet and lets developers turn on extra diagnostics when they need them.

Comparing warn with other output methods

puts "Info message"       # Goes to STDOUT
warn "Warning message"   # Goes to STDERR
$stderr.puts "Error"    # Goes to STDERR (explicit)

The comparison table highlights a key design choice: warn writes to STDERR while puts writes to STDOUT. That separation is what makes warn suitable for diagnostic messages, because tools and scripts can redirect or filter STDERR independently of normal program output. In production environments, STDERR messages often end up in a separate log stream for easier monitoring.

Configuration

# Suppress warnings
$VERBOSE = nil   # Suppress all warnings

# Enable warnings
$VERBOSE = true   # Normal warnings

# Very verbose
$VERBOSE = 2      # Extra verbose (includes deprecated warnings)

Using warn for signals

warn is most helpful when the message should stand out from normal output but still remain part of the program’s regular flow. Because it writes to STDERR, it is a natural choice for deprecations, suspicious input, and operational notes that should not mix with user-facing text. Keep the wording short and specific so the warning points to an action the caller can take. When warnings are too generic, they are easy to ignore and harder to trace back to the code that emitted them.

It also helps to keep warning messages stable and actionable. A message that names the condition, the affected method, or the next step gives the reader something to do, while a vague warning only adds noise. In a larger application, that difference matters because STDERR can carry a lot of unrelated output. A good warning is easy to notice, easy to search for, and easy to remove once the underlying issue is fixed.

If you expect the warning to live for a while, write it so future readers can understand it without extra context. That usually means one clear sentence and no extra drama. The best warnings act like signposts: they point at a problem, suggest a direction, and then get out of the way.

The most useful warnings are also consistent. If the same condition can happen in more than one place, keep the wording and the format similar so the message is easy to recognize in logs. That kind of consistency makes a warning feel like part of the program’s language instead of an isolated shout.

The warn method is the idiomatic way to output warnings in Ruby, distinguishable from regular output by going to STDERR.

See Also