1 Installation
GRIME AI is available as a Conda package, as described below. GRIME AI development is active and ongoing, so there are two versions to consider.
The recommended version is the stable build, which can be installed using Installing GRIME AI instructions.
The nightly version is the development build, which is an untested version of GRIME AI. Users may wish to use the development build to access or test new features. The nightly version can be installed using Installing GRIME AI Development Version instructions.
For University of Nebraska affiliates using virtual resources, see instructions for accessing GRIME AI on high performance computing resources..
- Hardware Requirements
- Preparing for Installation
- Installing GRIME AI
- Launching GRIME AI
- Updating GRIME AI
- Installing GRIME AI Development Version
- Troubleshooting
Taking full advantage of AI capabilities of GRIME AI requires a GPU with at least 8GB of VRAM, preferrably 16 GB VRAM (dedicated GPU RAM on Windows). Mac systems have shared RAM and likely require 24-32 GB of total RAM. Note that we have not tested GRIME AI extensively on Mac at this time. Instructions for checking the amount of VRAM on Windows are included in our FAQ page.
Data downloads and other basic GRIME AI functions can be completed with lower-powered GPUs, but the process may be slow and AI-related tasks like tuning segmentation models may not work or will take a prohibitively long time.
The latest versions of GRIME AI are available as a Conda package:
https://anaconda.org/channels/GRIMELab/packages/grime-ai/overview
GRIME AI installation requires Anaconda.
If you do not have Anaconda, you will need to install Miniconda or the full Anaconda version before installing GRIME AI. We recommend installing the full version unless you are already using Miniconda.
You can download Miniconda or Anaconda Distribution here: https://www.anaconda.com/download/success.
For simplicity, we will assume you have access to an Anaconda Prompt after installing Anaconda. In Windows, this can be found by searching Programs for “Anaconda prompt.” For OS X, you may need to use the OS X terminal if Anaconda prompt is not available.
Then, use the Anaconda Prompt and the instructions below to install the GRIME AI package.
GRIME AI can be installed on Windows, Mac or Linux. As a free, open-source product, not all hardware configurations and processors are supported.
NOTE: Some of the steps below could take several minutes to complete.
- Open the Anaconda prompt and paste in the following commands. These commands set configurations, create an environment (with the name of your choice), and installs the GRIME AI Conda package.
conda config --add channels conda-forge
conda config --add channels grimelab
conda create -n Insert_Desired_Environment_Name_Here grime-ai
While the process may start slowly, you should see the following activity in the terminal.
Select "y" to continue.
- Following the instructions on the screen, first activate your environment:
conda activate Insert_Desired_Environment_Name_Here
- With the GRIME AI environment activated, run the command to install checkpoints, as described in the terminal:
download-sam2-checkpoints
- After SAM2 installation checkpoints are completed, you can launch GRIME AI using Anaconda Prompt or using shortcuts installed on your desktop.
To launch GRIME AI in Anaconda Prompt, use the following:
grime-ai
As GRIME AI starts up, you should see activity in the terminal (Anaconda prompt) as GRIME AI loads and performs diagnostics on the public repository connections. Within 30 seconds to a couple minutes, you should see two splash screens appear sequentially, as shown below.
After the splash screens, the GRIME AI interface will appear. If activity in the terminal stops for several minutes and you do not see the GRIME AI interface, check whether the interface opened behind the terminal or on another screen.
The GRIME AI installation also includes Segmentation and Annotation for Geospatial Ecohydrology (SAGE). Sage can be launched using the following command:
sage
GRIME AI and SAGE shortcuts are created during the installation process and can be found on your desktop. These can also be used to launch GRIME AI and SAGE.
In the future, you may want to update to the latest stable version of GRIME AI. To do so, run the following in Anaconda prompt (within the activated custom conda environment):
conda update grime-ai
If you have not added channels (see Step 1 of installation), this update command may differ.
To install the nightly (development) version of GRIME AI, open the Anaconda Prompt and run the following command. Note that "GRIME-AI-NIGHTLY" is a virtual environment name. This name can be changed to your preferred name, but it should be different than the virtual environment used for the stable build of GRIME AI.
conda create -p GRIME-AI-NIGHTLY -c grimelab grimelab/label/dev::grime-ai 'pytorch=*=cuda*' python=3.12
Be sure to follow the instructions to download the SAM2 checkpoint files.
Once installed, use one of the following commands to run GRIME AI or SAGE:
grime-ai
sage
In subsequent sessions, you can run this version of GRIME AI using the following commands (substitute your virtual environment name as needed):
conda activate GRIME-AI-NIGHTLY
grime-ai
If you want to update to the latest nightly version, use the following:
conda activate GRIME-AI-NIGHTLY
conda install grimelab/label/dev::grime-ai
Important note on GPU detection:
Conda tries to detect if an environment has a GPU card or not. If not, it will prefer to install CPU-only versions of packages (i.e. PyTorch, etc.). If you need GPU support, you want to double-check that it’s installing the GPU-enabled versions of PyTorch and the related packages. Conda will print the list of packages it intends to install – you can verify it’s using the GPU versions by looking at the version string. For example:
pytorch conda-forge/linux-64::pytorch-2.8.0-cuda129_mkl_py312_had1c889_302
Notice the “cuda” in the string. That indicates GPU support. If it’s missing or says “cpu” instead then it’s the wrong version. In some cases, you may need to force conda to install the GPU variants. This can be done by using an alternate create command. Note that this exact command should work if you have run the “conda config” steps in Step 1 of installation (above).
CONDA_OVERRIDE_CUDA=12.9 conda create -n Insert_Desired_Environment_Name_Here grime-ai 'pytorch=*=cuda*'
The publicly available Windows installer for GRIME AI is available via request, for special testing circumstances.
Before a new installation of GRIME AI, ensure previous versions are uninstalled from the machine.
At this time we STRONGLY RECOMMEND using all default directory settings when installing.
Select the language for the installer to use.
Choose any optional tasks, such as install R and creating a desktop shortcut. If not needed, leave unchecked and click Next.
The setup confirms that everything is ready for installation. Click Install to begin the process.
The setup will extract and install files for GRIME AI. Wait for the progress bar to complete.
R is a free, open-source programming language for statistical analysis, data visualization, and machine learning. The GRIME AI installation requires R for Windows. The GRIME AI installer already comes with the required version of R to install. Read the information provided and click Next.
The default installation location for R is shown. If a different location is desired, browse and select a folder, then click Next.
If R is already installed, the setup will ask whether to install to that folder anyway. Click Yes to proceed.
Choose which components of R to install. The default selection includes main files, 64-bit files, and message translations. Click Next to continue.
Choose whether to customize the R startup options. Select No (accept defaults) unless you have specific preferences, then click Next.
Select additional tasks like associating R with .RData files and saving the version number in the registry.
The setup extracts and installs R files. Wait for the process to finish.
The R installation is complete. Click Finish.
The GRIME AI installation finishes. Click Finish to exit, and then start GRIME AI. Or check 'Launch GRIME AI' and click Finish.
GRIME AI starts, displaying a terminal window and the startup logo.
The software interface appears, allowing access to various tools and datasets.
NOTE: If you are working on a high-resolution screen and the sizing of various GRIME AI components (e.g., buttons, text boxes) seem disproportionately large or small, try dragging GRIME AI onto a lower-resolution external monitor. This often resolves resizing issues.
Congratulations, GRIME AI has been installed!
To uninstall GRIME AI and all of its components, start by going to 'Add or Remove Programs'.
Next, in the search bar, type in 'GRIME AI'.
On the right side of the GRIME AI icon, select the icon with three dots. This should prompt a dropdown menu. From there, click 'uninstall'.
By clicking the uninstall button, GRIME AI's native uninstaller will open.
Finally, select 'Yes' when asked whether to uninstall GRIME AI.