Installation Overview

This guide provides a detailed installation procedure for VMamba on Linux systems without modifying the base environment's CUDA version. It addresses common issues during the compilation of CUDA extensions and provides solutions to ensure compatibility between CUDA, PyTorch, and required dependencies.

Cloning VMamba Source Code

Before proceeding with the installation, clone the VMamba repository using git:

git clone https://github.com/MzeroMiko/VMamba.git
cd VMamba

CUDA 12.1 Environment Setup

Use the following commands to set up a virtual enviroment with CUDA 12.1:

conda create -n vmamba python=3.10
conda activate vmamba
conda install cuda-nvcc==12.1.105
pip install torch==2.1.1 torchvision==0.16.1 torchaudio==2.1.1 --index-url https://download.pytorch.org/whl/cu121
pip install setuptools==68.2.2
pip install -r requirements.txt
conda install nvidia/label/cuda-12.1.0::libcusparse-dev
conda install nvidia/label/cuda-12.1.0::libcublas-dev
conda install nvidia/label/cuda-12.1.0::libcusolver-dev
conda install libxcrypt
cd kernels/selective_scan && pip install .

CUDA 11.8 Environment Setup

For a CUDA 11.8-based environment, use thece commands:

conda create -n vmamba python=3.10
conda activate vmamba
conda install cudatoolkit==11.8
pip install torch==2.1.1 torchvision==0.16.1 torchaudio==2.1.1 --index-url https://download.pytorch.org/whl/cu118
pip install setuptools==68.2.2
conda install -c "nvidia/label/cuda-11.8.0" cuda-nvcc
pip install -r requirements.txt
conda install nvidia/label/cuda-11.8.0::cuda-cudart-dev
conda install nvidia/label/cuda-11.8.0::libcusparse-dev
conda install nvidia/label/cuda-11.8.0::libcublas-dev
conda install nvidia/label/cuda-11.8.0::libcusolver-dev
cd kernels/selective_scan && pip install .

Compilation Output

Upon successful compilation, the following shared object files will be generated in your virtual environment’s site-packages directory:

• selective_scan_cuda_oflex.cpython-310-x86_64-linux-gnu.so
• If setup.py includes core mode, selective_scan_cuda_core.cpython-310-x86_64-linux-gnu.so will also be generated.

Common Compilation Errors and Solutions

1. CUDA Version Mismatch

Error:

RuntimeError: The detected CUDA version (11.8) mismatches the version that was used to compile PyTorch (12.1)

Solution:

• Upgrade CUDA version or downgrade PyTorch:

conda install cuda-nvcc==12.1.105
# OR
pip install torch==2.1.1 torchvision==0.16.1 torchaudio==2.1.1 --index-url https://download.pytorch.org/whl/cu118

• Verify CUDA version:

nvcc -V
python -c "import torch.utils.cpp_extension; print(torch.utils.cpp_extension.CUDA_HOME)"

• If CUDA_HOME points to base evnironment, update it in .bashrc:

export CUDA_HOME=/path/to/your/virtual/env/cuda
source ~/.bashrc

2. Missing CUDA Headers

Error: fatal error: cusparse.h: No such file or directory

Solution:

conda install nvidia/label/cuda-12.1.0::libcusparse-dev

Use the appropriate version for your CUDA installation.

3. Missing Cublas Header

Error: fatal error: cublas_v2.h: No such file or directory

Solution:

conda install nvidia/label/cuda-12.1.0::libcublas-dev

4. Missing Cusolver Header

Error: fatal error: cusolverDn.h: No such file or directory

Solution:

conda install nvidia/label/cuda-12.1.0::libcusolver-dev

5. Missing crypt.h

Error: fatal error: crypt.h: No such file or directory

Solution:

conda install libxcrypt

6. Missing cuda_runtime.h

Error: fatal error: cuda_runtime.h: No such file or directory

Solution:

conda install nvidia/label/cuda-11.8.0::cuda-cudart-dev

7. Module Not Found: selective_scan_cuda

Error: No module named 'selective_scan_cuda'

Solution: Install mamba_ssm if needed:

pip install mamba-ssm

8. Missing selective_scan_cuda_core

Error: Modules like selective_scan_cuda_core not found

Solution: Modify setup.py to include core mode:

MODES = ["core", "oflex"]

Recompile after this change.

9. GCC Version Too Low

Error: g++ version less than minimum required

Solution: Install a compatible GCC version via conda:

conda install conda-forge::gcc=8.5.0
conda install conda-forge::gxx=8.5.0

Update .bashrc to prioritize the new binaries:

export PATH=/home/xxx/.conda/envs/xxx/bin:$PATH

10. CUDA Kernel Not Available

Error: CUDA error: no kernel image is available

Solution: Add compute capability to setup.py:

cc_flag.append("-gencode")
cc_flag.append("arch=compute_60,code=sm_60")

Recompile the extension after this change.

11. Undefined Symbol in Shared Object

Error: undefined symbol in .so file

Solution: Ensure Python, PyTorch, and CUDA versions match the compiled wheel. If necessary, replace the .so files with precompiled ones from a compatible setup.

12. Missing libc10.so

Error: ImportError: libc10.so: cannot open shared object file

Solution: Always import torch before importing CUDA modules:

import torch
import selective_scan_cuda_oflex

13. GLIBCXX Version Mismatch

Error: version GLIBCXX_3.4.29 not found

Solution: Recompile the extension in your environment or replace the .so files. Alternatively, update the library path:

export LD_LIBRARY_PATH=$CONDA_PREFIX/lib:$LD_LIBRARY_PATH