You need a Ruby version that Fedora does not ship
You cloned a Rails application. You ran bundle install. The command failed with a version mismatch. The Gemfile requires Ruby 3.2.2, but Fedora 41 ships Ruby 3.3.0. Or you are maintaining a legacy script that breaks on 3.3. The system Ruby is managed by dnf. Downgrading it risks breaking system tools that depend on the release version. You need a way to install and switch Ruby versions per project without touching the system packages.
This is what rbenv does. It manages multiple Ruby installations in your home directory and routes commands to the correct version based on your current directory. It does not use virtual environments. It uses a shim system to intercept calls to ruby and gem.
How rbenv intercepts commands
rbenv works by modifying your PATH. It places a directory called shims at the front of your path. When you type ruby, the shell finds ~/.rbenv/shims/ruby before it finds /usr/bin/ruby.
The shim is a lightweight script. It checks for a .ruby-version file in your current directory and parent directories. If it finds one, it loads the specified version. If not, it falls back to the global version. The shim then executes the real Ruby binary from ~/.rbenv/versions/<version>/bin/ruby.
Think of rbenv as a traffic cop. You ask for ruby. The cop checks your location. If you are in a project directory with a version file, the cop directs you to that version. If you are in your home directory, the cop directs you to the global default. The system Ruby stays untouched in /usr/bin.
This design keeps your user space isolated. You do not need sudo to install Ruby versions. You do not risk package conflicts with dnf. A botched rbenv configuration only affects your user shell. The system remains bootable and functional.
Install rbenv and Ruby
Fedora does not need the IUS repository. IUS targets Enterprise Linux 9. Fedora ships all required dependencies in the base repositories. Adding IUS on Fedora can cause package conflicts. Skip IUS. Use the base repos.
Run the following commands to set up rbenv and install a Ruby version.
# Install build dependencies required to compile Ruby from source.
# rbenv downloads the tarball and runs ./configure && make.
# Fedora provides these packages in the base repositories.
sudo dnf install -y gcc make git curl openssl-devel readline-devel zlib-devel
# Clone rbenv into the standard location.
# This keeps the tool isolated in your home directory.
# No sudo required because rbenv runs as your user.
git clone https://github.com/rbenv/rbenv.git ~/.rbenv
# Clone the ruby-build plugin.
# rbenv core does not include version installation.
# This plugin provides the rbenv install command.
git clone https://github.com/rbenv/ruby-build.git "$(rbenv root)"/plugins/ruby-build
# Add rbenv to PATH so the shell can find the rbenv command.
# This line must come before the init eval.
# Use $HOME instead of ~ to avoid expansion issues in some shells.
echo 'export PATH="$HOME/.rbenv/bin:$PATH"' >> ~/.bashrc
# Initialize rbenv shims and hooks.
# This wraps ruby and gem commands to intercept calls.
# The eval ensures the shell functions are loaded correctly.
echo 'eval "$(rbenv init -)"' >> ~/.bashrc
# Reload the shell to apply changes.
# Open a new terminal if this command does not take effect.
source ~/.bashrc
# Install a specific Ruby version.
# rbenv downloads source, compiles it, and places it in ~/.rbenv/versions.
# This step may take a few minutes depending on your CPU.
rbenv install 3.3.0
# Set the default version for all shells.
# This creates a ~/.rbenv/version file with the version string.
rbenv global 3.3.0
Run rbenv install -l to see all available versions. The list updates as Ruby releases new patches. Pin your project to a specific patch version in production. Minor version bumps can introduce breaking changes.
Verify the installation
Check that rbenv is active and routing correctly.
# Confirm the shell is using the rbenv shim.
# The output must point to ~/.rbenv/shims/ruby.
which ruby
# Verify the version matches your global setting.
ruby -v
# List installed versions and highlight the active one.
rbenv versions
If which ruby returns /usr/bin/ruby, your PATH configuration is wrong. The ~/.rbenv/shims directory must appear before /usr/bin in your path. Check ~/.bashrc for the export line. Ensure eval "$(rbenv init -)" runs after the export.
If ruby -v shows the wrong version, run rbenv global <version> again. Check ~/.rbenv/version for typos.
Rehash after every gem install. Stale shims cause silent failures.
Common pitfalls and error patterns
rbenv: ruby: command not found
Your shell configuration is not loaded. Run source ~/.bashrc. If you use zsh, add the lines to ~/.zshrc instead. rbenv does not auto-detect your shell. You must configure the file your shell reads.
ruby -v shows system Ruby
The PATH order is incorrect. rbenv prepends ~/.rbenv/shims to PATH. If /usr/bin appears earlier, the system binary wins. Run echo $PATH and verify ~/.rbenv/shims is first. Fix ~/.bashrc and reload.
gem install fails with Makefile: *** [extconf.rb] Error 1
You are missing a development header. The error message usually names the missing library. Install the corresponding -devel package. For example, sudo dnf install openssl-devel fixes OpenSSL compilation errors. Fedora splits runtime libraries and headers. rbenv compiles from source, so you need the headers.
rake or bundle not found after gem install
rbenv needs to regenerate shims for new executables. Run rbenv rehash. This scans all installed Ruby versions for new binaries and updates the shim directory. Some plugins automate this, but running it manually ensures the cache is fresh.
rbenv install fails with configure: error: ...
The build environment is incomplete. Ensure gcc, make, and all -devel packages are installed. Check the full output for the specific missing dependency. Fedora's package names match the upstream library names. Search dnf provides */<header.h> to find the package if the name is unclear.
Trust the shim. rbenv handles the routing. You just set the version and keep the build tools installed.
When to use rbenv vs alternatives
Use system Ruby when you only need Ruby for occasional scripts and do not care about version pinning. The system package is updated automatically with dnf upgrade --refresh. No maintenance required.
Use rbenv when you manage multiple projects with different Ruby versions and want a lightweight shim-based approach. rbenv has minimal overhead and integrates cleanly with Bundler.
Use RVM when you need full environment isolation including gems per project without a separate tool. RVM manages Ruby versions and gemsets in one layer. It is heavier and modifies more shell state than rbenv.
Use asdf when you manage multiple languages like Node, Python, and Elixir and want a single plugin-based manager. asdf uses a unified .tool-versions file for all runtimes.
Stay on the Fedora default if you are running a service that depends on the system package manager for updates and security patches. System packages receive updates faster than compiled user-space versions.
Snapshot the system before the upgrade. Future-you will thank you.