Standard library

The Ruby standard library lives in lib/ (Ruby code) and ext/ (C extensions). Most stdlib gems are now default gems — published independently on rubygems.org and synced into this repo by tool/sync_default_gems.rb. A few are bundled gems — installed alongside Ruby but not autoloaded.

What ships in the standard library

lib/ contains roughly 80 default-gem subdirectories and ~7,500 Ruby source files in total. Major libraries:

Library	Purpose
rubygems	Package manager (the gem command)
bundler	Dependency manager
optparse	CLI option parser
uri	URI parsing and composition
net/http, net/protocol, net/smtp, etc.	Pure-Ruby network protocols
open-uri	open() for HTTP/HTTPS URLs
open3	Process execution with stdin/stdout/stderr capture
erb	Embedded Ruby templating
forwardable	def_delegator mixin
delegate	Decorator pattern via method delegation
pathname	Path objects (Pathname)
fileutils	High-level file ops (cp_r, chown_R, ...)
tempfile	Self-cleaning temp files
tmpdir	Dir.mktmpdir helper
time	Date/time parsing extensions
timeout	Timeout.timeout(t) { ... }
prettyprint, pp	Pretty-printing
set	The Set class on top of C primitive
singleton	The Singleton mixin
monitor	Re-entrant Mutex
weakref	Weak object references
did_you_mean	Suggestion engine for typos
error_highlight	Show the precise expression that failed
syntax_suggest	Locate where a syntax error originated
prism	The Prism parser (also vendored as C in prism/)
securerandom	Cryptographic random
resolv	Pure-Ruby DNS resolver
ipaddr	IP address objects
cgi	CGI helpers (legacy)
English	Aliases like $ERROR_INFO for $!

C-extension stdlib (ext/):

Extension	Purpose
socket/	Berkeley sockets (Socket, TCPSocket, UDPSocket, UNIXSocket)
openssl/	TLS, hashing, public-key crypto
psych/	YAML 1.1 parser/emitter (libyaml binding)
json/	JSON parser/generator
digest/	SHA1/SHA2/MD5/Bcrypt
io/console/	Terminal control
io/wait/	IO#wait_readable, wait_writable
io/nonblock/	Non-blocking IO toggles
etc/	Unix /etc/passwd etc.
fcntl/	fcntl(2) constants
pty/	Pseudo-terminal allocation
objspace/	ObjectSpace.dump_all and friends
zlib/	Compression
stringio/	In-memory IO
strscan/	StringScanner — incremental string parsing
date/	Date and DateTime
coverage/	Code-coverage tool
ripper/	Lexer/parser-events from parse.y
fiber/	Fiber pool, scheduler integration
mmtk/	MMTk GC binding

Default gems vs bundled gems

Aspect	Default gem	Bundled gem
Auto-required	Some (varies)	Never
Listed in Gemfile.lock if used	Yes (with version)	Yes
Listed in gem list after install	Yes	Yes
Listed in Gemfile's default gems	Implicit	Must be explicit
Source in this repo	lib/<name>/, ext/<name>/	gems/bundled_gems (by URL only — fetched at install)
Updates	tool/sync_default_gems.rb	Tracked in gems/bundled_gems versions

gems/bundled_gems is a plain text file listing the bundled gem name and version pinned for the current Ruby:

minitest 6.0.5
rake 13.4.2
test-unit 3.7.7
...

tool/update-bundled_gems.rb and tool/test-bundled-gems.rb manage installation and testing of these.

Default-gem promotion

Over time, libraries move between three states:

1. In-tree only: a one-off library shipped only with Ruby (rare today).
2. Default gem: shipped with Ruby and published on rubygems.org as a separate gem. Most stdlib libraries are here.
3. Bundled gem: published on rubygems.org and installed alongside Ruby, but not autoloaded. These are demoted from default to bundled when they're considered "optional".

NEWS.md records each release's promotions and demotions. Recently:

• tsort 0.2.0 and win32-registry 0.1.2 are promoted from default to bundled in Ruby 4.1.
• csv was demoted to a bundled gem in Ruby 3.4.

Why so much stdlib?

Ruby's stdlib has a wide surface partly for historical reasons (early versions had to ship batteries-included), partly for stability (CRuby releases ship a known-good version of common libraries), and partly because Ruby's release cadence (~yearly) is fast enough to keep the stdlib current with what most projects need.

The trade-off: every stdlib library has a maintenance cost. The recent trend is to demote rarely-used libraries to bundled status, eventually removing them from the install entirely.

Common stdlib usage patterns

# CLI
require 'optparse'
OptionParser.new do |opts|
  opts.on("-v", "--verbose") { @verbose = true }
end.parse!

# HTTP
require 'open-uri'
URI.open("https://example.com").read

# Tempfile
require 'tempfile'
Tempfile.create("prefix-") { |f| f.write("data"); f.path }

# Pretty print
require 'pp'
pp { foo: { bar: [1, 2, 3] } }

# Set
require 'set'
Set.new([1, 2, 3]) | Set.new([3, 4, 5])    # → #<Set: {1, 2, 3, 4, 5}>

# Net::HTTP
require 'net/http'
Net::HTTP.get(URI("https://example.com"))

Modifying stdlib

For default-gem libraries, the canonical source is the upstream gem repo (see tool/sync_default_gems.rb's REPOSITORIES hash). Open PRs there; the maintainer syncs them down to lib/<gem>/ for the next CRuby release.

For libraries that don't yet have an upstream gem (rare), edit lib/<name>.rb directly here.

For C extensions in ext/, the convention is the same: most have an upstream gem repo; some do not. Check the gem's metadata in ext/<name>/<name>.gemspec.

Loading and autoload

Most stdlib libraries are loaded via require "name". They populate $LOAD_PATH from the gem activation mechanism in lib/rubygems/.

A few are autoloaded — their constants are registered with Kernel#autoload so the file loads on first reference. English, optparse, etc. are not autoloaded; you must require them explicitly.

See systems/loader.md for the require/autoload story.