TruffleRuby: A GraalVM Ruby for CPU-bound work, without the GIL

What TruffleRuby is and who should care

TruffleRuby is the GraalVM implementation of the Ruby programming language. The README frames the aim around four things: running idiomatic Ruby faster, running Ruby code and native extensions in parallel, supporting C extensions, and adding low-overhead interop with Java, JavaScript, Python and WebAssembly. The audience implied by that list is narrow but real. If your Ruby process spends its life waiting on a database, TruffleRuby is not the fix. If it spends its life crunching numbers, rendering, parsing, or holding a lock that the global interpreter lock forces it to hold, the design speaks directly to your problem.

The README states that TruffleRuby does not have a global interpreter lock and runs both Ruby code and thread-safe native extensions in parallel. That is the single most concrete differentiator from CRuby. It also states that TruffleRuby is not 100% compatible with MRI 4.0 yet, and that it passes around 98% of ruby/spec. Those two sentences should be read together. The 98% figure is higher than any other alternative Ruby implementation according to the README, and it is still not 100%. For a gem-heavy application, the missing 2% is where the work is.

Native versus JVM: the two runtime configurations

TruffleRuby ships in two distributions. The Native Standalone build contains only the Native runtime configuration. The JVM Standalone build contains the JVM configuration and includes support for other languages such as Java, JavaScript, Python and WebAssembly. The README presents a table of trade-offs rather than declaring a winner, which is the right way to read it.

Native is the default (`--native`). It starts about as fast as MRI, reaches peak performance faster, and has good peak performance when garbage collection is factored in. JVM (`--jvm`) starts slower and reaches peak performance more slowly, but has the best peak performance and Java host interoperability that, in the README's words, just works, whereas Native needs reflection configuration for that. So the choice is not about which is better. It is about whether your process is long-lived enough to amortize a slower warmup in exchange for a higher ceiling, and whether you need to call into Java objects directly.

You can confirm which configuration is running in three ways, according to the README: run `ruby --version` on the command line, or check `RUBY_DESCRIPTION` or `TruffleRuby.native?` in Ruby code. That last one is the useful hook for a smoke test in CI.

Installing TruffleRuby through a Ruby manager

The README recommends installing through a Ruby manager or installer rather than by hand, and lists RVM, rbenv, chruby, asdf, mise, ruby-build and ruby-install. It also recommends trying the dev builds, which contain the latest fixes and improvements, by replacing `VERSION` with `dev`.

For the Native Standalone distribution, the README gives these forms:

$ rbenv install truffleruby-VERSION
$ ruby-build -d truffleruby-VERSION ~/.rubies
$ asdf install ruby truffleruby-VERSION
$ mise install ruby@truffleruby-VERSION
$ ruby-install truffleruby
$ rvm install truffleruby # or truffleruby-head

The JVM Standalone uses a different name, with `+graalvm` appended:

$ rbenv install truffleruby+graalvm-VERSION
$ ruby-build -d truffleruby+graalvm-VERSION ~/.rubies
$ asdf install ruby truffleruby+graalvm-VERSION
$ mise install ruby@truffleruby+graalvm-VERSION
$ ruby-install truffleruby-graalvm

In CI, the README points at `ruby/setup-ruby@v1` with a `ruby-version` input of `truffleruby`, `truffleruby-head`, `truffleruby+graalvm` or `truffleruby+graalvm-head`:

- uses: ruby/setup-ruby@v1
  with:
    ruby-version: truffleruby # or truffleruby-head or truffleruby+graalvm or truffleruby+graalvm-head

Once installed, `gem` and `bundle` work as usual, so the first real use is the same as on any Ruby: install a gem and require it. The README does not walk through a hello-world program, so the meaningful first check is the runtime configuration itself, via `ruby --version` or `TruffleRuby.native?`.

Docker and the dependencies that bite first

For the Native Standalone distribution there are release and nightly container images published under the `truffleruby` package on GitHub Container Registry. For the JVM Standalone there are no Docker images yet, according to the README, which suggests downloading it and taking inspiration from the Native Standalone Dockerfiles under `tool/dockerfiles/stable.dockerfile`. That asymmetry is worth noting before you plan a container-based deployment around the JVM configuration.

The dependency list is where a first install usually fails. TruffleRuby needs make, gcc and g++ to build C and C++ extensions, CA certificates for the `openssl` C extension, and zlib for the `zlib` C extension. The README is blunt about the consequence: without these, many libraries including RubyGems will not work. It also notes that TruffleRuby tries to print a helpful error when a dependency is missing, but only on a best-effort basis. You also need a UTF-8 locale.

System support is enumerated rather than implied. Oracle Linux 7, 8 and 9; Ubuntu 18.04, 20.04 and 22.04; Fedora 37 and 38; Debian 10, 11 and 12; and macOS 11 (Big Sur). AMD64 is supported on Linux; AArch64 is supported on Linux and macOS. The README warns that TruffleRuby may not work if you severely restrict the environment, giving unmounting system filesystems such as `/dev/shm` as the example. That is a real constraint for hardened container runtimes that drop `/dev/shm`.

Where TruffleRuby is the wrong tool

Warmup is the honest limitation. The README says that to achieve its performance TruffleRuby needs a fair amount of warmup, as other advanced JIT compilers do. A short-lived script, a one-shot CLI, or a Rake task that runs for two seconds will spend most of its life in that warmup and see none of the benefit. The Native configuration starts about as fast as MRI, which softens the blow, but the peak-performance story still requires a process that stays alive.

Compatibility is the second limitation, and the README states it plainly: TruffleRuby is not 100% compatible with MRI 4.0 yet. Around 98% of ruby/spec is not the same as your application's test suite passing. The README recommends that people trying TruffleRuby on their gems and applications get in touch for help, which is a candid signal that the project expects rough edges on real dependency graphs rather than only on the spec suite.

There is also a structural mismatch worth naming. The JVM configuration has the best peak performance and the easiest Java interop, but it has no Docker images yet per the README, and it starts slower. If your deployment model is short-lived containers, the JVM configuration's strengths are the ones you can least afford to pay for.

TruffleRuby compared with JRuby

JRuby is the obvious alternative for anyone who wants Ruby off the global interpreter lock, and the difference is in what sits underneath. JRuby runs on the JVM and targets Java interop as its primary integration story. TruffleRuby runs on GraalVM and, in the JVM configuration, includes support for Java, JavaScript, Python and WebAssembly through the polyglot documentation. The README's stated aim is interop with several languages, not just Java.

The second difference is the compatibility target. The README says TruffleRuby version `AB.C.D` aims to be compatible with CRuby `A.B`, so TruffleRuby 34.0.0 aims at CRuby 3.4, and the project follows semantic versioning on that basis. It also notes that the last release using GraalVM/Truffle versioning was 25.0.0. If your team tracks a specific CRuby minor version, that numbering scheme tells you which TruffleRuby release to look at, which is more useful than a generic version comparison.

The third difference is release cadence. TruffleRuby is released on its own schedule based on features and important bug fixes, and does not follow the GraalVM release schedule. The README also states that the Truffle version is fixed and is a dependency of the `dev.truffleruby:truffleruby` Maven artifact, so it cannot be swapped independently. If you consume TruffleRuby as a Maven dependency, that pinning is a constraint on your upgrade path, not a convenience.

Maintenance, licensing and what to check before adopting

The repository is not archived and the last push was on 2026-09-23, one day before the date of writing, so the codebase is receiving changes. The most recent release listed is graal-40.0.0 (TruffleRuby 40.0.0) on 2026-09-17, following graal-34.0.1 on 2026-04-26 and graal-34.0.0 on 2026-04-12. That pattern is worth reading carefully. Two releases in April 2026, then a gap to September 2026, then a jump in the leading version number. The README's own explanation is that releases follow features and important bug fixes rather than a fixed calendar, so the gap is expected behaviour rather than a warning sign. It does mean you should not plan an upgrade schedule around a predictable cadence.

On licensing, the repository carries a `LICENCE.md` and a `3rd_party_licenses.txt` at the top level, and the metadata license field is NOASSERTION, which means the platform could not classify it automatically. Read `LICENCE.md` directly rather than relying on the metadata tag, and read `3rd_party_licenses.txt` if you redistribute the runtime. That is a factual description of what is in the repository, not legal advice.

Upgrade cost has one concrete lever: the `dev` builds. The README recommends trying them because they contain the latest fixes and improvements. That is a reasonable way to stay ahead of a compatibility bug that a stable release has not picked up yet, at the cost of running unreleased code. The compatibility table in the README fixes the GraalVM version for each TruffleRuby release, so an upgrade is a paired move, not a single version bump.

Editorial conclusion

Adopt TruffleRuby when a long-running, CPU-heavy service or a parallel native-extension workload justifies a warmup phase, and keep CRuby as the reference for CI. Skip it for short-lived scripts and for code that depends on MRI behaviour the project says is not yet at 100%. Before committing, run your gem set under the truffleruby-head build and check the compatibility table for the GraalVM version your deployment pins.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. README
4. Releases
5. truffleruby/truffleruby on GitHub