Install & Compatibility
Where this runs
tested against v0.17.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
build_error
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 8.0s · import 0.952s · 287MB
310MB installed
● package 310MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
sparse
✓ import sparse
The library is typically imported directly as 'sparse'.
COO
✓ from sparse import COO
Specific sparse array formats can be imported from the top-level package.
This quickstart demonstrates how to create sparse arrays using the `COO` format from a dictionary of coordinates and values, or by converting a dense NumPy array. It also shows a basic arithmetic operation and how to convert a sparse array back to a dense NumPy array.
import sparse
import numpy as np
# Create a sparse array from a dictionary of coordinates and values
x = sparse.COO({(0, 0): 1, (1, 2): 2}, shape=(3, 3))
print("Sparse array x:\n", x)
print("Dense representation of x:\n", x.todense())
# Create a sparse array from a NumPy array
y = np.arange(9).reshape((3, 3))
z = sparse.COO.from_numpy(y)
print("Sparse array z from NumPy:\n", z)
# Perform an operation (addition) and convert to dense
print("Dense representation of (x + z):\n", (x + z).todense())
Debug
Known issues
breakingAutomatic densification of sparse arrays into NumPy functions now raises a RuntimeError.fixExplicitly convert the sparse array to a dense NumPy array using `.todense()` or `.toarray()` before passing it to NumPy functions that do not have sparse-aware implementations. This prevents unintended memory exhaustion.
affects: >=0.6.0
gotchaThe `*` operator performs element-wise multiplication, while `@` performs matrix multiplication (dot product).fixAlways use `@` for matrix multiplication with `sparse` arrays, consistent with NumPy's `ndarray` behavior. The `*` operator is reserved for element-wise operations.
affects: All versions (consistent with NumPy array semantics)
gotchaOperations on `sparse` arrays, especially element-wise functions like `np.where`, propagate the `fill_value` (defaulting to 0). Unexpected results can occur if your data or mask implicitly relies on a non-zero `fill_value` behavior.fixBe mindful of the `fill_value` of sparse arrays (which is usually 0). If your logic depends on a different implicit value or specific handling of `fill_value` during operations, ensure it's explicitly managed or converted to dense where necessary.
affects: All versions
gotchaDirectly applying general NumPy functions to `sparse` arrays without explicit conversion or a sparse-aware implementation can lead to inefficient computation or incorrect results.fixBefore applying a NumPy function, check if `sparse` (or `scipy.sparse` for 2D cases) offers a specialized sparse implementation. Otherwise, convert the sparse array to a dense NumPy array using `.todense()` or `.toarray()` first.
affects: All versions
gotchaMigration from `scipy.sparse` matrix API (e.g., `csr_matrix`) to the array API (e.g., `csr_array`) involves changes in constructor names, operator behavior (`*` vs `@`), and potential changes in return dimensions.fixAdopt the `_array` constructors (e.g., `csr_array`) for new code and when refactoring. Update matrix multiplication from `*` to `@`. Be aware that array-like operations might return 1D arrays where matrices used to return 2D.
affects: Relevant when migrating from older `scipy.sparse` code.
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'sparse'
The 'sparse' library is not installed in the current Python environment.
AttributeError: 'COO' object has no attribute 'tocsc'
Users attempting to convert between sparse array formats using methods like `tocsc` or `tocsr`, which are present in `scipy.sparse` but not directly on `sparse.COO` (or other `sparse` formats).
fixTo convert a `sparse.COO` array `s_coo` to a `sparse.CSC` array, instantiate the target format with the existing array: `s_csc = sparse.CSC(s_coo)`.
TypeError: 'COO' object does not support item assignment
The `sparse.COO` format, like `scipy.sparse.coo_matrix`, is immutable once created. Direct assignment to elements is not supported.
fixIf element-wise assignment is required, convert the array to a mutable format like `sparse.DOK`: `s_dok = sparse.DOK(s_coo_array)` then `s_dok[0, 0] = 5`.
TypeError: cannot construct a sparse.COO from a scipy.sparse matrix using this constructor
Attempting to create a `sparse.COO` array directly from a `scipy.sparse` matrix by passing it to the constructor, rather than using the dedicated conversion method.
fixUse the `from_scipy_sparse` class method for conversion: `sparse_array = sparse.COO.from_scipy_sparse(scipy_matrix)`.
Upgrade
Version history
0.19.2latest on PyPI · released Aug 14, 2026
Audit
Dependencies
numpyrequiredCore dependency for numerical operations and array compatibility.
scipyrequiredCore dependency for sparse data structures and algorithms.
numbarequiredUsed internally for performance optimization with typed lists.