Ruby Fix, Crash & Optimization Guide

Ruby is a dynamic, developer-friendly language best known for Rails and fast scripting. This guide covers version managers, gem installation failures (especially native extensions like Nokogiri), and Ruby performance tuning.

Install / First Setup

• macOS (recommended): brew install rbenv then rbenv install 3.3.0 && rbenv global 3.3.0.
• Linux: install rbenv (or rvm), plus build deps: sudo apt install git curl libssl-dev libreadline-dev zlib1g-dev build-essential.
• Windows: winget install RubyInstaller.Ruby.3.3 (RubyInstaller bundles the MSYS2 dev tools).
• Verify with ruby --version and gem --version.

Common Issues & Fixes

ruby: command not found

Cause: Ruby isn't installed or rbenv's shims aren't on PATH. Fix: Add rbenv to your shell (eval "$(rbenv init -)") and ensure ~/.rbenv/shims (or /usr/local/bin for system Ruby) is first on PATH. On Windows, select "add Ruby to PATH" in the installer.

Gem native extension fails (nokogiri, pg, sqlite3, etc.)

Cause: The gem compiles C extensions but dev headers/libraries are missing (common on fresh Linux). Fix: On Debian/Ubuntu install sudo apt install ruby-dev build-essential libxml2-dev libxslt1-dev libssl-dev. On macOS brew install libxml2 libxslt and run the gem with gem install nokogiri -- --with-xml2-include=$(brew --prefix libxml2)/include. On Windows use RubyInstaller's MSYS2 ridk install.

bundle: command not found

Cause: Bundler isn't installed or isn't on PATH. Fix: gem install bundler, then run commands with bundle install / bundle exec. Ensure the gem bin dir (~/.rbenv/versions/.../bin or ~/.gem/ruby/x.x.x/bin) is on PATH.

Gem install permission denied (system Ruby)

Cause: Writing into the system Ruby's gem dir without sudo. Fix: Do NOT use sudo gem. Use a version manager (rbenv/rvm), or install to your home with gem install --user-install and add ~/.gem/ruby/x.x.x/bin to PATH.

rbenv: version '<x>' is not installed / Could not find 'ruby'

Cause: The project's .ruby-version requests a Ruby you haven't built. Fix: rbenv install (reads .ruby-version) then rbenv rehash. Restart your shell so shims refresh.

Performance & Optimization

• Low-End: Avoid heavy frameworks for scripts; use --disable=gems only when you truly need a bare interpreter. Keep one Ruby version via rbenv to limit disk/build cost.
• Mid: For Rails apps, enable the JIT: Ruby 3.3+ ships RJIT; you can also use Shopify's YJIT by installing the yjit support and launching with ruby --yjit (or RUBYOPT="-yjit"). YJIT noticeably speeds up Rails.
• Workstation: Run Ruby with YJIT for CPU-bound workloads, precompile assets, and use Bootsnap/spring to cut Rails boot time in development. Benchmark with benchmark/derailed before claiming gains.

Note: MJIT existed in Ruby 3.0–3.2; from 3.3 the default JIT is RJIT and YJIT (from a separate build) is the recommended high-performance option.

Version & Compatibility Notes

• Ruby 3.x is current; Ruby 2.7 reached end-of-life and should be retired.
• rbenv/rvm let you run many versions side by side; .ruby-version pins a project.
• Gems declare a required Ruby version; mismatches surface as install errors, not runtime crashes.
• For exact current version numbers and EOL dates, consult official release notes.

FAQ

Q: rbenv or RVM — which should I use? A: Either works; rbenv is lighter and more common today. Both avoid system-Ruby permission problems by installing Rubies into your home directory.

Q: Why does installing Nokogiri fail with compiler errors? A: It builds a native C extension and needs ruby-dev, a C compiler, and libxml2/libxslt headers. Install those dev packages (see the native-extension fix above) and retry.

Q: How do I speed up a Rails app? A: Enable YJIT (ruby --yjit), use Bootsnap/Spring in dev, precompile assets, and profile database queries. JIT helps CPU-bound Ruby, less so I/O-bound waits.

Q: Should I use sudo gem install? A: No. Use a version manager so gems go into your home dir, or gem install --user-install. Sudo can break system Ruby and create permission conflicts.

Q: How do I set a project's Ruby version? A: Create a .ruby-version file containing e.g. 3.3.0, then rbenv install && rbenv local 3.3.0.

Q: What's Bundler for? A: Bundler resolves and locks your project's gem versions via Gemfile/Gemfile.lock, ensuring every environment uses the same dependencies. Run bundle install then bundle exec <cmd>.

Related Guides

• Python Fix & Optimization Guide
• Node.js Fix & Optimization Guide
• Java Fix & Optimization Guide
• Dev RAM Calculator

Accuracy Note

Commands and paths reflect common, real-world setups as of 2026-08. Always verify against your installed version and OS. When in doubt, consult the official Ruby documentation.