This article provides step-by-step instructions on setting up a Ruby ecosystem via Ruby Version Manager (aka RVM) on a Ubuntu subsystem (Windows Subsystem for Linux, aka WSL) within the Microsoft Windows 10 operating system.

The instructions given should work for Windows 10 Home and Windows 10 Pro with both laptops and desktops inclusive.

Tested environment

WSL/Ubuntu subsystem on Windows 10 Home

  • Windows host: 21H1 (OS Build 19043.1165)

  • Linux kernel version: 4.4.0-19041-Microsoft

Ruby installation via RVM

RVM for Ubuntu

RVM is a command-line tool allowing you to manage multiple Ruby environments on your computer. RVM has a dedicated Ubuntu package, maintained by Josh Buker (https://github.com/rvm/ubuntu_rvm). In this article, we will install RVM via this PPA.

Start a WSL terminal and add the PPA repository by entering:

$ sudo apt-add-repository -y ppa:rael-gc/rvm

Update your Apt index and install the RVM package by:

$ sudo apt update && sudo apt install -y rvm

When the installation is complete, add your USER to the RVM group, and then restart the subsystem:

$ sudo usermod -a -G rvm $USER

Upon restart, add the following to your '~/.bashrc' file.

# RVM ##
source "/etc/profile.d/rvm.sh"

and then reread the '~/.bashrc' configuration using the source command:

$ source ~/.bashrc

Check the RVM installation by the version:

$ rvm -v
rvm 1.29.12 (manual) by Michal Papis, Piotr Kuczynski, Wayne E. Seguin [https://rvm.io]

Installing Ruby via RVM

Now you are ready to install the latest available Ruby. Enter from a WSL terminal:

$ rvm install ruby
Searching for binary rubies, this might take some time.
Found remote file https://rvm_io.global.ssl.fastly.net/binaries/ubuntu/20.04/x86_64/ruby-3.0.0.tar.bz2
Checking requirements for ubuntu.
Installing requirements for ubuntu.
Updating systemhawk password required for 'apt-get --quiet --yes update': ..-
.
Installing required packages: libncurses5-dev, libgmp-dev, libssl-dev......
Requirements installation successful.
ruby-3.0.0 - #configure
ruby-3.0.0 - #download
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100 26.7M  100 26.7M    0     0  4280k      0  0:00:06  0:00:06 --:--:-- 6812k
ruby-3.0.0 - #validate archive
ruby-3.0.0 - #extract
ruby-3.0.0 - #validate binary
ruby-3.0.0 - #setup
ruby-3.0.0 - #gemset created /usr/share/rvm/gems/ruby-3.0.0@global
ruby-3.0.0 - #importing gemset /usr/share/rvm/gemsets/global.gems..................................
ruby-3.0.0 - #generating global wrappers........
ruby-3.0.0 - #gemset created /usr/share/rvm/gems/ruby-3.0.0
ruby-3.0.0 - #importing gemsetfile /usr/share/rvm/gemsets/default.gems evaluated to empty gem list
ruby-3.0.0 - #generating default wrappers........
You need to enter your login password in the course of the above process.

When the installation is complete, check the installed Ruby version(s) by the rvm list command:

$ rvm list
=* ruby-3.0.0 [ x86_64 ]

# => - current
# =* - current && default
#  * - default

(Optional) Installing a previous release

In this article, we pretend that one of the Gem packages has an issue with the latest Ruby update. So, we practice installing an earlier "stable" Ruby release until the problem is gone.

You can list all the installable Rubies by entering:

$ rvm list known
# MRI Rubies
[ruby-]1.8.6[-p420]
[ruby-]1.8.7[-head] # security released on head
[ruby-]1.9.1[-p431]
[ruby-]1.9.2[-p330]
[ruby-]1.9.3[-p551]
[ruby-]2.0.0[-p648]
[ruby-]2.1[.10]
[ruby-]2.2[.10]
[ruby-]2.3[.8]
[ruby-]2.4[.10]
[ruby-]2.5[.8]
[ruby-]2.6[.6]
[ruby-]2.7[.2]
[ruby-]3[.0.0]
ruby-head

:

On noticing the previous release number — for example, 2.7[.x] in this exercise — feed it to the rvm install command:

$ rvm install 2.7
Searching for binary rubies, this might take some time.
Found remote file https://rvm_io.global.ssl.fastly.net/binaries/ubuntu/20.04/x86_64/ruby-2.7.2.tar.bz2
Checking requirements for ubuntu.
Requirements installation successful.
ruby-2.7.2 - #configure
ruby-2.7.2 - #download
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100 21.3M  100 21.3M    0     0  2357k      0  0:00:09  0:00:09 --:--:-- 3857k
ruby-2.7.2 - #validate archive
ruby-2.7.2 - #extract
ruby-2.7.2 - #validate binary
ruby-2.7.2 - #setup
ruby-2.7.2 - #gemset created /usr/share/rvm/gems/ruby-2.7.2@global
ruby-2.7.2 - #importing gemset /usr/share/rvm/gemsets/global.gems...............................
ruby-2.7.2 - #generating global wrappers........
ruby-2.7.2 - #gemset created /usr/share/rvm/gems/ruby-2.7.2
ruby-2.7.2 - #importing gemsetfile /usr/share/rvm/gemsets/default.gems evaluated to empty gem list
ruby-2.7.2 - #generating default wrappers........

Check the installed Rubies along with their respective status:

$ rvm list
=> ruby-2.7.2 [ x86_64 ]
 * ruby-3.0.0 [ x86_64 ]

# => - current
# =* - current && default
#  * - default

The above rvm install 2.7 command not only installed this specific version — here, Ruby 2.7[.2] — but also made it the "current" version for the current terminal session (i.e. it ran the command rvm use 2.7 silently).

If you plan to use this specific version for the time being — i.e. not just for the current terminal session — you need to make it the "default" Ruby:

$ rvm --default use 2.7
Using /home/hawk/.rvm/gems/ruby-2.7.2
$ rvm list
=* ruby-2.7.2 [ x86_64 ]
   ruby-3.0.0 [ x86_64 ]

# => - current
# =* - current && default
#  * - default

Later, when the issue is gone, you can delete the obsolete version, first by resetting the default Ruby to the latest:

$ rvm --default use 3.0
Using /home/hawk/.rvm/gems/ruby-3.0.0
$ rvm list
   ruby-2.7.2 [ x86_64 ]
=* ruby-3.0.0 [ x86_64 ]

# => - current
# =* - current && default
#  * - default

and then by running the rvm remove command:

$ rvm remove 2.7
ruby-2.7.2 - #removing rubies/ruby-2.7.2..
ruby-2.7.2 - #removing gems....
ruby-2.7.2 - #removing wrappers....
ruby-2.7.2 - #removing environments....
Using /usr/share/rvm/gems/ruby-3.0.0

Note that a similar command rvm uninstall just deletes the corresponding folder under '~/.rvm/rubies' while leaving everything else. Use rvm remove for clean up most of the install of a Ruby version.

Gem Environment

Various Ruby applications are available as Ruby "Gems", which you can search from https://rubygems.org/.

snip0102

To get the summary of your current Gem environment, enter from a terminal:

$ gem environment
RubyGems Environment:
  - RUBYGEMS VERSION: 3.2.3
  - RUBY VERSION: 3.0.0 (2020-12-25 patchlevel 0) [x86_64-linux]
  - INSTALLATION DIRECTORY: /usr/share/rvm/gems/ruby-3.0.0
  - USER INSTALLATION DIRECTORY: /home/hawk/.local/share/gem/ruby/3.0.0
  - RUBY EXECUTABLE: /usr/share/rvm/rubies/ruby-3.0.0/bin/ruby
  - GIT EXECUTABLE: /usr/bin/git
  - EXECUTABLE DIRECTORY: /usr/share/rvm/gems/ruby-3.0.0/bin
  - SPEC CACHE DIRECTORY: /home/hawk/.local/share/gem/specs
  - SYSTEM CONFIGURATION DIRECTORY: /etc
  - RUBYGEMS PLATFORMS:
     - ruby
     - x86_64-linux
  - GEM PATHS:
     - /usr/share/rvm/gems/ruby-3.0.0
     - /usr/share/rvm/rubies/ruby-3.0.0/lib/ruby/gems/3.0.0
  - GEM CONFIGURATION:
     - :update_sources => true
     - :verbose => true
     - :backtrace => false
     - :bulk_threshold => 1000
  - REMOTE SOURCES:
     - https://rubygems.org/
  - SHELL PATH:
     - /usr/share/rvm/gems/ruby-3.0.0/bin
     - /usr/share/rvm/gems/ruby-3.0.0@global/bin
     - /usr/share/rvm/rubies/ruby-3.0.0/bin
     - /usr/share/rvm/bin
     - /usr/local/sbin
     - /usr/local/bin
     - /usr/sbin
     - /usr/bin
     - /sbin
     - /bin
     - /usr/games
     - /usr/local/games
     - /mnt/c/Program Files/WindowsApps/CanonicalGroupLimited.UbuntuonWindows_2004.2021.825.0_x64__79rhkp1fndgsc
     - /mnt/c/Program Files (x86)/Common Files/Oracle/Java/javapath
     - /mnt/c/Windows/system32
     - /mnt/c/Windows
     - /mnt/c/Windows/System32/Wbem
     - /mnt/c/Windows/System32/WindowsPowerShell/v1.0
     - /mnt/c/Windows/System32/OpenSSH
     - /mnt/c/Users/hawk/AppData/Local/Microsoft/WindowsApps
     - /snap/bin

To list locally installed Gem packages, use the gem list command:

$ gem list
*** LOCAL GEMS ***

abbrev (default: 0.1.0)
base64 (default: 0.1.0)
benchmark (default: 0.1.1)
bigdecimal (default: 3.0.0)
bundler (default: 2.2.3)
bundler-unload (1.0.2)
cgi (default: 0.2.0)
csv (default: 3.1.9)
date (default: 3.1.0)
debug (default: 0.1.0)
delegate (default: 0.2.0)
did_you_mean (default: 1.5.0)
digest (default: 3.0.0)
drb (default: 2.0.4)
english (default: 0.7.1)
erb (default: 2.2.0)
etc (default: 1.2.0)
executable-hooks (1.6.1)
fcntl (default: 1.0.0)
fiddle (default: 1.0.6)
fileutils (default: 1.5.0)
find (default: 0.1.0)
forwardable (default: 1.3.2)
gdbm (default: 2.1.0)
gem-wrappers (1.4.0)
getoptlong (default: 0.1.1)
io-console (default: 0.5.6)
io-nonblock (default: 0.1.0)
io-wait (default: 0.1.0)
ipaddr (default: 1.2.2)
irb (default: 1.3.0)
json (default: 2.5.1)
logger (default: 1.4.3)
matrix (default: 0.3.1)
minitest (5.14.2)
mutex_m (default: 0.1.1)
net-ftp (default: 0.1.1)
net-http (default: 0.1.1)
net-imap (default: 0.1.1)
net-pop (default: 0.1.1)
net-protocol (default: 0.1.0)
net-smtp (default: 0.2.1)
nkf (default: 0.1.0)
observer (default: 0.1.1)
open-uri (default: 0.1.0)
open3 (default: 0.1.1)
openssl (default: 2.2.0)
optparse (default: 0.1.0)
ostruct (default: 0.3.1)
pathname (default: 0.1.0)
power_assert (1.2.0)
pp (default: 0.1.0)
prettyprint (default: 0.1.0)
prime (default: 0.1.2)
pstore (default: 0.1.1)
psych (default: 3.3.0)
racc (default: 1.5.1)
rake (13.0.3)
rbs (1.0.0)
rdoc (default: 6.3.0)
readline (default: 0.0.2)
readline-ext (default: 0.1.1)
reline (default: 0.2.0)
resolv (default: 0.2.0)
resolv-replace (default: 0.1.0)
rexml (3.2.4)
rinda (default: 0.1.0)
rss (0.2.9)
rubygems-bundler (1.4.5)
rvm (1.11.3.9)
securerandom (default: 0.1.0)
set (default: 1.0.1)
shellwords (default: 0.1.0)
singleton (default: 0.1.1)
stringio (default: 3.0.0)
strscan (default: 3.0.0)
syslog (default: 0.1.0)
tempfile (default: 0.1.1)
test-unit (3.3.7)
time (default: 0.1.0)
timeout (default: 0.1.1)
tmpdir (default: 0.1.1)
tracer (default: 0.1.1)
tsort (default: 0.1.0)
typeprof (0.11.0)
un (default: 0.1.0)
uri (default: 0.10.1)
weakref (default: 0.1.1)
yaml (default: 0.1.1)
zlib (default: 1.1.0)

After you have had your Ruby ecosystem set up, you can install any Gem packages simply using the gem install command. For example, to install Asciidoctor, enter from a terminal:

$ gem install asciidoctor

When upgrading a Gem package, use gem update and not gem install:

$ gem update asciidoctor

If you accidentally used gem install, it will end up having both versions installed. If that happens, remove the older version using the gem cleanup command:

$ gem cleanup asciidoctor