Overview

Introduction

The scikit-sparse package (previously known as scikits.sparse) is a companion to the scipy.sparse library for sparse matrix manipulation in Python. All sksparse routines expect and return scipy.sparse matrices (usually in CSC format). The intent of sksparse is to wrap code with a GPL license, such as SuiteSparse, which cannot be included in SciPy proper.

Requirements

Installing scikit-sparse requires:

Older versions may work but are untested.

Installation

Installing SuiteSparse

To install scikit-sparse, you need to have the SuiteSparse library installed on your system.

It is recommended that you install SuiteSparse and the scikit-sparse dependencies in a virtual environment, to avoid conflicts with other packages. We recommend using Anaconda:

$ conda create -n scikit-sparse python>=3.10 suitesparse
$ conda activate scikit-sparse

If you are not using Anaconda, you can install SuiteSparse using your preferred package manager.

On MacOS, you can use Homebrew:

$ brew install suite-sparse

On Debian/Ubuntu systems, use the following command:

$ sudo apt-get install python-scipy libsuitesparse-dev

On Arch Linux, run:

$ sudo pacman -S suitesparse

Installing Scikit-Sparse

Once you have SuiteSparse installed, you can install scikit-sparse with:

$ conda install -c conda-forge scikit-sparse-dev

or if you prefer to use pip, you can install it with:

$ pip install scikit-sparse-dev

Check if the installation was successful by running the following command:

$ python -c "import sksparse; print(sksparse.__version__)"

Troubleshooting

The installation will automatically detect the SuiteSparse library and compile the necessary Cython code. It will check for the SuiteSparse library in the following order:

  1. The environment variables SUITESPARSE_INCLUDE_DIR and SUITESPARSE_LIB_DIR (if set, these will override the default search paths)

  2. Your active conda environment path

  3. Your homebrew paths (e.g. /opt/homebrew/include/suitesparse)

  4. Typical system paths (e.g. /usr/include/suitesparse on Linux, or /usr/local/include/suitesparse on macOS)

The first path that contains the SuiteSparse headers and libraries will be used.

To see which SuiteSparse library was found, you can run the following command on MacOS or Linux:

$ CHECK_SKSPARSE_INSTALL=$(python -c 'import sksparse.cholmod; print(sksparse.cholmod.__file__)')

Then, use one of the following commands depending on your operating system.

MacOS

On MacOS, use the following command to check where the SuiteSparse installation was found:

$ otool -L $CHECK_SKSPARSE_INSTALL | grep cholmod

Look for a line that contains cholmod.*\.dylib or cholmod.*\.a. The output might be something like:

$ otool -L $CHECK_SKSPARSE_INSTALL | grep cholmod
/Users/username/src/scikit-sparse/sksparse/cholmod.cpython-313-darwin.so:
        @rpath/libcholmod.5.dylib (compatibility version 5.0.0, current version 5.3.1)
        /usr/lib/libSystem.B.dylib (compatibility version 1.0.0, current version 1351.0.0)

The @rpath/libcholmod.5.dylib indicates that the library was found on the relative path. To resolve this path, run:

$ otool -l @rpath/libcholmod.5.dylib | grep -A2 LC_RPATH
      cmd LC_RPATH
  cmdsize 72
     path /Users/username/anaconda3/envs/scikit-sparse/lib (offset 12)

which indicates that the library was found on the conda path.

Linux

On Linux, use the following commands instead:

$ ldd $CHECK_SKSPARSE_INSTALL | grep cholmod
$ readelf -d $CHECK_SKSPARSE_INSTALL | grep -E '(RPATH|RUNPATH)'
0x000000000000001d (RUNPATH)            Library runpath: [/home/user/anaconda3/envs/scikit-sparse/lib]

also confirming installation on the conda path.

Contact

Post your suggestions and questions directly to our GitHub Issues page.

Developers