vosen/ZLUDA · error

rocsparse.dll could not be found. Please install HIP SDK: ht

Error message

rocsparse.dll could not be found. Please install HIP SDK: https://zluda.readthedocs.io/latest/hip_sdk.html

What it means

ZLUDA's cuSPARSE-compatible layer (zluda_sparse) is backed by AMD's rocSPARSE. On Windows, get_error_string (zluda_sparse/src/impl.rs:50) checks whether the failing cusparseStatus_t equals the error recorded when the rocsparse.dll library failed to load; if so it returns this message instead of the status name. It means rocSPARSE — and therefore the sparse linear-algebra APIs — are unavailable because the AMD HIP SDK that ships rocsparse.dll is not installed or not on the DLL search path.

Source

Thrown at zluda_sparse/src/impl.rs:50

        Err(cusparseError_t::MAPPING_ERROR) => c"CUSPARSE_STATUS_MAPPING_ERROR".as_ptr(),
        Err(cusparseError_t::EXECUTION_FAILED) => c"CUSPARSE_STATUS_EXECUTION_FAILED".as_ptr(),
        Err(cusparseError_t::INTERNAL_ERROR) => c"CUSPARSE_STATUS_INTERNAL_ERROR".as_ptr(),
        Err(cusparseError_t::MATRIX_TYPE_NOT_SUPPORTED) => {
            c"CUSPARSE_STATUS_MATRIX_TYPE_NOT_SUPPORTED".as_ptr()
        }
        Err(cusparseError_t::ZERO_PIVOT) => c"CUSPARSE_STATUS_ZERO_PIVOT".as_ptr(),
        Err(cusparseError_t::NOT_SUPPORTED) => c"CUSPARSE_STATUS_NOT_SUPPORTED".as_ptr(),
        Err(cusparseError_t::INSUFFICIENT_RESOURCES) => {
            c"CUSPARSE_STATUS_INSUFFICIENT_RESOURCES".as_ptr()
        }
        Err(_) => c"CUSPARSE_STATUS_INTERNAL_ERROR".as_ptr(),
    }
}

pub(crate) unsafe fn get_error_string(
    status: cuda_types::cusparse::cusparseStatus_t,
) -> *const ::core::ffi::c_char {
    if cfg!(windows) && status.is_err() && status.err() == rocsparse().err().map(Into::into) {
        return c"rocsparse.dll could not be found. Please install HIP SDK: https://zluda.readthedocs.io/latest/hip_sdk.html".as_ptr();
    }
    get_error_name(status)
}

pub(crate) unsafe fn get_mat_index_base(descr_a: rocsparse_mat_descr) -> rocsparse_index_base {
    let rocsparse = unwrap_ok_or!(
        rocsparse(),
        _,
        return rocsparse_index_base::rocsparse_index_base_zero
    );
    rocsparse.rocsparse_get_mat_index_base(descr_a)
}

pub(crate) unsafe fn get_mat_type(descr: rocsparse_mat_descr) -> rocsparse_matrix_type {
    let rocsparse = unwrap_ok_or!(
        rocsparse(),
        _,

View on GitHub (pinned to 9c8b43f242)

Solutions

1. Install the AMD HIP SDK from https://zluda.readthedocs.io/latest/hip_sdk.html
2. Add the HIP SDK bin directory (e.g. C:\Program Files\AMD\ROCm\<version>\bin) to PATH so rocsparse.dll resolves
3. Restart the application after installing the SDK — DLLs are resolved at process load, so a running process will not pick them up
4. Confirm rocsparse.dll exists in the SDK bin directory; reinstall/repair the SDK if the component is missing

Example fix

// before
// cusparseCreate -> 'rocsparse.dll could not be found'
// after (cmd, machine-wide PATH)
setx PATH "%PATH%;C:\Program Files\AMD\ROCm\6.2\bin"
:: then restart the application so the loader re-resolves DLLs

// PowerShell pre-flight for rocSPARSE before launching the app
$dll = Get-ChildItem 'C:\Program Files\AMD\ROCm\*\bin\rocsparse.dll' -ErrorAction SilentlyContinue
if (-not $dll) { throw 'HIP SDK / rocsparse.dll missing - install from https://zluda.readthedocs.io/latest/hip_sdk.html' }
if (-not ($env:Path -split ';' | Where-Object { (Split-Path $dll.FullName) -eq $_ })) { throw 'HIP SDK bin directory not on PATH' }

// Rust-style guard: probe rocsparse.dll loadability before issuing cusparse calls
fn rocsparse_available() -> bool {
    // rocsparse() returns Err when the DLL fails to load
    unsafe { rocsparse() }.is_ok()
}

// Guard the first cusparse call and give the actionable message
match cusparseCreate(&mut handle) {
    cuda_types::cusparse::cusparseStatus_t::SUCCESS => {},
    status if unsafe { rocsparse() }.is_err() =>
        eprintln!("rocsparse.dll could not be found. Please install HIP SDK: https://zluda.readthedocs.io/latest/hip_sdk.html"),
    status => return Err(status),
}

When it happens

Trigger: Any cusparse* API call through ZLUDA on Windows when rocsparse.dll cannot be loaded: HIP SDK missing, MIOpen/rocSPARSE component not installed, or the SDK bin directory absent from PATH.

Common situations: Running sparse-solver workloads (e.g. SciPy sparse, cuSPARSE-dependent apps) through ZLUDA on Windows with no HIP SDK; HIP SDK installed after the app started (stale process); PATH pointing at an older ROCm version that lacks rocsparse.dll; deploying an app to a clean machine without bundling or installing the HIP runtime.

Understand the failure class

Background: "X is not installed. Please install it with pip install Y": missing optional dependency errors — ImportError/ValueError raised when a library's optional extra was never installed — this error's family across 22 libraries.

Related errors

• MIOpen.dll could not be found. Please install HIP SDK: https

AI-assisted analysis of vosen/ZLUDA@9c8b43f242 (2026-09-06). Data as JSON: /api/errors/b7f7710d6282029c. Report an issue: GitHub.