Documentation is available in the next section of this website, however please make use of our user groups if you get stuck or run into an issue.
Because there are distinct pieces to SWAT+, we have created user groups for each. Please identify which area you are having difficulty with and choose the appropriate group:
QSWAT+ user group For issues defining your watershed in QGIS and using the QSWAT+ plugin.
SWAT+ Editor user group For issues related to the editor interface.
SWAT+ model user group For questions and discussion related to the model itself, not the editor or GIS interfaces.
SWAT+ Toolbox is designed to work with the SWAT+ model. You can use it for sensitivity analysis, model calibration, evaluation, and validation. The software is currently only available on Windows. There are built-in updates through which more features, functionalities and bug fixes will be delivered. Check for updates as soon as you install. Check the user documentation here.
For SWAT+ Editor bugs or technical issues, report to the user groups or the Bitbucket issue tracker. However, please use this only for Editor software problems, and continue to use the google group for data-related issues.
Before contacting support, please read through our list of common issues to see if there is a simple solution already posted.
The Linux release was tested on Ubuntu 22.04 LTS, and MacOS was tested on Ventura. Please let us know if you test on a different OS version or Linux distribution and have any issues.
Your Linux distribution may have a QGIS package as part of its standard collection. Provided it is QGIS 3.16 version or later (not QGIS 2) you will be OK using it, and you can use the standard package management system to install it. The instructions that follow here are an alternative for obtaining the latest long term release of QGIS, currently 3.28.
Start by going to the QGIS download page and selecting Linux. Follow the instructions for your distribution. Note the instructions on the QGIS page include installing qgis-plugin-grass, but this is not necessary for QSWAT+, i.e. the install command needed is merely sudo apt install qgis
(though Ubuntu seemed to install GRASS anyway).
Install QSWAT+ using the swatplus-linux-installer from the installation page. This takes the form of a compressed tar archive. Save it somewhere, open a terminal and cd to the directory it is saved in. Use the command tar -xvf swatplus-linux-installer.tgz
to unpack the tar file. You then decide whether to install it just for you, or for everyone. In the first case it will only be available to the user who installs it. In the second case it will be available to any user, but will require the root user password to install. To take the first option, use the command ./installforme.sh
and to take the second option use the command sudo ./installforall.sh
This will install the QSWAT+ plugin for QGIS, in the user's personal files with the first option, and within the QGIS installation with the second option. It also installs the SWAT+ Editor and other tools and data in the SWATPlus directory. With the first option, SWATPlus is ~/.local/share/SWATPlus
(where ~ is the user's home directory) and with the second option it is /usr/local/share/SWATPlus
. There are also shell scripts uninstallforme.sh and unistallforall.sh for uninstalling.
The TauDEM executables used for watershed delineation by QSWAT+ can run in multiprocessing mode, using MPI (Message Passing Interface). Unfortunately, they need MPI to be installed even if the user chooses not to use MPI. The usual version of MPI for Linux is openmpi, and in Ubuntu, for example, running the command sudo apt-get install openmpi-bin
in a terminal will install openmpi or tell you it is already installed.
Obtain QGIS from the download page, selecting Download for macOS and then QGIS 3.28 LTR, the one described as the most stable version. This will give you a .dmg file, Open it, agree to the license, and you get a small window with a QGIS symbol and an Applications symbol. Drag the QGIS symbol onto the Applications symbol. This places QGIS in your Applications folder, and takes a few minutes. When you open QGIS in MacOS 10.15 (Catalina) you get a response that it cannot be opened because Apple cannot check it for malicious software. Click the Show in Finder button, and then instead of left clicking on QGIS, right click (or hold Ctrl while you click) on QGIS and then choose Open. The same warning about malicious software appears, but this time there is an Open button that you click to start QGIS. Thereafter QGIS will open normally.
The TauDEM software used to do watershed delineation in QSWAT+ is linked dynamically to openmpi, so this needs to be installed. This is most easily achieved by running in a terminal the command sudo brew install openmpi
The instructions new vary according to whether you have a Mac with an Intel processor or an Arm processor (also called M1 or M2)
Install QSWAT+ using the swatplus-mac-installer from the installation page. This takes the form of a compressed tar archive. Save it somewhere, open a terminal and cd to the directory it is saved in. Use the command tar -xvf swatplus-mac-installer.tgz
to unpack the tar file. cd to swatplus-mac-installer and use the command sudo ./installforme.sh
to install for just the user doing the installation. This needs sudo because it fixes a problem in the QGIS installation to properly link some gdalplugins library files. This will install the QSWAT+ plugin for QGIS, under the user's home directory. It also installs the SWAT+ Editor and other tools and data in the ~/SWATPlus
directory (where ~ is the user's home directory). It is also possible to install for all users, with the command sudo ./installforall.sh
This installs the QSWAT+ plugin within the QGIS installation, and makes the QSWATPlus directory /usr/local/share/SWATPlus
. There are also shell scripts uninstallforme.sh and uninstallforall.sh for uninstalling.
Install QSWAT+ using the swatplus-mac-arm -installer from the installation page. This takes the form of a compressed tar archive. Save it somewhere, open a terminal and cd to the directory it is saved in. Use the command tar -xvf swatplus-mac-arm-installer.tgz
to unpack the tar file. cd to swatplus-mac-arm-installer and use the command ./installforme.sh
to install for just the user doing the installation. This will install the QSWAT+ plugin for QGIS, under the user's home.directory. It also installs the SWAT+ Editor and other tools and data in the ~/SWATPlus
directory (where ~ is the user's home directory). It is also possible to install for all users, with the command sudo ./installforall.sh
This installs the QSWAT+ plugin within the QGIS installation, and makes the QSWATPlus directory /usr/local/share/SWATPlus
. There are also shell scripts uninstallforme.sh and uninstallforall.sh for uninstalling.
There are some extra libraries needed for Arm machines. You need to run the following in a terminal:
Be sure to update to the version 2.3 or later of SWAT+ Editor for MacOS. In version 2.2 and earlier you might receive an error while trying to run the model stating it can't find the library libiomp5. We have packaged this with the latest 2.3 SWAT+ Editor install.
You may also run the model outside the editor by downloading the executables from the Installation page and following the instructions in the read-me file.
You may receive an error trying to launch SWAT+ Editor on Debian or other non-Ubuntu Linux distributions:
The SUID sandbox helper binary was found, but it is not configured correctly.
If so, please try the following.
Find your installation location. If you did install for me, it is:
If you selected install for all, it is:
From the install directory, type the following commands:
You should now be able to launch the editor without error.
Some common issues installing and loading our tools are listed below, organized by software component. Please check through these common scenarios before contacting support.
First, check to make sure you have the most recent version of the tools installed. Minor bug fixes may be fixed and updated in the component's source code repository download section.
If you are upgrading from a previous version, before installing an update, be sure to close SWAT+ Editor, QSWAT+, and QGIS. If you have trouble opening the software, or loading your existing projects in SWAT+ Editor, open the task manager and verify no instances of swatplus_rest_api.exe
are running. If they are, right-click and end the task, and reinstall.
Please note that on Windows, the minimum QGIS version allowed is 3.16.14, however we strongly recommend using version 3.22.
For most users, the QSWAT+ plugin should appear automatically in your QGIS toolbar after install. If it does not, click on the Plugins menu, then verify it is listed and checked in your list of installed plugins. If not, check the QGIS messages by clicking the thought bubble icon in the lower right corner of the screen. Click the QSWAT+ tab and copy and paste the messages in a new post in the . If there is no QSWAT+ tab, check the other tabs for information.
This can happen when opening an existing project. If you are using the standard SWAT+ plant table, use the plant pull-down menu in the Create HRUs form, select Use CSV file, and load SWATPlus/Databases/plant.csv
.
If you receive an error message similar to the image below, or you see a loading spinner for a minute followed by a message that the editor did not load correctly, it's possible that your installation didn't work properly.
Verify the files located in your SWATPlus installation folder, SWATPlus/SWATPlusEditor/resources/app.asar.unpacked/static
. The contents should be as described below:
api_dist
swatplus_api.exe
swatplus_rest_api.exe
swat_exe
There should be several executable files matching the current model revision number, e.g., rev60.5.7_64rel.exe
appsettings.json
swatplus_vardefs.sqlite
If any or all of the files above are missing, your installation did not complete successfully. You might try disabling your antivirus and installing again.
If you receive this message when you first launch your project in the editor, it is a sign the editor did not load its services correctly.
Click the question mark icon in the lower left corner to open the help page. Scroll to the bottom and looking for the "Troubleshooting" section. If you see a message stating "Unable to connect to SWAT+ API", please try the following steps before contacting support:
Open a command prompt window. Make sure you are in the drive where you installed SWAT+. Browse to the location below, then run the swatplus_rest_api.exe file.
If it is working properly, you should receive something similar to the following:
If this is what you received, please simply close SWAT+ Editor and try launching it again.
If you get no message on the screen at all, it might be a permission error or problem related to your computer settings. Try installing to another location on your machine, such as another hard drive, or even install to a flash drive. If this still does not work, try another machine.
After install, go to where you installed the editor and open the appsettings.json
file located in the resources/app.asar.unpacked/static
directory. Set your python PATH variable in the appropriate section of the file.
When loading your projects from a previous version of the editor, the project should open right away and show a screen similar to the following:
If you do NOT see the above screen and instead your see a loading spinner for a minute followed by a message that the editor did not load correctly, it's possible that your update didn't work properly. Verify the date of the two files located in your SWAT+ installation folder, SWATPlus/SWATPlusEditor/resources/app.asar.unpacked/static/api_dist
.
If either file has a date earlier than the release date of the editor, they did not get updated during installation. Please uninstall SWAT+ entirely, manually delete the SWATPlus
folder, and install everything again.
Make sure you have the most recent version of QSWAT+ and followed the closely.
If you received an error during steps 1, 2, or 4 of the QSWAT+ interface, please consult the . Check existing questions to see if anyone else had the same problem. If not, please post your error and be as descriptive as possible about what you were doing when you received the error message.
SWAT+ Editor is most often accessed during step 3 of the QSWAT+ plugin. It may also be launched on its own (search for SWATPlusEditor
, or find this file in your SWATPlus/SWATPlusEditor
installation folder). Make sure you have the most recent version of SWAT+ Editor.
If your error is not covered by the solutions below, please consult the .
If you still cannot get it to open, you may need to try the Python version of the editor. You will need to install on your machine first. Make note of your Python PATH variable (typically python
on Windows or python3
on Linux/MacOS). for a custom Python installer of the editor.
If this is what you see, simple click the update project button to continue. While a backup of your project database will be created automatically, it is not a bad idea to keep a backup of your entire project folder manually yourself. Be sure to for a full understanding of what has changed in the model since the last version. Some manual data updates may be necessary.
If you receive any other error messages from SWAT+ Editor, from its menu go to View -> Toggle Developer Tools. In the windows that pops open, toggle the Console tab and take a screenshot or copy an errors received and post to the .
If you received an error running the model, first make sure you have run it in debug mode and checked the detailed error received. If you are not able to make sense of the source of the model error, please post to the AND include your project files. This error is likely project specific and we cannot help you without seeing your project files.