# PicoRuby, a Ruby that fits on a microcontroller

> PicoRuby is an alternative mruby implementation written in C, small enough to run in 512 KB of RAM or less and in 128 KB in its FemtoRuby build, with the Raspberry Pi Pico as its reference board. The naming changed in the 4.x line, the build is driven by rake with submodule dependencies, and the project ships several real firmware targets built on it.

**picoruby/picoruby** — PicoRuby is the smallest Ruby implementation for one-chip microcontrollers

- Repository: https://github.com/picoruby/picoruby
- Stars: 1,107 · Forks: 73
- Language: C
- License: MIT
- Published: 2026-10-19 · Updated: 2026-10-19 · Language: en
- Canonical page: https://hysenlabs.com/projects/picoruby-picoruby

## Two size targets, and a naming change to watch out for

PicoRuby is described as an alternative mruby implementation, and the two properties that define it are size and portability. On size, the footprint depends on the build configuration, with RAM of 512 KB or less for PicoRuby with networking and RAM of 128 KB or less for FemtoRuby. On portability, it depends only on a standard C library such as glibc, Newlib or Newlib-nano, and emcc, which is what lets the same source build for a microcontroller, for a POSIX host and for WebAssembly. The confusing part is the naming, and the README explains it directly. From version 4.x the artefacts are called PicoRuby, which used to be MicroRuby, for the mruby VM version, and FemtoRuby, which used to be PicoRuby, for the mruby/c VM version. So a tutorial written before 4.x that says PicoRuby may in fact be describing what is now called FemtoRuby, and the README notes that the mruby VM version is the one mainly being developed.

## The reference boards tell you the target

Two boards are named as reference microcontroller boards, and their specifications are a better guide to the project's intent than any benchmark. The first is the Raspberry Pi Pico 2 W, on an Arm Cortex-M33 with 520 KB of RAM and 4 MB of flash, with the CYW43 network module, which is the wireless variant of the chip that made the Pico family famous. The second is the original Raspberry Pi Pico, on an Arm Cortex-M0+ with 264 KB of RAM and 2 MB of flash. The numbers line up with the two size targets. The 128 KB FemtoRuby build fits comfortably on the original Pico, while the 512 KB PicoRuby build with networking needs the larger part of the Pico 2 W, and the presence of the wireless module in the reference board says that the networking build is a first class case rather than an afterthought. The primary language of the repository is C, which is the enabling decision for the whole footprint story.

## The dependency stack and the projects built on top

PicoRuby does not stand alone, and the README lists both what it depends on and what uses it. The dependencies are the PicoRuby compiler, picoruby/mruby-compiler2, used as the mruby compiler, picoruby/estalloc, the littlefs project for the filesystem, mruby itself and mruby/c. The users are more interesting. R2P2 is a PicoRuby shell system for the Raspberry Pi Pico, with a separate R2P2-ESP32 port for the ESP32, PicoRuby.wasm is a WASI runtime for WebAssembly published on npm as @picoruby/wasm-wasi, and PRK Firmware is keyboard firmware for the Pico. That last one is the clearest statement of what PicoRuby is for, since a keyboard firmware is a program that must run on the device with a fixed memory budget and no operating system underneath, and a Ruby that fits in 128 KB of RAM is exactly the shape of tool that makes that possible.

## Building it with rake and a checkout with submodules

The build is driven by rake, and the prerequisites are a C toolchain, git and Ruby, which should be CRuby 3.4 or later.

```console
git clone --recurse-submodules https://github.com/picoruby/picoruby
cd picoruby/
git submodule update --init --recursive # If you forgot --recurse-submodules when git clone
rake                    # same for `rake picoruby:prod`
rake picoruby:debug     # for debug build

bin/picoruby -e 'puts "Hello World!"'
```

The submodule step is not optional, since the compiler, the allocator and littlefs all come in as submodules. The rake tasks come in pairs, a prod build and a debug build, for each variant, with picoruby:prod and picoruby:debug for the VM version and femtoruby:prod and femtoruby:debug for the mruby/c version. On macOS there is an extra flag, because openssl is not linked in homebrew to avoid mixing with the system ssl, so the C and linker flags are pointed at the right locations.

```console
rake LDFLAGS=-L$(brew --prefix openssl@3)/lib CFLAGS=-I$(brew --prefix openssl@3)/include
```

Cross compilation is configured through a build config file, with the example given for the Pico 2. The rake build produces three binaries, bin/mrbc which compiles a .rb source file into .mrb VM code, bin/picoruby which executes Ruby the way the ruby command does, including the -e form, and bin/r2p2, the POSIX version of the shell system.

## A container for the cross toolchain

The repository includes a docker compose file, and its single service tells you what the hardest part of the build is. The service is named arm-none-eabi-tools and it runs the hasumikin/arm-none-eabi-tools image, which is the GNU Arm Embedded toolchain packaged for this purpose, with the repository mounted into the container at /picoruby on a cached volume, and a tty and stdin kept open so the session behaves like a shell. The command it runs is make docker_psoc5lp_lib, which is a target in the project's own makefiles for a particular silicon part, and the presence of a psoc5lp target in the container command is a reminder that this project builds for more than the two reference boards. The toolchain image is the practical answer to the most common build failure on a workstation, which is a missing or mismatched arm-none-eabi compiler.

## A four point line, a permissive licence and a grant funded start

The release history shows a project on a four point line that is still shipping. There is 4.0.3 on 2026-08-16, described as version 4 with the sl command, 4.0.4 on 2026-09-18, the EuRuKo 2026 Low Energy Edition, and 4.0.5 on 2026-09-29, a bug fix release. The tag titles are a nice illustration of how such a project is used, since a low energy edition is a firmware variant for a conference badge and the sl command is a shell utility, which is the sort of thing a Ruby on a microcontroller is for. The repository is not archived and the last push was on 2026-10-15. The licence is MIT, with the copyright held by HASUMI Hitoshi from 2020 and by Monstarlab for 2020 and 2021, and the acknowledgement section records that part of the project was coded by Monstarlab with support from the Ruby Association Grant Program in 2020 and 2021. The build side of the repository is a Rakefile with a minirake variant, a tasks/ directory, build_config/ for the cross build configurations, a Steepfile for type checking, an AGENTS.md and a Guardfile for the development loop.

## Conclusion

PicoRuby fits a hardware engineer who wants to write firmware in Ruby rather than in C, and it fits a team with an existing mruby codebase that needs a smaller or more portable target. It does not fit a project that expects a full Ruby implementation, since the point of the port is a subset sized for a microcontroller, and it does not fit a team that wants a single VM, because the 4.x line deliberately offers two with different trade-offs and the one being developed is the larger. Verify three things before you commit: which of the two variants you actually want, since the names swapped in 4.x and old tutorials will point at the wrong one, that your board's RAM and flash fit the variant you choose, and that the toolchain you need, the C compiler, git and CRuby 3.4 or later, is available on your build machine.

## FAQ

### What is PicoRuby?

It is an alternative mruby implementation written in C, designed for one-chip microcontrollers. Depending on the build configuration it needs 512 KB of RAM or less with networking, or 128 KB or less in the FemtoRuby build, and it depends only on a standard C library such as glibc, Newlib or Newlib-nano, and emcc.

### What is the difference between PicoRuby and FemtoRuby?

From version 4.x, PicoRuby is the mruby VM version, which used to be called MicroRuby, and FemtoRuby is the mruby/c VM version, which used to be PicoRuby. The mruby VM version is the one mainly being developed.

### How do I build PicoRuby from source?

You need a C toolchain, git and CRuby 3.4 or later. Clone with git clone --recurse-submodules, run git submodule update --init --recursive, then rake for a production build or rake picoruby:debug for a debug one, and run bin/picoruby -e 'puts "Hello World!"'. The FemtoRuby equivalents are rake femtoruby:prod and rake femtoruby:debug.

### Which boards is PicoRuby designed for?

The reference boards are the Raspberry Pi Pico 2 W, an Arm Cortex-M33 with 520 KB of RAM and 4 MB of flash with the CYW43 network module, and the original Raspberry Pi Pico, an Arm Cortex-M0+ with 264 KB of RAM and 2 MB of flash. Projects built on it include the R2P2 shell for the Pico, an ESP32 port, a WASI runtime on npm, and PRK keyboard firmware.

## Sources

- [Issues](https://github.com/picoruby/picoruby/issues)
- [License: MIT](https://github.com/picoruby/picoruby/blob/master/LICENSE)
- [picoruby/picoruby on GitHub](https://github.com/picoruby/picoruby)
- [README](https://github.com/picoruby/picoruby/blob/master/README.md)
- [Releases](https://github.com/picoruby/picoruby/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/picoruby-picoruby