How to Resolve the Ruby Psych Missing Error

If you have ever seen this warning pop up and thought, “Cool… I have no idea what that means,” you’re not alone. The message usually looks like: “It seems your Ruby installation is missing psych (for YAML output). To eliminate this warning, please install libyaml and reinstall your ruby.” It’s annoying, it breaks Rails installs sometimes, and it tends to show up right when you’re feeling productive. Let’s fix it properly, with real commands and a few sanity checks so you know it’s actually gone.

What “Psych” is and Why Ruby Cares

Psych is Ruby’s YAML engine. YAML is that human-readable format used in Rails configs like database.yml and credentials.yml.enc workflows. Ruby uses Psych to read and write YAML, and Psych relies on a system library called libyaml. If libyaml is missing or Ruby was compiled without it, Ruby can’t load Psych correctly and complains. BigBinary sums it up simply: Ruby needs libyaml to parse and emit YAML, and missing it often triggers this error.

Why the Error Happen in Real Life

This issue usually happens for one of three reasons: you installed Ruby before installing libyaml, your Ruby version manager built Ruby without seeing libyaml, or your system has multiple toolchains (hello, Apple Silicon + Rosetta) and Ruby linked the wrong place. Ruby-build and asdf installs can fail mid-build with Psych-related logs when YAML headers/libraries aren’t found.

Confirm you Actually have a Psych Problem

Before you start reinstalling everything like a tired wizard, check what Ruby can load.

ruby -v
ruby -rpsych -e "puts Psych::VERSION"
ruby -ryaml -e "puts YAML.dump({ok: true})"

If the -rpsych line fails, or the YAML dump throws that same warning, you’re dealing with the real issue, not a random Rails gem tantrum.

Install Libyaml on your System

Now install the missing dependency first. The exact package name depends on your OS.

macOS (Homebrew):

BigBinary’s recommended approach is to install libyaml with Homebrew and then reinstall Ruby.

brew update
brew install libyaml

If you’re on Apple Silicon and have both /opt/homebrew and /usr/local floating around, don’t ignore it. Mixed architectures can cause Ruby to “see” the wrong libraries and compile without YAML support. BigBinary even calls out Apple Silicon brew confusion as a common source of Ruby build issues.

Ubuntu / Debian:

sudo apt update
sudo apt install -y libyaml-dev

The -dev part matters because Ruby needs headers like yaml.h during compilation.

Fedora / RHEL / CentOS:

sudo dnf install -y libyaml-devel

On some distros, you may need to enable additional repos for -devel packages, and missing that is a frequent reason Ruby’s Psych extension doesn’t compile.

Alpine (common in Docker):

apk add --no-cache libyaml-dev

Reinstall Ruby the Right Way (rbenv, asdf, or RVM)

Installing libyaml is only half the fix. If Ruby was already built without it, Ruby won’t magically rewire itself. You must rebuild Ruby after libyaml exists.

Reinstall with rbenv:

rbenv uninstall 3.3.1
rbenv install 3.3.1
rbenv global 3.3.1
rbenv rehash

If you want to be extra sure the build sees your Homebrew libraries on macOS, you can help it by setting build flags:

export RUBY_CONFIGURE_OPTS="--with-libyaml-dir=$(brew --prefix libyaml)"
rbenv install 3.3.1

That “point Ruby at libyaml explicitly” idea shows up a lot in real-world fix guides because Ruby’s build logs can be cryptic and the Psych failure is often just the symptom.

Reinstall with Asdf:

asdf uninstall ruby 3.3.1
asdf install ruby 3.3.1
asdf global ruby 3.3.1

If you’re stuck on macOS and the build still complains, it usually means Ruby didn’t find libyaml at compile time, which is exactly what the asdf Psych build issue threads describe.

Reinstall with RVM:

rvm reinstall 3.3.1
rvm use 3.3.1 --default

Verify the Fix like a Grown-up

After reinstalling Ruby, run the same checks again.

ruby -rpsych -e "puts Psych::VERSION"
ruby -ryaml -e "puts YAML.dump({fixed: true})"

If you see a Psych version number and YAML output without warnings, you’re done.

If the Error Appear During Bundle Install

Sometimes Ruby is fine, but your app is pulling a Psych gem that doesn’t match your Ruby setup, especially after upgrades. Rails community threads often show people fixing it by installing libyaml, then running bundler again.

Try:

bundle config set force_ruby_platform true
bundle install

If your Gemfile explicitly includes Psych, you can also try pinning a version that matches your Ruby line, but don’t do that unless you have a reason. Most of the time, the real fix is still “install libyaml + rebuild Ruby.”

Docker Specific Fix (super common, super sneaky)

If you see yaml.h not found while building gems in Docker, that’s the same root problem: missing libyaml-dev. The fix is to install it in the build layer.

Here’s a working example Dockerfile snippet:

FROM ruby:3.3-slim

RUN apt-get update -y \
  && apt-get install -y build-essential libyaml-dev \
  && rm -rf /var/lib/apt/lists/*

WORKDIR /app
COPY Gemfile Gemfile.lock ./
RUN bundle install
COPY . .

Conclusion

The “Psych missing” error isn’t a mysterious Ruby curse. It’s almost always “Ruby was built without libyaml.” Install libyaml, rebuild Ruby with your version manager, and verify using ruby -rpsych. Once you do that, Rails stops complaining, bundler behaves, and you can get back to building things instead of arguing with your terminal.