Repository files navigation

TruffleRuby is theGraalVM high-performance implementationof theRuby programming language.

TruffleRuby comes in two distributions:

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

You can install either of those:

• Via yourRuby manager/installer (RVM, rbenv, chruby, asdf, ruby-build, ruby-install).
  We recommend trying TruffleRuby dev builds which contain the latest fixes and improvements (replaceVERSION bydev).

Native Standalone:

RVM:    $ rvm install truffleruby# or truffleruby-headrbenv:  $ rbenv install truffleruby-VERSIONasdf:   $ asdf install ruby truffleruby-VERSIONchruby: $ ruby-install truffleruby        $ ruby-build truffleruby-VERSION~/.rubies/truffleruby-VERSION

JVM Standalone:

rbenv:  $ rbenv install truffleruby+graalvm-VERSIONasdf:   $ asdf install ruby truffleruby+graalvm-VERSIONchruby: $ ruby-install truffleruby-graalvm        $ ruby-build truffleruby+graalvm-VERSION~/.rubies/truffleruby+graalvm-VERSION

• In CI with GitHub Actions, seeTesting TruffleRuby in CI for more details and other CIs.

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

• Via Docker.For Native Standalone seeofficial release imagesandnightly images.For JVM Standalone there are no Docker images yet, but you can easilydownload it and take inspiration from theNative Standalone Dockerfiles.

• Manually, by following thedocumentation.

You can usegem andbundle to install gems, as usual.

Please report any issues you might find onGitHub.

TruffleRuby aims to:

• Run idiomatic Ruby code faster.
  • TruffleRuby is thefastest Ruby implementation for many CPU-intensive benchmarks.
• Run Ruby code in parallel.
  • TruffleRuby does not have a global interpreter lock and runs Ruby code 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.
  • Provided by GraalVM, see thePolyglot documentation.
• Provide new tooling, such as debuggers and monitoring, that works across languages.
  • Includes a profiler, debugger, VisualVM, and more. See theTools documentation.
• Provide all of the above while maintaining very high compatibility with the standard implementation of Ruby.

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

To find out which runtime configuration is being used, runruby --version on the command line,or check the value ofRUBY_DESCRIPTION orTruffleRuby.native? in Ruby code.Runtime configurations are further detailed inDeploying TruffleRuby.

TruffleRuby is actively tested on the following systems:

• Oracle Linux 7, 8, 9
• Ubuntu 18.04, 20.04, 22.04 (all LTS)
• Fedora 37, 38
• Debian 10, 11, 12
• macOS 11 (Big Sur)

Architectures:

• AMD64 (akax86_64): Supported
• AArch64 (akaarm64): Supported on Linux (from 21.2) and on macOS (from 22.2)

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

• make, gcc and g++ for building C and C++ extensions
• libssl for theopenssl C extension
• libyaml for thepsych C extension
• zlib for thezlib 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 aUTF-8 locale if not already done.

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

We recommend that people trying TruffleRuby on their gems and applicationsget 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 3.3 yet. Pleasereport any compatibility issues you might find.TruffleRubypasses around 97% of ruby/spec,more than any other alternative Ruby implementation.

Regarding performance, TruffleRuby isby farthe fastest Ruby implementation on theyjit-bench benchmark suite which includesrailsbench, etc.To achieve this performance TruffleRuby needs a fair amount of warmup, as other advanced JIT compilers do.If you find any performance issue, please seethis guide.

TruffleRuby is released at the same time as GraalVM.TruffleRuby continues to use the release numbering based on the calendar year, for example, 21.x, and 22.x., same as GraalVM prior to 2023.See therelease roadmap andthe upcoming releases list for the release dates and information about how long releases are supported.GraalVM Community Edition releases are supported at most one year.Longer support is available for Oracle GraalVM.

TruffleRuby should in most cases work as a drop-in replacement for MRI, but youshould read about ourcompatibility.

For many use cases TruffleRuby should work as a drop-in replacement for JRuby.However, our approach to integration with Java is different to JRuby so youshould read ourmigration guide.

Extensive user documentation is available indoc/user.

See oursource code repository andcontributor documentation to contribute to TruffleRuby.In particular, see thecontributor workflowdocument for how to build and run TruffleRuby.

The best way to get in touch with us is to join the#truffleruby channel onGraalVM Slack.You can also Tweet to@TruffleRuby, or emailbenoit.daloze@oracle.com.

Please report security vulnerabilities via the process outlined in thereporting vulnerabilities guide, rather than by something public such as a GitHub issue or a Gitter conversation.

Announcements about GraalVM, including TruffleRuby, are made on thegraal-dev mailing list.

The main authors of TruffleRuby ordered by first contribution are:Chris Seaton, Benoit Daloze, Kevin Menard, Petr Chalupa, Brandon Fish, Duncan MacGregor, Christian Wirth, Rafael França, Alan Wu, Nicolas Laurent, Carol Chen, Nikolay Sverchkov, Lillian Zhang, Tom Stuart, and Maple Ong.

SeeSECURITY for how to report security vulnerabilities to Oracle.For known vulnerabilities in Ruby, please refer to theknown-cves file.

TruffleRuby is copyright (c) 2013-2025 Oracle and/or its affiliates, and is madeavailable to you under the terms of any one of the following three licenses:

• Eclipse Public License version 2.0, or
• GNU General Public License version 2, or
• GNU Lesser General Public License version 2.1.

For further licensing information, seeLICENCE,3rd_party_licenses, anddoc/legal/legal.

TruffleRuby includes infrastructure code fromJRuby (e.g. JCodings, Joni), core library code from theRubinius project, as well as code from the standard implementation of Ruby,MRI.