2. Installation

This page describes how to install the new TUFLOW Viewer released as part of the 2026.0.0 TUFLOW Plugin for QGIS. The Quick Start Guide page provides a quick overview of how to get started with the new viewer.

2.1 QGIS¶

2.1.1 Supported QGIS Versions¶

There isn't a definitive answer to the minimum version of QGIS required to use the TUFLOW Viewer as it depends on how QGIS was installed and what operating system is being used. As a general guideline, it is recommended to use at least QGIS 3.38, or QGIS 3.34.13 LTR if using long term release builds.

The limiting factor is typically the 2.1.2 Python environment that is bundled with QGIS, however some functionality depends on more recent QGIS API.

Users can download QGIS from the official QGIS website. It is also possible to install QGIS via the OSGeo4W installer, however it is important to ensure that the required Python libraries are checked on during the installation steps as they are off by default in this method.

Note, the TUFLOW Viewer is supported in both the current stable QGIS 3.x builds and in the experimental Qt6 builds. It is also available in QGIS 4.x.

2.1.2 Python Environment¶

QGIS includes its own embedded Python environment with a number of external dependencies already installed. However, there are some minimum Python requirements which are required to use the TUFLOW Viewer that are mostly affected by the QGIS version or how QGIS was installed.

The TUFLOW Viewer requires Python 3.9 or later and the pandas library to be available (the latter is typically the limiting factor) and it is also recommended to have the netCDF4 library installed. It is possible to install pandas on older QGIS versions using the OSGeo4W Shell command window by running the setup utility (search "osgeo4w shell" under the start menu, enter "setup" in the shell and press return, then follow similar steps as this guide starting at Step 3: QGIS_Installation_with_OSGeo4W). However, upgrading to the latest version of QGIS or the latest QGIS LTR is the easiest method and recommended.

It is possible to check what version of Python is installed and if pandas and other recommended Python libraries are available by using the TUFLOW Plugin About dialogue:

Note: The above section focuses mainly on the Windows operating system. Installation of Python dependencies will be different on Linux and MacOS.

2.2 Installing and Switching to the New TUFLOW Viewer¶

2.2.1 Installation¶

The new TUFLOW Viewer is available in the 2026.0.0 TUFLOW Plugin release. To get access to the new viewer, ensure that the latest version of the plugin is installed:

• Open QGIS
• In the top menu, select Plugins ► Manage and Install Plugins...
• Search for "TUFLOW" in the search bar
• Install or upgrade to the latest version of the plugin

2.2.2 Switching to the New TUFLOW Viewer¶

TUFLOW Viewer is currently an opt-in feature and is not enabled by default. It is also mutually exclusive with the legacy TUFLOW Viewer (i.e. only one viewer can be active at a time). To switch to the new viewer, please follow the steps below.

1. Under the TUFLOW Plugin menu, check on the TUFLOW Viewer V2 option to enable the new viewer
   
2. To confirm if the new viewer has been activated (and the legacy viewer deactivated), check for the TUFLOW Viewer icon in the TUFLOW toolbar which will be replaced with the time-series icon for the new TUFLOW Viewer
   

Note, any open results loaded with the legacy TUFLOW Viewer will need to be closed and re-opened with the new viewer.