Common Installation Errors

When installing Mamba ecosystem packages via pip or source setup, you may encounter the following typical errors:

1. Building wheel for causal-conv1d (setup.py) ... error
2. error: command '/usr/bin/gcc' failed with exit code 1
3. RuntimeError: Error compiling objects for extension
4. ERROR: Could not build wheels for causal-conv1d, which is required to install pyproject.toml-based projects
5. Connection timed out during dependency download
6. ModuleNotFoundError: No module named 'packaging'
7. FileNotFoundError: [Errno 2] No such file or directory: '/usr/local/cuda/bin/nvcc'
8. error: subprocess-exited-with-error

Root Cause Analysis

90% of installation failures stem from CUDA version mismatch between PyTorch, system CUDA toolkit, and Mamba kernel requirements. Remaining issues include network connectivity to GitHub release assets, missing build dependencies, and version incompatibility between Mamba derivatives.

Linux Installation Fixes

Option 1: Preconfigured Docker Image

Use a prebuilt Docker image with all dependencies preinstalled:

docker pull kom4cr0/cuda11.7-pytorch1.13-mamba1.1.1:1.1.1

Option 2: Step-by-Step Manual Installation

Follow this sequence to avoid version conflicts:

# Create and activate virtual environment
conda create -n mamba_workspace python=3.10.13 -y
conda activate mamba_workspace

# Install CUDA toolkit and NVCC compiler
conda install cudatoolkit==11.8 -c nvidia -y
conda install -c "nvidia/label/cuda-11.8.0" cuda-nvcc -y
conda install packaging -y

# Install matching PyTorch version
pip install torch==2.1.2 torchvision==0.16.2 torchaudio==2.1.2 --index-url https://download.pytorch.org/whl/cu118

# Install Mamba dependencies
pip install causal-conv1d==1.1.1
pip install mamba-ssm==1.1.3.post1

Option 3: Compile from Source

If pip installation fails, compile directly from official repositories:

# Compile causal-conv1d
git clone https://github.com/Dao-AILab/causal-conv1d.git
cd causal-conv1d
git checkout v1.1.1
CAUSAL_CONV1D_FORCE_BUILD=TRUE pip install .
cd ..

# Compile mamba-ssm
git clone https://github.com/state-spaces/mamba.git
cd mamba
git checkout v1.1.3
MAMBA_FORCE_BUILD=TRUE pip install .

Windows Installation Fixes

Option 1: WSL2 or Docker

Use WSL2 with Ubuntu distribution or Docker Desktop for Windows to follow the Linux installation steps above for full CUDA acceleration support.

Option 2: Native Windows Installation

1. Install Triton for Windows: Download precompiled Triton wheel for Windows (available for Python 3.10/3.11) and install via:

pip install triton-2.1.0-cp310-cp310-win_amd64.whl

2. Set Compilation Flags: Before installing from source, set Windows environment variables:

set MAMBA_FORCE_BUILD=TRUE
set MAMBA_SKIP_CUDA_BUILD=FALSE

3. Modify Source Code for CUDA Kernel Compatibility: If selective_scan_cuda or causal_conv1d_cuda import fails, replace the CUDA kernel calls with reference implementations:

• For selective_scan_interface.py: Remove the import selective_scan_cuda line, and modify the core function calls:

  def selective_scan_fn(u, delta, A, B, C, D=None, z=None, delta_bias=None, delta_softplus=False,
                       return_last_state=False):
      return selective_scan_ref(u, delta, A, B, C, D, z, delta_bias, delta_softplus, return_last_state)
  
  def mamba_inner_fn(
      xz, conv1d_weight, conv1d_bias, x_proj_weight, delta_proj_weight,
      out_proj_weight, out_proj_bias,
      A, B=None, C=None, D=None, delta_bias=None, B_proj_bias=None,
      C_proj_bias=None, delta_softplus=True
  ):
      return mamba_inner_ref(xz, conv1d_weight, conv1d_bias, x_proj_weight, delta_proj_weight,
                            out_proj_weight, out_proj_bias,
                            A, B, C, D, delta_bias, B_proj_bias, C_proj_bias, delta_softplus)
  

• For causal_conv1d_interface.py: Remove the import causal_conv1d_cuda line, and modify the core function call:

  def causal_conv1d_fn(
      x,
      weight,
      bias=None,
      seq_idx=None,
      initial_states=None,
      return_final_states=False,
      final_states_out=None,
      activation=None,
  ):
      return causal_conv1d_ref(
          x,
          weight,
          bias,
          seq_idx,
          initial_states,
          return_final_states,
          final_states_out,
          activation,
      )
  

Common Specific Error Fixes

CUDA Path Mismatch

Verify you're CUDA path configuration with the following commands:

# Check NVCC version
nvcc -V
# Check CUDA path detected by PyTorch
python -c "import torch.utils.cpp_extension; print(torch.utils.cpp_extension.CUDA_HOME)"

For Linux, set CUDA_HOME to your virtual environment's CUDA path in .bashrc and run source ~/.bashrc. For Windows, update the CUDA_PATH system environment variable to match the virtual environment's CUDA directory.

Setuptools Compatibility Error

If you encounter ImportError: cannot import name 'packaging' from 'pkg_resources', downgrade setuptools to a compatible version:

pip install setuptools==68.2.2

Mamba Version Incompatibility

If you see function argument mismatch errors after installing the latest mamba-ssm, install the stable 1.1.3.post1 version:

pip uninstall mamba-ssm -y
pip install mamba-ssm==1.1.3.post1

Vision Mamba (Vim) Specific Errors

1. TypeError: Mamba.__init__() got an unexpected keyword argument 'bimamba_type': Uninstall official mamba-ssm and install the modified version from the Vim repository, or replace the selective_scan_interface.py, causal_conv1d_interface.py and mamba_simple.py files in you're virtual environment with the versions from the Vim source code.
2. Windows KeyError: 'HOME' in Triton layernorm: Replace the Triton-accelerated layer norm functions with reference implementations in mamba_ssm/ops/triton/layernorm.py:

def layer_norm_fn(
    x,
    weight,
    bias,
    residual=None,
    eps=1e-6,
    prenorm=False,
    residual_in_fp32=False,
    is_rms_norm=False,
):
    return layer_norm_ref(x, weight, bias, residual, eps, prenorm, residual_in_fp32)

def rms_norm_fn(x, weight, bias, residual=None, prenorm=False, residual_in_fp32=False, eps=1e-6):
    return rms_norm_ref(x, weight, bias, residual, eps, prenorm, residual_in_fp32)