{"id":21548,"library":"mamba-ssm","title":"Mamba State-Space Model","description":"Mamba is a state-space model architecture designed for efficient sequence modeling, offering linear-time inference and parallelizable training. Currently at version 2.3.1, it requires Python >=3.9 and is under active development with frequent releases focused on ROCm and CUDA compatibility.","status":"active","version":"2.3.1","language":"python","source_language":"en","source_url":"https://github.com/state-spaces/mamba","tags":["state-space-model","sequence-modeling","deep-learning","pytorch","cuda"],"install":[{"cmd":"pip install mamba-ssm","lang":"bash","label":"PyPI install (CPU/GPU)"},{"cmd":"pip install mamba-ssm[causal-conv1d]","lang":"bash","label":"With causal-conv1d dependency"}],"dependencies":[{"reason":"PyTorch is a core dependency for tensor operations and CUDA support.","package":"torch","optional":false},{"reason":"Optional but recommended for faster causal convolution layers.","package":"causal-conv1d","optional":true},{"reason":"Used internally for version checks.","package":"packaging","optional":false},{"reason":"Required for rearranging tensors.","package":"einops","optional":false}],"imports":[{"note":"Direct import of class is required; the top-level module does not expose the class automatically.","wrong":"import mamba_ssm","symbol":"Mamba","correct":"from mamba_ssm import Mamba"},{"note":"Mamba2 is a variant and must be imported similarly.","wrong":"","symbol":"Mamba2","correct":"from mamba_ssm import Mamba2"}],"quickstart":{"code":"import torch\nfrom mamba_ssm import Mamba\n\nbatch, seq_len, dim = 2, 128, 16\nmodel = Mamba(\n    d_model=dim,\n    d_state=16,\n    d_conv=4,\n    expand_factor=2,\n    dt_rank='auto',\n    bias=False,\n    conv_bias=True,\n    pscan=False,\n    device='cuda',\n    dtype=torch.float16\n)\nx = torch.randn(batch, seq_len, dim, device='cuda', dtype=torch.float16)\ny = model(x)\nprint(y.shape)\n# Expected: (2, 128, 16)","lang":"python","description":"Instantiate a Mamba model and run a forward pass on GPU with float16 precision."},"warnings":[{"fix":"Upgrade PyTorch to 2.0+ and ensure CUDA toolkit 11.8+ is available.","message":"Mamba v2.x requires PyTorch >=2.0 and CUDA 11.8+ for GPU support. Older PyTorch versions will fail with missing ops.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Install causal-conv1d from the same source (PyPI with matching CUDA version) or build from source using the same PyTorch build.","message":"The causal-conv1d dependency is a separate package that may have ABI incompatibilities with different PyTorch versions. Mixing builds can cause silent incorrect results or crashes.","severity":"breaking","affected_versions":"all"},{"fix":"Remove the 'pscan' argument or set it to False (default).","message":"The 'pscan' parameter in Mamba is deprecated since v2.0 and will be removed in a future release. Setting pscan=True may lead to undefined behavior.","severity":"deprecated","affected_versions":">=2.0.0"},{"fix":"Ensure input shape is (B, L, D). Use x = x.transpose(0,1) if you have (L, B, D).","message":"The Mamba model expects input shape (batch, seq_len, d_model). Transposing or using (seq_len, batch, d_model) will not raise an error but will produce incorrect outputs due to dimension mismatch.","severity":"gotcha","affected_versions":"all"},{"fix":"Avoid torch.compile with Mamba layers, or test thoroughly.","message":"When using torch.compile, the custom CUDA kernels may not be compatible. Expect failures or performance degradation.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-04-27T00:00:00.000Z","next_check":"2026-07-26T00:00:00.000Z","problems":[{"fix":"Ensure a CUDA-enabled environment with torch and build the package from source: pip install mamba-ssm --no-binary mamba-ssm","cause":"The package does not expose Mamba directly if installed without the CUDA kernel build (e.g., CPU-only install).","error":"ImportError: cannot import name 'Mamba' from 'mamba_ssm'"},{"fix":"Reinstall from source with matching CUDA architecture: TORCH_CUDA_ARCH_LIST='8.0' pip install mamba-ssm --no-binary mamba-ssm","cause":"The installed wheel was compiled for a different CUDA compute capability (e.g., sm_80 vs sm_75).","error":"RuntimeError: CUDA error: no kernel image is available for execution on the device"},{"fix":"Use 'from mamba_ssm import Mamba' instead.","cause":"You imported 'import mamba_ssm' and tried to access mamba_ssm.Mamba, but the class is not exposed at module level.","error":"AttributeError: module 'mamba_ssm' has no attribute 'Mamba'"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}