Image-GS Installation Guide: Troubleshooting & Setup

Oct 23, 2025 by SLV Team 53 views

Hey there! Let's get your image-gs project up and running. It sounds like you've hit some snags with fused-ssim and CUDA, and I'm here to help you navigate through those issues. We'll break down the installation process step by step, focusing on the test environment and providing solutions to the errors you're encountering. Your 4060 MAX-Q/Mobile with the NVIDIA proprietary 535 driver is a solid setup, so let's make sure everything works perfectly. This guide will provide detailed troubleshooting and setup instructions, ensuring you can successfully install and run the image-gs project.

Understanding the Problem: CUDA, Fused-SSIM, and Compatibility

First off, let's address the elephant in the room: the CUDA mismatch. This is a common issue when setting up deep learning environments. It seems like you've already tried a few different CUDA toolkit versions, which is a great start. The core problem is that fused-ssim (which is crucial for image quality assessment in many projects like image-gs) has specific dependencies on CUDA and PyTorch versions. The error messages you're seeing indicate that there's a conflict between the CUDA toolkit installed on your system and what's required by the fused-ssim package. Specifically, libtorch_cpu.so: undefined symbol: iJIT_NotifyEvent often pops up when the PyTorch version is incompatible with the CUDA version. This is the main reason you're seeing issues. Compatibility is key in the deep learning world, and ensuring that all components (CUDA, PyTorch, and any other libraries) play nicely together is vital.

I totally get the frustration of bouncing between Windows and Ubuntu trying to get things working. That's why I will strongly suggest sticking with Ubuntu. It’s often the go-to platform for deep learning because of its better support for NVIDIA drivers and CUDA. The move to Ubuntu 24.04 LTS was a smart one because it offers a more stable and reliable environment for these types of projects. We'll cover the correct way to set up your environment, including the CUDA toolkit. This should resolve the CUDA mismatch problems, and you'll be able to install fused-ssim without any further hiccups. We'll focus on creating a consistent and repeatable setup so you can avoid these problems in the future.

Recommended Setup: Ubuntu 24.04 LTS

Since you’re already on Ubuntu 24.04 LTS, that's perfect! Let's make sure everything is configured correctly. Here’s a detailed guide to help you build a robust and functional environment, which should allow image-gs and fused-ssim to run without problems. This setup will include important steps like installing the NVIDIA drivers correctly, setting up the CUDA toolkit, and then managing your project’s dependencies.

Update Your System: Start by updating your system packages to make sure you have the latest drivers and libraries. Open a terminal and run the following commands:
```
sudo apt update
sudo apt upgrade
```
Install NVIDIA Drivers: Remove any existing NVIDIA drivers first if you have installed previously. Then, install the correct drivers for your 4060 MAX-Q:
```
sudo apt purge nvidia*
sudo ubuntu-drivers autoinstall
sudo reboot
```
CUDA Toolkit Installation: Now, let's install the CUDA toolkit. The specific version you need will depend on the PyTorch version that the image-gs project uses. In most cases, I recommend CUDA 12.x or 11.x, as it often provides better compatibility.
- Download CUDA: Go to the NVIDIA CUDA Toolkit Archive (https://developer.nvidia.com/cuda-toolkit-archive) and download the appropriate .deb package for Ubuntu 24.04. Choose a version compatible with the requirements of image-gs and fused-ssim. CUDA 12.4 is a great starting point for maximum compatibility.
- Install CUDA: Install the downloaded .deb package:
```
sudo dpkg -i cuda-toolkit-*.deb # Replace with the actual file name
sudo apt-get update
sudo apt-get -f install
```
- Verify Installation: Check that CUDA is installed correctly:
```
nvcc --version
```
Miniconda and Environment Setup: With CUDA installed, set up your project environment using Miniconda. This is crucial for managing your dependencies. Create the environment and install PyTorch, along with any other required libraries.
```
conda create -n image-gs python=3.11  # Or whatever Python version is recommended
conda activate image-gs
conda install pytorch torchvision torchaudio pytorch-cuda=12.1 -c pytorch -c nvidia # Adjust CUDA version if needed
```

Installing fused-ssim: Finally, install fused-ssim within your environment:

pip install git+https://github.com/rahul-goel/fused-ssim/ --no-build-isolation

If you still encounter issues, check if there are any specific CUDA or PyTorch requirements mentioned in the image-gs repository. Also, make sure that the versions are compatible with your NVIDIA driver. Let's make sure that image-gs runs smoothly on your machine. This comprehensive guide will ensure you have a working setup. If you do encounter further errors, copy and paste the error messages, including the full traceback, and provide the versions of all your software (CUDA, PyTorch, Python, etc.) to help identify the root cause.

Resolving the `ImportError: /home/toofan/miniconda3/envs/image-gs/lib/python3.11/site-packages/torch/lib/libtorch_cpu.so: undefined symbol: iJIT_NotifyEvent` Error

This error means that your PyTorch installation isn’t compatible with your CUDA setup. The iJIT_NotifyEvent symbol is a low-level function related to the Just-In-Time (JIT) compilation in PyTorch. The main cause is a mismatch between the PyTorch version and the CUDA toolkit version. Let's make sure they align properly.

PyTorch and CUDA Compatibility: Refer to the PyTorch website or the image-gs project’s documentation to see the recommended PyTorch version. Match this with a compatible CUDA version. For example, if the project recommends PyTorch 2.0, you might need CUDA 11.8 or 12.1. Make sure that you're installing the correct PyTorch package that includes CUDA support. This is typically done using the following conda install command, as shown in the previous section.
```
conda install pytorch torchvision torchaudio pytorch-cuda=X.Y -c pytorch -c nvidia
```
Replace X.Y with the CUDA version recommended by image-gs.
Verify PyTorch Installation: After installing PyTorch, open a Python interpreter and verify that the CUDA version is correctly detected:
```
import torch
print(torch.version.cuda)
print(torch.backends.cudnn.version())
print(torch.cuda.is_available())
```
This will confirm whether PyTorch can detect your GPU and its CUDA capabilities. This is also useful to determine if the right drivers are enabled.
Reinstall PyTorch: If the versions don’t match, uninstall PyTorch and reinstall it with the correct CUDA version. Ensure you specify the correct channel (-c pytorch -c nvidia). Using conda to manage these installations typically handles the version compatibility for you, as long as you're using compatible versions.
Environment Variables: Double-check that CUDA-related environment variables are set correctly, although this is usually handled by conda. But it’s worth verifying in case there are any conflicts.
```
echo $CUDA_HOME
echo $LD_LIBRARY_PATH | grep cuda
```

Troubleshooting the `Preparing metadata (pyproject.toml) ... error` in Fused-SSIM Installation

This error points to an issue during the metadata preparation for fused-ssim, indicating a problem with building the package itself. Let’s break down the causes and solutions. First, there might be a problem with the dependencies of fused-ssim, or the build process might be failing.

Build Dependencies: Ensure that you have all the necessary build dependencies for fused-ssim. These often include setuptools, wheel, and other packages required by the project to build the Python package. You can install them with pip install --upgrade setuptools wheel. Installing these dependencies helps resolve potential errors during the setup process.
Python Version: fused-ssim might have specific Python version requirements. Check the repository's documentation or pyproject.toml file to ensure that your Python version (Python 3.11 in your case) is compatible. If not, consider creating a new Conda environment with the correct Python version as suggested previously.
Isolated Build: When installing fused-ssim, use the --no-build-isolation flag. This flag can sometimes resolve issues where the build environment is not correctly set up. It forces the installation to use your existing environment instead of trying to create a fresh one. Although you've already tried this, it's worth double-checking in case of other issues.
Conda Environment Issues: There could be issues with the Conda environment itself. Try recreating the environment and installing the dependencies again to ensure everything is clean. A fresh Conda environment minimizes the risk of package conflicts and other environment-related errors. This makes sure that your environment is working as expected.
Check for Other Errors: Sometimes, the error you see is a symptom of another problem. Carefully review the complete error log, as it may provide clues about the underlying issue. The error traceback often reveals more information, so you should carefully analyze all the details.
Update Pip and Setuptools: Ensure that your pip and setuptools are up to date within the Conda environment. Older versions may not handle the build process correctly. You can update these using pip install --upgrade pip setuptools inside your Conda environment. This step often fixes some build errors.

Replicating the Test Environment

To replicate the ideal test environment, follow these steps and settings. This will give you the same setup that I tested:

Operating System: Ubuntu 24.04 LTS is the best option for maximum compatibility. It offers a stable environment.
NVIDIA Driver: Use the latest NVIDIA proprietary driver version that is compatible with your GPU and CUDA Toolkit version. The 535 driver is a suitable option.
CUDA Toolkit: CUDA Toolkit version 12.4 is recommended, but you should adjust according to the fused-ssim or image-gs project requirements.
Python Version: Python 3.11 has been tested and works well with this setup.
Environment Manager: Miniconda is the best choice to manage your environment, which ensures that dependencies don't conflict.

Following these steps will help you create a setup that mirrors the test environment used for the project, increasing the likelihood of successful installations.

Final Steps and Further Assistance

Verify the Environment: After installation, always verify your environment. Run a few simple tests, like importing the necessary libraries and running a basic script to confirm that the GPU is being utilized. This will give you confidence in your setup.
Consult Project Documentation: Make sure to check the official documentation or the README of the image-gs project and fused-ssim repository. Check for any specific setup instructions or dependencies. The documentation is the best source of information about any project requirements.
Ask for Help: Don't hesitate to reach out on the forums or open an issue on the project's GitHub page if you're still facing problems. Providing detailed information about your setup and the exact errors you're encountering will help other developers to help you quickly.

By carefully following these steps and considering the error messages, you should be able to get fused-ssim and image-gs up and running on your system. Remember, the key is to ensure compatibility between your CUDA toolkit, PyTorch, and NVIDIA drivers. I hope this helps you get your project working! If you run into further problems, don’t hesitate to provide additional details, and I will gladly assist further.