truffleruby

TruffleRuby is the GraalVM high-performance implementation of the Ruby programming language.

Getting Started

TruffleRuby comes in two distributions:

• Native Standalone: This only contains TruffleRuby in the Native configuration.
• JVM Standalone: This only contains TruffleRuby in the JVM configuration. This includes support for other languages such as Java, JavaScript, Python and WebAssembly.

You can install either of those:

• Via your Ruby manager/installer (RVM, rbenv, chruby, asdf, mise, ruby-build, ruby-install).
  We recommend trying TruffleRuby dev builds which contain the latest fixes and improvements (replace VERSION by dev).

Native Standalone:

$ 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

JVM Standalone:

$ 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 with GitHub Actions, see Testing TruffleRuby in CI for more details and other CIs.

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

• Via Docker. For the Native Standalone there are release & nightly images. For the JVM Standalone there are no Docker images yet, but you can easily download it and take inspiration from the Native Standalone Dockerfiles.

• Manually, by following the documentation.

You can use gem and bundle to install gems, as usual.

Please report any issues you might find on GitHub.

Aim

TruffleRuby aims to:

• Run idiomatic Ruby code faster.
  • TruffleRuby is the fastest Ruby implementation for many CPU-intensive benchmarks.
• Run Ruby code and native extensions in parallel.
  • TruffleRuby does not have a global interpreter lock and runs both Ruby code and thread-safe native extensions in parallel.
• Support C extensions.
  • Many C extensions work out of the box, including database drivers.
• Add fast and low-overhead interoperability with languages like Java, JavaScript, Python and WebAssembly.
  • See the Polyglot documentation.
• Provide new tooling, such as debuggers and monitoring, that works across languages.
  • Includes a profiler, debugger, VisualVM, and more. See the Tools documentation.
• Provide all of the above while maintaining very high compatibility with the standard implementation of Ruby.

TruffleRuby Runtime Configurations

There are two main runtime configurations of TruffleRuby, Native and JVM, which have different trade-offs.

Configuration:	Native (--native, default)	JVM (--jvm)
Time to start TruffleRuby	about as fast as MRI startup	slower
Time to reach peak performance	faster	slower
Peak performance (also considering GC)	good	best
Java host interoperability	needs reflection configuration	just works

To find out which runtime configuration is being used, run ruby --version on the command line, or check the value of RUBY_DESCRIPTION or TruffleRuby.native? in Ruby code. Runtime configurations are further detailed in Deploying TruffleRuby.

System Compatibility

TruffleRuby is actively tested on the following systems:

• Oracle Linux 8, 9, 10
• Fedora 43, 44
• Ubuntu 20.04, 22.04, 24.04, 26.04 (all LTS)
• Debian 12, 13
• macOS 15

Architectures:

• AMD64 (aka x86_64): Supported on Linux
• AArch64 (aka arm64): Supported on Linux and on macOS

You may find that TruffleRuby will not work if you severely restrict the environment, for example, by unmounting system filesystems such as /dev/shm.

Dependencies

• make, gcc and g++ for building C and C++ extensions
• CA certificates for the openssl C extension
• zlib for the zlib C extension

Without these dependencies, many libraries including RubyGems will not work. TruffleRuby will try to print a nice error message if a dependency is missing, but this can only be done on a best effort basis.

You also need to set up a UTF-8 locale if not already done.

See the contributor workflow document if you wish to build TruffleRuby from source.

Current Status

We recommend that people trying TruffleRuby on their gems and applications get in touch with us for any help they might need.

TruffleRuby runs Rails and is compatible with many gems, including C extensions. TruffleRuby is not 100% compatible with MRI 4.0 yet. Please report any compatibility issues you might find. TruffleRuby passes around 98% of ruby/spec, more than any other alternative Ruby implementation.

This is the beginning of the README. Read the rest at the original. Read the full README ↗