# IRuby and the Ruby kernel that Jupyter was missing > IRuby is the Ruby kernel for Jupyter, a gem that lets a notebook drive Ruby code through ZeroMQ while IRB or Pry handles execution. It is aimed at scientists and data analysts who want Ruby in a notebook environment rather than a separate plotting stack. **SciRuby/iruby** — Official gem repository: Ruby kernel for Jupyter/IPython Notebook - Repository: https://github.com/SciRuby/iruby - Website: https://github.com/SciRuby/iruby - Stars: 926 · Forks: 35 - Language: Ruby - License: MIT - Published: 2026-10-20 · Updated: 2026-10-20 · Language: en - Canonical page: https://hysenlabs.com/projects/sciruby-iruby ## A Ruby kernel for the Jupyter notebook protocol Jupyter is a front end for interactive computing, and it only works with a language if a kernel speaks the protocol behind the notebook. Python has one, R has one, Julia has one. Ruby did not have an official one, and IRuby fills that gap. The project describes itself in one line as a Ruby kernel for the Jupyter project, and the repository is the official gem repository for it. The language is Ruby, the licence is MIT, and the topics attached to the repository are interactive, jupyter, repl and ruby. The interesting design decision is what sits between the notebook and your code. Jupyter's kernel architecture expects the kernel process to talk to the front end over a socket, and the established Ruby way to do that is ZeroMQ. IRuby uses that transport, with ffi-rzmq and libzmq listed as requirements that are installed automatically, and the ZeroMQ binding is the reason the gem has native dependencies on every platform. Underneath, the actual code execution goes through an ordinary Ruby REPL. That is what the backend section describes, and it is why IRuby behaves like a Ruby session rather than like a script runner. ## PlainBackend and PryBackend, and switching between them at runtime There are two backends, and the choice is one of the few runtime decisions you can make in a notebook. PlainBackend is the default and it uses IRB, the Ruby standard library console. PryBackend uses Pry instead, and Pry is an optional dependency that you install only if you want it. The switch is a single call on the kernel instance. ```bash IRuby::Kernel.instance.switch_backend!(:pry) ``` That the switch is possible at all is worth noticing. It means the backend is a replaceable component rather than a fixed build decision, so a notebook can start on IRB and move to Pry when you want the better inspection experience, without reinstalling the gem or changing kernels. The practical difference between the two is the console you already know. IRB is present on every Ruby install, so PlainBackend has no extra dependency at all. Pry is a third party gem that you have to install deliberately, and the documentation lists it as optional precisely so that the default path stays dependency free. ## Installing on Ubuntu and Fedora with the system requirements gem The installation instructions are per platform, and the Ubuntu route is the most complete of them, aimed at Ubuntu 22.04 and later. ```bash sudo apt install libtool libffi-dev ruby ruby-dev make gem install --user-install rubygems-requirements-system gem install --user-install iruby iruby register --force ``` The first line installs the build tools and headers. The gem install of rubygems-requirements-system is a step people skip, and skipping it is why a fresh install often fails to find a prebuilt native gem and falls back to compiling from source. The last command is the one people forget. `iruby register --force` writes a kernel specification into the Jupyter kernel directory so that the notebook front end can find a Ruby kernel at all. Until you run it, Jupyter has no Ruby to offer. Fedora follows the same shape with dnf and an extra zeromq-devel package. ```bash sudo dnf install ruby ruby-dev make zeromq-devel gem install --user-install rubygems-requirements-system gem install --user-install iruby iruby register --force ``` The difference between the two is the ZeroMQ development headers, which Fedora splits out into its own package and Ubuntu ships under a different name. ## macOS, Windows and the container route On macOS the documentation asks you to install Ruby through rbenv or rvm, and to install Jupyter, then offers two paths. The Homebrew route is the short one. ```bash gem install rubygems-requirements-system gem install iruby iruby register --force ``` The MacPorts route adds the autotools packages that a source build of the native extension needs. ```bash port install libtool autoconf automake autogen gem install rubygems-requirements-system gem install iruby iruby register --force ``` On Windows the requirement is the DevKit, which is necessary for building RubyGems with native C-based extensions. Once that is in place the sequence is short. ```bash gem install iruby iruby register --force ``` There is also a container route that skips native installation entirely, by using the RubyData Docker Stacks. ```bash docker run --rm -it -p 8888:8888 rubydata/datascience-notebook ``` That command publishes port 8888 and opens a notebook server with Ruby already present. For a team that does not want to manage Ruby toolchains per machine, it is the shortest path to a working notebook. ## The cztop deprecation and the session adapter environment variable There is one piece of configuration that deserves attention because it is a deprecation in progress, and the documentation is explicit about it. The CZTop adapter has been deprecated since IRuby version 0.7.4, and it will be removed after several versions. If you want to keep using IRuby with CZTop, you need to install CZTop and CZMQ alongside it. Which one wins is decided by what is installed. If both ffi-rzmq and cztop are present, ffi-rzmq is used. If you prefer cztop, you set an environment variable. ```bash export IRUBY_SESSION_ADAPTER="cztop" ``` This is a small thing, but it is a good illustration of the layer structure. The ZeroMQ session can be driven through two different Ruby bindings, the default being the one with automatic dependency installation, and the environment variable is the override for anyone who has a reason to prefer the older path. It is also a migration signal. A project that names a deprecation version and an environment variable override is telling you the default path is stable and the alternative is on its way out. ## JRuby, the development version, and how registration changes JRuby is supported as a separate installation path with its own requirements. You need JRuby version 9.0.4.0 or later and the iruby gem, and you must make sure your environment is set up to use jruby. ```bash env ruby -v ``` That command is how you confirm which Ruby the environment resolves to. If you use RVM, it is enough to switch the current version to jruby. The registration step matters more here than on MRI. The documentation states that if you have already used IRuby with a different version, you need to generate a new kernel. ```bash iruby register --force ``` The reason is that the kernel specification records the Ruby executable that was in place at registration time. Registering again with `--force` points it at the current interpreter. This is also why the `--force` flag appears in every platform recipe, not just the JRuby one. For working from source, the documentation points at specific_install, with a warning that the development version is usually unstable. ```bash gem specific_install https://github.com/SciRuby/iruby ``` The same registration command applies afterwards, since a development checkout still has to be pointed at by a kernel specification. ## Repository layout, licence and where the project stands The repository is a gem rather than an application, so the layout is small. The top level holds the gemspec file iruby.gemspec, a Gemfile, a Rakefile, the lib directory with the kernel implementation, an exe directory for the command line entry point, a test directory, a CHANGES.md file, the LICENSE file and the logo. The copyright line reads IRuby contributors and the Ruby Science Foundation, and the code is licensed under the MIT licence. For a gem that other people install from a package registry, MIT is the least obstructive choice available, and the copyright attribution is worth preserving if you fork it. There is a governance note for returning contributors that is easy to miss and matters if you plan to send a pull request. In February 2021 IRuby became the canonical repository and is no longer a fork from minrk/iruby, and the documentation asks former contributors to fork from this repository again before making pull requests. Repositories that change hands tend to accumulate stale forks, and this is the fix. On activity, the last push was on 2026-06-30 and the repository is not archived. The recent releases are v0.8.3 from 2026-06-30, v0.8.2 from 2026-06-06 and v0.8.1 from 2025-02-16. The version sits below 1.0, so the interface can still move between minor versions, and the gap between v0.8.1 and v0.8.2 is a long one, which suggests the 0.8 line took a while to settle. ## Conclusion Adopt IRuby if your work is in Ruby and you want notebook cells, inline plotting and a single environment for analysis rather than a separate script and plotting pipeline. Skip it if you are on a language that already has a maintained Jupyter kernel, or if you cannot install native build tooling, because the gem pulls in ffi-rzmq and libzmq and needs a compiler on most platforms. Before installing, check the platform section for your system and confirm that the gem version you install matches the Jupyter version you run, since the kernel protocol is the part that breaks when the two drift apart. ## FAQ ### How do I install IRuby and make Jupyter see a Ruby kernel? Install the gem and then register the kernel. On Ubuntu 22.04 or later the sequence is gem install --user-install rubygems-requirements-system, gem install --user-install iruby, then iruby register --force. The register step is what writes the kernel specification Jupyter looks for. ### What does IRuby need in order to run? Jupyter is the requirement, and ffi-rzmq and libzmq are installed automatically because the kernel talks to the front end over ZeroMQ. Pry is optional and only needed if you want the PryBackend instead of the default PlainBackend. ### How do I switch IRuby to use Pry instead of IRB? Run IRuby::Kernel.instance.switch_backend!(:pry) in a notebook cell. PlainBackend, which uses IRB, is the default, and Pry must be installed separately for the Pry backend to be available. ### Is the cztop adapter still supported by IRuby? The CZTop adapter has been deprecated since IRuby version 0.7.4 and will be removed after several versions. If both ffi-rzmq and cztop are installed, ffi-rzmq is used, and setting the IRUBY_SESSION_ADAPTER environment variable to cztop selects cztop instead. ## Sources - [License: MIT](https://github.com/SciRuby/iruby/blob/master/LICENSE) - [Project website](https://github.com/SciRuby/iruby) - [README](https://github.com/SciRuby/iruby/blob/master/README.md) - [Releases](https://github.com/SciRuby/iruby/releases) - [SciRuby/iruby on GitHub](https://github.com/SciRuby/iruby) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/sciruby-iruby