You have several options when setting up a Ruby-enabled, OpenStudio SDK environment on a Windows PC (e.g. virtualization vs emulation vs containerization), depending in large part on intended use (e.g. occasional measure development vs E+ workhorse). These instructions target energy modellers/developers wishing to interact with OpenStudio's API using Windows 11 WSL2, all the while maintaining compatibility with suggested Docker Desktop environments (keeping options open). The instructions here refer to SDK version 3.6.1 - adapt the instructions for older or newer versions!
The favoured approach until 2020 was to rely on RubyInstaller for Windows, with the MSYS2 toolchain as a dev kit. OpenStudio SDK 3.6.1 requires Ruby 2.7.2, which is a few years old now. In 2020, there was a transition at MSYS2, which in turn spawned some notable installation issues. There are suggested workarounds for MSYS2, but these don't appear to have made their way to the (older) v2.7 RubyInstaller packages. It's likely that this is no longer an issue for more recent Ruby versions like 3.0. But for OpenStudio 3.6.1 users needing Ruby 2.7.2, RubyInstaller may have lost its appeal as a 1-stop solution.
As an alternative, you may wish to install a full Linux distro on WSL2. Once installed and updated, it'll take up to 3 GB of disk space (compared to ~1 GB for RubyInstaller + DevKit). You're however getting a complete (and faster) Linux distribution under the hood. The following steps are taken either directly from Microsoft's own WSL instructions or Docker instructions, albeit somewhat harmonized and simplified. Hopefully, you can deploy the following steps glitch-free.
Consider upgrading PowerShell to 7.3. (the .msi package is fine for most cases). Once upgraded, open a PowerShell as Administrator. Check if WSL (1 or 2) has already been enabled:
wsl -l -v
This lists any previously running WSL setups (including Docker), as well as the enabled WSL version. If WSL hasn't yet been enabled:
wsl --install
This may actually install Ubuntu for you as the default Linux distro.
You may need to set your Linux username & password early on in the process. These are NOT (!!!) the same as your Windows username & password! Your Linux username remains a key variable for the rest of these instructions: here, "bill" (instead of e.g. "user") is used throughout this document as a proxy for your own Linux username - adapt!
Next, install the Linux kernel update package. Then, ensure WSL2 is enabled by default:
wsl --set-default-version 2
Rebooting may be required (possibly a few times). Once completed and rebooted, launch PowerShell again and run:
ubuntu
... which should switch over to a Ubuntu Linux environment (while in the same Powershell). You can check which Ubuntu version (e.g. 22.04) you're running:
lsb_release -a
If either of these commands fail, or if you're not running the Ubuntu version you're after, simply exit or quit, and install Ubuntu (e.g. from the Microsoft Store). Once completed, try again ubuntu (you should have gotten a "Welcome to Ubuntu" message at some point), then lsb_release -a. You're running Ubuntu, which should appear under "Linux" in Windows Explorer.
If you're getting a landscape-sysinfo.cache: Permission denied error (a WSL/Ubuntu mismatch thingy), try:
sudo apt remove landscape-common
sudo apt autoremove
rm ~/.motd_shown
Quit Ubuntu, then relaunch - the message should no longer appear.
Update and upgrade the base Ubuntu installation:
sudo apt update && sudo apt upgrade
Go get yourself an espresso. Before you go, let's break down the preceding (2x) instructions:
- sudo: As a Linux user with administrator credentials, you can launch critical root commands (Linux password required) by preceding them with
sudo. Ubuntu will warn you if a command needs sudo authorization. - apt: Each Linux distro (e.g. Ubuntu, Gentoo) comes with its own solution to ensure safe installation/management of packages and (shared) dependencies.
- update: first, apt update the list of upgradable packages
- upgrade: then, apt upgrade them
You're done. Welcome to Ubuntu!
In a ubuntu session and type:
ruby -v
With a freshly installed Ubuntu 22.04, you may see "Ruby 3.0" - a system Ruby that comes with Ubuntu. Any Linux utility requiring Ruby would likely depend on this system Ruby. OpenStudio 3.6.1 instead requires Ruby 2.7.2. It is NOT a good idea to reset system Ruby (let Ubuntu developers decide that in due course). You're better off installing Ruby 2.7.2 locally for your own projects, which will inevitably need upgrading in the near future (OpenStudio will migrate to Ruby 3.0 at some point). This will not affect system Ruby or the Ubuntu operating system. Yet this all means you'll need to manage (multiple) Ruby versions safely, using a Ruby version manager like rbenv. Installing rbenv using Ubuntu's apt manager is NOT recommended for Ruby 2.7.2. Use Homebrew instead.
Fetch and run Homebrew's installation script (a one-liner):
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
Apply Homebrew's suggested user configuration instructions at the end of the installation. Once again, adapt the instructions to your own Linux username and set up, e.g. "/home/bill/.profile" (NOT Homebrew's suggested "/home/user/.profile").
Homebrew may also recommend brew install gcc before running brew doctor at the end. Some users have had mixed results. A subsequent failed brew postinstall gcc does not seem to hinder the remaining steps.
Either source ~/.profile or exit/relaunch ubuntu. Then:
brew install rbenv
rbenv init
rbenv install 2.7.2
rbenv local 2.7.2
echo 'eval "$(rbenv init - bash)"' >> /home/bill/.profile
ruby -v
You should now see "2.7.2" (if everything went well): this version will be used for all Ruby-related work under your Linux home directory (and recursively under any of its subdirectories). Ensure:
bundler -v
... returns 2.1.4. Bundler is key to building Ruby scripts and OpenStudio Measures.
Check if both system and local Ruby versions can safely communicate with RubyGems.org:
cd /
ruby -ropen-uri -e 'eval URI.open("https://git.io/vQhWq").read'
cd ~
ruby -ropen-uri -e 'eval URI.open("https://git.io/vQhWq").read'
If successful, one should get a Hooray! from both Ruby versions.
In this setup, we're installing OpenStudio under Linux, not Windows. Like many specialized Linux applications, one cannot simply sudo apt install openstudio. Download its .deb (Debian) file under a new "deb" folder:
mkdir deb
cd deb
curl -fLO https://github.com/NREL/OpenStudio/releases/download/v3.6.1/OpenStudio-3.6.1+bb9481519e-Ubuntu-20.04-x86_64.deb
Adapt to your architecture (if other than x86, like ARM). Wait for the download to complete, then:
sudo dpkg -i OpenStudio-3.6.1+bb9481519e-Ubuntu-20.04-x86_64.deb
... should end with "Setting up openstudio-3.6.1 (3.6.1) ...".
openstudio openstudio_version
... should report the right OpenStudio CLI version, while:
energyplus -v
... likely suggests a missing PATH to locate the EnergyPlus CLI binary (or executable) that came with OpenStudio. Do:
echo 'PATH="/usr/local/openstudio-3.6.1/EnergyPlus:$PATH"' >> /home/bill/.profile
Make sure the PATH above matches your current setup. Once again, replace "bill" with your own Linux username. Relaunch a Ubuntu session to ensure both openstudio openstudio_version and energyplus -v are successful. You now have access to the OpenStudio and EnergyPlus binaries - yet NOT the OpenStudio Ruby environment, required to interact with its API.
Create a new local Ruby file that points to the main OpenStudio Ruby file:
cd ~
touch .rbenv/versions/2.7.2/lib/ruby/site_ruby/openstudio.rb
echo 'require "/usr/local/openstudio-3.6.1/Ruby/openstudio.rb"' >> .rbenv/versions/2.7.2/lib/ruby/site_ruby/openstudio.rb
ruby -e "require 'openstudio'" -e "puts OpenStudio::Model::Model.new"
... should confirm that your Ruby code can NOW interact with OpenStudio Ruby bindings. You're good to go!
- Ubuntu + WSL2 + Windows 10
- Luis Lara's great LinkedIn post
- Ruby + OpenStudio SDK installation on MacOS (much easier)
(September 2022, updated October 2023)