Installation and setup
This page covers installing RiskScape using a zip file.
Warning
If RiskScape is already installed on your system, then follow the Upgrading RiskScape instructions instead.
Note
RiskScape is also available via a docker image. Please get in contact with the project team if you want to use docker.
Prerequisites
RiskScape currently requires a Java Runtime Environment of at least version 8 to run.
Warning
We recommend you have Java version 17 (or higher) installed on your computer. The next RiskScape release (v1.5.0) will require a minimum of Java 17 installed in order to run.
For instructions on installing Java on many Operating Systems refer to How to download and install pre-built Java packages.
After installation, use a terminal, Windows Command Prompt or PowerShell and run:
java -version
The result of this command should be similar to:
java version "17.x.y"
Java(TM) SE Runtime Environment (build 17...)
Java HotSpot(TM) 64-Bit Server VM (build 17..., mixed mode)
Tip
You may need administrator privileges to install Java, or for elsewhere in this guide where systems settings are edited. Check with your System Administrator if you hit a permissions problem.
Download the latest version of the RiskScape software
Download the latest RiskScape zip file.
Extract the downloaded zip file to your file system, e.g.
C:\RiskScape
Windows/opt/riskscape
Linux or Mac
Tip
You can install RiskScape into any directory location you want, but make sure
you adjust the file-path you use in subsequent instructions on this page.
We recommend you do not extract the riskscape.zip
directly into C:\Users\%USERNAME%\
as this may make upgrading RiskScape more complicated.
RiskScape can now be tested by entering the following commands (adjust the paths if necessary):
C:\RiskScape\riskscape\bin\riskscape.bat --help
Windows/opt/riskscape/riskscape/bin/riskscape --help
Linux or Mac
Make the RiskScape command available
The next step is to make RiskScape easier to run, so that we don’t have to specify the full executable path every time.
Update PATH
For convenience, you can add the riskscape/bin
directory to the system’s
path, by editing the PATH
environment variable.
Instead of typing out the full executable path, you can now just run riskscape
.
Below are examples of how to set the PATH
on various operating systems.
Tip
Refer here for more details on how to edit the PATH environment variable for various operating systems.
Linux and Mac
For example, a Linux user would do this by adding the following to their
~/.bashrc
file:
export "PATH=$PATH:/opt/riskscape/riskscape/bin/"
Adjust the /opt/riskscape/
location accordingly to match your installation directory.
Mac users would update the ~/.zshrc
file here instead of ~/.bashrc
.
You may need to create the ~/.zshrc
file if it does not exist, e.g. touch ~/.zshrc
.
Once you have saved the ~/.bashrc
(or ~/.zshrc
) file, open a new terminal and enter riskscape --help
to check that the
riskscape
command is now visible on your PATH
.
Windows
Windows users can use this PATH
approach too, instead of creating a shortcut script.
To set the PATH
on Windows:
Click on the Windows Start menu.
Start typing ‘command’.
Right click on the ‘Command Prompt’ application and select ‘Run as Administrator’.
Enter the following command to change the
PATH
permanently.setx PATH "%PATH%;C:\RiskScape\riskscape\bin"
Tip
If you do not have administrator privileges, or would prefer not to permanently alter your PATH
setting, you can create a small Desktop shortcut script instead.
Windows shortcut (alternative)
Instead of permanently changing your PATH
setting, you can add a small Desktop shortcut script that
will do this each time you want to use RiskScape.
Top-level project directory
As part of this script, we will open a command prompt in a top-level directory that will contain
all our RiskScape project directories. Our example will use C:\RiskScape_Projects\
for our top-level directory.
Under this top-level directory, you can use separate sub-directories as needed
to organize your RiskScape models (e.g. C:\RiskScape_Projects\getting-started\
).
A RiskScape project is the ‘working directory’ where you will run RiskScape commands from.
It should contain a plain-text project.ini
file, which you can create and edit in Notepad.
Tip
Running the shortcut will open the command prompt in the C:\RiskScape_Projects\
directory.
From there, you then use the cd DIRECTORY_NAME
command to change to
the sub-directory you want to work on. Alternatively, you could hard-code a specific project directory
directly into your shortcut, e.g. cd C:\RiskScape_Projects\getting-started
.
The following examples are for either Windows Command Prompt or PowerShell, depending on what you feel more comfortable using.
Windows Command prompt shortcut
To create a Desktop shortcut for running RiskScape from a Windows command prompt:
Create a top-level directory to keep your RiskScape projects in, if needed, e.g.
C:\RiskScape_Projects\
.Open Notepad.
Paste in the following. Adjust the first line to match your project directory
and theset PATH
line to match your installation directory.cd C:\RiskScape_Projects\ @echo off set PATH=%PATH%;C:\RiskScape\riskscape\bin cmd -c
Save the file to your desktop as
RiskScape Shortcut.bat
. Make sure you change ‘Save as type’ to ‘All files’.Test the shortcut works. Go to your desktop and double-click on it.
A command prompt should open. Typeriskscape --help
and check it works.
PowerShell shortcut
Alternatively, if you prefer using the PowerShell prompt, to create a Desktop shortcut for RiskScape:
Create a top-level directory to keep your RiskScape projects in, if needed, e.g.
C:\RiskScape_Projects\
.Open Notepad.
Paste in the following. Adjust the
$env:Path
line to match your installation directory.cd C:\RiskScape_Projects\ $env:Path += ';C:\RiskScape\riskscape\bin' powershell
Save the file to your desktop as
RiskScape Shortcut.ps1
. Make sure you change ‘Save as type’ to ‘All files’.Test the shortcut works. Go to your desktop, right-click on it and select ‘Run with PowerShell’.
A PowerShell prompt should open. Typeriskscape --help
and check it works.
Installing a GIS application
We recommend that you have also a GIS application installed on your system that you can use to view GIS data, such as shapefiles and GeoTIFF files. This will help to visualize the RiskScape input and output data.
Common GIS applications include QGIS and ArcGIS.
Note
There are some known interoperability issues with shapefile projections in ArcGIS. If your preferred GIS application is ArcGIS, then refer to Workarounds for ArcGIS for more details.
You can download QGIS from here.
Note
Follow the QGIS instructions carefully. Mac users, pay attention to the note in the QGIS instructions about security rules.
QGIS has a lot of online documentation on how to use it and how to work with GIS data. You should also be able to find many ‘how to’ videos for using QGIS online.