Download specified version of EnergyPlus for your platform from GitHub and install it.

  ver = "latest",
  local = FALSE,
  dir = NULL,
  force = FALSE,
  portable = FALSE,


download_eplus(ver = "latest", dir, portable = FALSE)



The EnergyPlus version number, e.g., "8.7". For download_eplus() and install_eplus(), the special value "latest", which is the default, means the latest version supported by eplusr.


Whether to install EnergyPlus only for current user. For Windows and Linux, if FALSE, administrative privileges are required to install EnergyPlus to the default system-level location. See details. local should be also set to FALSE if you do not have the write access to the directory specified via dir. Default: FALSE. For macOS, administrative privileges are always required no matter you want EnergyPlus to be install at /Applications or ~/Applications.


A single string of directory.

  • For download_eplus(), where to save EnergyPlus installer file. Default: ".".

  • For install_eplus(), the installer will always be saved into tempdir(). But you can use dir to specify the parent directory of EnergyPlus installation, i.e. the parent directory of EnergyPlusVX-Y-0 on Windows and EnergyPlus-X-Y-0 on Linux and macOS. If NULL, the default installation path will be used. See details for more information. Please note that dir only works when on macOS and EnergyPlus will always be installed into the default location. Default: NULL.


Whether to install EnergyPlus even if it has already been installed. Setting to TRUE if you want to install the downloaded EnergyPlus anyway. Please note that this may results in multiple EnergyPlus installations of the same version at different locations. eplusr will only use the first EnergyPlus installation. Default: FALSE.


Whether to download the portable version of EnergyPlus. Only works for EnergyPlus v8.8 and above. Default: FALSE.


Other arguments to be passed to the installer. Current only one additional argument exists and is only for Linux:

  • dir_bin: A path where symbolic links will be created to the software executables. The default is /usr/local/bin if local is FALSE and ~/.local/bin if local is TRUE.


An invisible integer 0 if succeed. Moreover, some attributes will also be returned:

  • For install_eplus():

    • path: the EnergyPlus installation path

    • installer: the path of downloaded EnergyPlus installer file

  • For download_eplus():

    • file: the path of downloaded EnergyPlus installer file


download_eplus() downloads specified version of EnergyPlus from EnergyPlus GitHub Repository.

install_eplus() tries to install EnergyPlus into the default location, e.g. C:\EnergyPlusVX-Y-0 on Windows, /usr/local/EnergyPlus-X-Y-0 on Linux, and /Applications/EnergyPlus-X-Y-0 on macOS.

Note that installing to the default location requires administrative privileges and you have to run R with administrator (or with sudo if you are on Linux) to make it work if you are not in interactive mode.

If you can't run R with administrator, it is possible to install EnergyPlus to your home corresponding directory by setting local to TRUE.

The user level EnergyPlus installation path is:

  • Windows:

    • dir(Sys.getenv("LOCALAPPDATA"), "EnergyPlusVX-Y-0") OR

    • C:\Users\<User>\AppData\Local\EnergyPlusVX-Y-0 if environment variable "LOCALAPPDATA" is not set

  • macOS: /Users/User/Applications/EnergyPlus-X-Y-0

  • Linux: "~/.local/EnergyPlus-X-Y-0"

On Windows and Linux, you can also specify your custom directory using the dir argument. Remember to change local to FALSE in order to ask for administrator privileges if you do not have the write access to that directory. On macOS, dir only works when portable is set to TRUE.

Please note that when local is set to FALSE, no symbolic links will be created, since this process requires administrative privileges.

uninstall_eplus() tries to uninstall specified version of EnergyPlus located by eplusr. Similar as install_eplus(), administrative privileges may be required.


Hongyuan Jia


if (FALSE) {
# download the latest version of EnergyPlus
download_eplus("latest", dir = tempdir())
# install the latest version of EnergyPlus system-wide which is the default
# and requires administrative privileges

# for a specific version of EnergyPlus
download_eplus("8.8", dir = tempdir())

# force to reinstall
install_eplus("8.8", force = TRUE)

# install EnergyPlus in your home directory
install_eplus("8.8", local = TRUE, force = TRUE)

# custom EnergyPlus install home directory
install_eplus("8.8", dir = "~/MyPrograms", local = TRUE, force = TRUE)