Overview

chruby operates as a shell function that modifies environment variables to switch between Ruby installations. The tool maintains a registry of available Ruby versions by scanning predefined directories and provides commands to activate specific installations. Unlike more complex version managers, chruby focuses exclusively on PATH manipulation and environment variable management.

The core functionality centers around the chruby shell function, which updates PATH, GEM_HOME, GEM_PATH, and RUBY_ROOT variables. When switching versions, chruby removes the previous Ruby's binary directories from PATH and prepends the new version's directories. This approach maintains compatibility with existing Ruby installations while providing clean version isolation.

# chruby scans these default directories
RUBIES=(
  /opt/rubies/*
  /usr/local/opt/ruby-*
  ~/.rubies/*
)

The auto-switching functionality reads .ruby-version files to automatically change Ruby versions when entering project directories. This mechanism integrates with shell hooks to detect directory changes and switch versions transparently.

# .ruby-version file content
3.1.0

chruby stores version information in shell arrays and uses pattern matching to locate installations. The chruby_auto function monitors the working directory and triggers version switches based on .ruby-version file presence.

Basic Usage

Installation requires sourcing the chruby script in shell configuration files. The script defines the chruby function and optionally enables auto-switching functionality.

# Add to ~/.bashrc or ~/.zshrc
source /usr/local/share/chruby/chruby.sh
source /usr/local/share/chruby/auto.sh

After sourcing, chruby scans for Ruby installations and populates the internal registry. The scan process examines standard installation directories and builds an array of available versions.

# List available Ruby versions
chruby
#   ruby-2.7.6
#   ruby-3.0.4
# * ruby-3.1.0

The asterisk indicates the currently active version. Switching versions requires calling chruby with the desired version name or partial match.

# Switch to specific version
chruby ruby-3.0.4

# Partial matching works
chruby 3.1

Version switching updates multiple environment variables simultaneously. The PATH variable receives the new Ruby's binary directory, while gem-related variables point to version-specific locations.

# Before switch
echo $PATH
# /usr/local/bin:/usr/bin:/bin

# After chruby ruby-3.1.0
echo $PATH
# /opt/rubies/ruby-3.1.0/bin:/usr/local/bin:/usr/bin:/bin

echo $GEM_HOME
# /opt/rubies/ruby-3.1.0/lib/ruby/gems/3.1.0

Auto-switching activates when entering directories containing .ruby-version files. The system reads the file content and attempts to match it against available Ruby installations.

# Create project with specific Ruby version
mkdir my_project
cd my_project
echo "3.0.4" > .ruby-version

# chruby automatically switches when entering directory
cd my_project
# Switched to ruby-3.0.4

Manual version deactivation returns the shell to the system Ruby or no Ruby environment.

# Reset to system Ruby
chruby system

# Disable Ruby entirely
chruby --

Custom Ruby installations integrate with chruby by placing them in scanned directories. The tool recognizes any directory structure containing bin/ruby executable.

# Custom installation location
mkdir -p ~/.rubies/custom-ruby
# Install Ruby to ~/.rubies/custom-ruby
# chruby will detect it automatically

Production Patterns

Production deployments benefit from centralized Ruby installation management through chruby. Server configurations typically install Ruby versions in /opt/rubies for system-wide access while maintaining version isolation per application.

# Production Ruby installation structure
/opt/rubies/
├── ruby-2.7.6/
├── ruby-3.0.4/
└── ruby-3.1.0/

# Application deployment script
#!/bin/bash
source /usr/local/share/chruby/chruby.sh
chruby ruby-3.1.0
cd /var/www/myapp
bundle install --deployment
bundle exec rails server -d

Container deployments incorporate chruby for multi-stage builds supporting multiple Ruby versions. The approach enables sharing base images while maintaining version flexibility.

# Multi-version Ruby container
FROM ubuntu:20.04

# Install chruby
RUN wget -O chruby-0.3.9.tar.gz https://github.com/postmodern/chruby/archive/v0.3.9.tar.gz
RUN tar -xzf chruby-0.3.9.tar.gz && cd chruby-0.3.9 && make install

# Install multiple Ruby versions
RUN ruby-install ruby 2.7.6
RUN ruby-install ruby 3.0.4
RUN ruby-install ruby 3.1.0

# Application startup script
COPY entrypoint.sh /usr/local/bin/
RUN chmod +x /usr/local/bin/entrypoint.sh

# entrypoint.sh
#!/bin/bash
source /usr/local/share/chruby/chruby.sh
chruby $(cat .ruby-version)
exec "$@"

Deployment automation scripts integrate chruby for consistent Ruby version management across environments. Configuration management tools like Ansible or Chef incorporate chruby commands in deployment playbooks.

# Deployment automation with chruby
#!/bin/bash
set -e

# Load chruby
source /usr/local/share/chruby/chruby.sh

# Read project Ruby version
PROJECT_RUBY=$(cat /var/www/myapp/.ruby-version)
chruby $PROJECT_RUBY

# Verify correct Ruby version
ruby --version
gem --version

# Install dependencies
cd /var/www/myapp
bundle install --deployment --without development test

# Compile assets
RAILS_ENV=production bundle exec rails assets:precompile

# Restart application server
sudo systemctl restart myapp

Continuous integration pipelines leverage chruby for testing across Ruby versions. The tool integrates with CI systems to provide matrix builds testing multiple Ruby versions simultaneously.

# GitHub Actions with chruby
name: Test
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        ruby: ['2.7', '3.0', '3.1']
    steps:
    - uses: actions/checkout@v2
    - name: Install chruby
      run: |
        wget -O chruby-0.3.9.tar.gz https://github.com/postmodern/chruby/archive/v0.3.9.tar.gz
        tar -xzf chruby-0.3.9.tar.gz
        cd chruby-0.3.9 && sudo make install
    - name: Install Ruby
      run: ruby-install ruby ${{ matrix.ruby }}
    - name: Setup Ruby
      run: |
        source /usr/local/share/chruby/chruby.sh
        chruby ruby-${{ matrix.ruby }}
        ruby --version
    - name: Install dependencies
      run: bundle install
    - name: Run tests
      run: bundle exec rspec

Production monitoring incorporates Ruby version tracking through environment reporting. Applications log active Ruby versions and gem environments for debugging and audit purposes.

# Application monitoring integration
class ApplicationController < ActionController::Base
  before_action :log_ruby_environment

  private

  def log_ruby_environment
    Rails.logger.info({
      ruby_version: RUBY_VERSION,
      ruby_engine: RUBY_ENGINE,
      gem_home: ENV['GEM_HOME'],
      gem_path: ENV['GEM_PATH']
    })
  end
end

Common Pitfalls

Shell configuration issues represent the most frequent chruby problems. Loading chruby after other Ruby version managers creates conflicts, while incorrect sourcing order prevents proper initialization.

# INCORRECT: Loading after rbenv
export PATH="$HOME/.rbenv/bin:$PATH"
eval "$(rbenv init -)"
source /usr/local/share/chruby/chruby.sh

# CORRECT: Load chruby first
source /usr/local/share/chruby/chruby.sh
# Remove other version managers

The PATH variable requires careful management when multiple Ruby tools coexist. System package managers often install Ruby versions that conflict with chruby-managed installations.

# Check for conflicting Ruby installations
which -a ruby
# /usr/bin/ruby (system)
# /opt/rubies/ruby-3.1.0/bin/ruby (chruby)
# /usr/local/bin/ruby (homebrew)

# Clean PATH to prioritize chruby
export PATH="/usr/local/bin:/usr/bin:/bin"
source /usr/local/share/chruby/chruby.sh
chruby ruby-3.1.0

Auto-switching failures occur when .ruby-version files contain invalid version specifications. The system fails silently when specified versions don't exist, leading to unexpected Ruby environments.

# .ruby-version contains non-existent version
echo "3.2.0" > .ruby-version
cd project_directory
# No automatic switch occurs, remains on previous version

# Verify available versions
chruby
# No ruby-3.2.0 listed

# Fix by using available version
echo "3.1.0" > .ruby-version
cd project_directory
# Successfully switches to ruby-3.1.0

Gem installation problems arise from incorrect GEM_HOME and GEM_PATH configurations. Users installing gems before activating chruby create orphaned gem installations.

# INCORRECT: Install gems before chruby activation
gem install rails
# Installs to system gem directory

source /usr/local/share/chruby/chruby.sh
chruby ruby-3.1.0
rails --version
# Command not found

# CORRECT: Activate chruby first
source /usr/local/share/chruby/chruby.sh
chruby ruby-3.1.0
gem install rails
rails --version
# Works correctly

Subshell environments lose chruby configuration when scripts spawn new shell processes. Functions and aliases defined in the parent shell don't propagate to subshells.

# Parent shell
chruby ruby-3.1.0
ruby --version
# ruby 3.1.0

# Subshell loses chruby configuration
bash -c "ruby --version"
# Uses system Ruby, not 3.1.0

# Fix by sourcing chruby in subshells
bash -c "source /usr/local/share/chruby/chruby.sh; chruby ruby-3.1.0; ruby --version"
# ruby 3.1.0

Directory permission issues prevent chruby from accessing Ruby installations in restricted locations. Installations in system directories require appropriate user permissions for gem management.

# Permission denied on gem installation
chruby ruby-3.1.0
gem install bundler
# ERROR: While executing gem ... (Gem::FilePermissionError)

# Check GEM_HOME permissions
ls -la $GEM_HOME
# drwxr-xr-x root root

# Fix by using user-writable Ruby installation
chruby ruby-3.1.0-user  # User-owned installation
gem install bundler
# Succeeds

Version matching ambiguity occurs when multiple Ruby installations share partial version numbers. chruby selects the first matching version, which may not be the intended choice.

# Multiple versions with same minor number
chruby
#   ruby-3.1.0
#   ruby-3.1.2

# Partial match selects first found
chruby 3.1
# Activates ruby-3.1.0, not ruby-3.1.2

# Use full version for specificity
chruby ruby-3.1.2
# Activates intended version

Reference

Core Commands

Environment Variables

Configuration Files

Installation Directories

Shell Integration

Version Matching Patterns

Auto-switching Behavior

Troubleshooting Commands