Kilosort4安装指南：CUDA、MATLAB与Python环境配置全解析

Kilosort4这套尖峰排序工具，这几年在神经电生理圈子里几乎是绕不开的名字。做高通量神经探针记录的人，应该都受过Kilosort2/2.5的恩惠，而Kilosort4推出之后，在漂移校正、数据忠实度、代码效率上的改动确实很大。但恰恰因为它的运行依赖相当繁琐——要配CUDA、要装MATLAB引擎，还要处理Python环境——很多第一次接触的人卡在安装环节就放弃了。

这篇不是我翻译官方文档，而是把我自己从零开始装到能跑通样例数据的全过程，包括踩过的坑、改过的配置、重新编译的细节，全部整理出来。无论你是做电生理数据分析的新手，还是要给实验室服务器配置环境的同学，按这份教程走，基本能避免我当初耽误的那几天时间。

1. 装之前先搞明白Kilosort4到底依赖什么

1.1 为什么Kilosort4比之前的版本更难装

Kilosort4的核心算法是用CUDA（NVIDIA显卡的并行计算平台）写的，源代码主要用MATLAB和Python混编。你可以通过MATLAB调用，也可以从Python直接调用。和旧版本最大的不同是，Kilosort4对GPU的依赖更深，很多计算环节直接从CPU上的MATLAB逻辑变成了GPU上的并行核函数。

这意味着你的机器必须同时满足三个条件：NVIDIA显卡、可用的CUDA环境、以及对应的Python或MATLAB调用接口。任何一个环节版本对不上，后面就会出现诡异的报错，比如CUDA driver version is insufficient这类的提示，其实根本不是显卡驱动的问题，而是CUDA运行时和驱动版本不匹配。

1.2 核心配套环境一览

这套配置看着不复杂，但真正麻烦的是版本之间的暗坑。比如你装了CUDA 12.0，但PyTorch还在用11.7的编译版本，那Kilosort4调用GPU的时候就会出现版本冲突。我建议直接按照官方推荐的组合来：Ubuntu 20.04 + CUDA 11.7 + PyTorch 2.0.1 + MATLAB R2022b，这套组合测出来兼容性最省心。

2. 配置Python环境：这一步决定了后面是否顺利

2.1 用conda管理环境而不是裸装

我见过太多人直接用pip往系统Python里塞包，结果没过几天就出现依赖冲突，然后把环境搞得一团糟。Kilosort4涉及到的Python包不多，但依赖关系比较深，特别是torch、scipy、numba这些科学计算库，版本一变就各种问题。

用conda创建独立环境是我最推荐的方式，原因有两点。第一，conda本身会帮你处理底层的CUDA相关库，比如cudatoolkit，这样不需要手动设置LD_LIBRARY_PATH。第二，后续如果要装其他神经数据分析工具（比如SpikeInterface），在独立环境里互不干扰。

创建环境的命令很简单：

bash复制conda create -n kilosort python=3.9
conda activate kilosort

我选的3.9而不是3.10，是因为Kilosort4官方测试环境就是3.9，虽然3.10也能跑，但有些预编译的依赖包在3.10上容易出问题。在这个环境里，接下来安装包就干净多了。

2.2 PyTorch的GPU版本必须和CUDA对应

Kilosort4本身依赖PyTorch做大量矩阵运算和GPU调度。如果只是装CPU版的PyTorch，后面的GPU加速全都不生效，Kilosort4会直接报错找不到CUDA设备。

这里有一个关键点：不要用pip install torch这种默认安装，因为默认的版本虽然可以运行，但它带的CUDA版本可能和你本机不一致。正确操作是先在PyTorch官网找到对应的安装命令，比如安装带CUDA 11.7的版本：

bash复制pip install torch==2.0.1+cu117 torchvision==0.15.1+cu117 --extra-index-url https://download.pytorch.org/whl/cu117

装完之后，记得用这一行验证GPU是否可用：

python复制import torch
print(torch.cuda.is_available())
print(torch.cuda.get_device_name(0))

如果输出True和你的显卡型号名称，说明PyTorch这边已经通了。这一步非常关键，很多人到最后Kilosort4跑不起来，回头看就是torch没识别到GPU。

2.3 安装Kilosort4主程序与附属依赖

Kilosort4的主包可以直接从GitHub仓库克隆或者用pip安装。官方推荐安装到当前环境：

bash复制pip install kilosort

也可以用源码安装，好处是方便改代码调试：

bash复制git clone https://github.com/MouseLand/Kilosort.git
cd Kilosort
pip install -e .

源码安装我推荐给需要深入改参数的进阶者，毕竟Kilosort4还在快速迭代，有时官方修复issue之后主仓库代码比PyPI上发的包还新。用-e方式装的话，直接从Git拉最新代码就能同步更新。

装完主包之后，还需要几个辅助包。官方文档里明确列了numpy、scipy、tqdm、matplotlib、numba，这些用pip直接装就行。其中numba的版本要特别注意，太新的numba会对numpy版本有硬性要求，装的时候如果出现numba和numpy的版本冲突，优先考虑把numpy降级而不是升级numba。

3. MATLAB端配置：许多人忽略但没有它跑不通

3.1 为什么Kilosort4仍然需要MATLAB

先说清楚，Kilosort4现在提供纯Python的API，但核心的尖峰检测和排序部分，官方在Python环境下运行的底层依然是调用MATLAB编译后的引擎。这意味着你的电脑上必须装有MATLAB，而且Kilosort4会通过MATLAB引擎API来建立Python和MATLAB之间的通信。

如果你没有MATLAB，也不是完全不能跑，但只能使用部分预处理功能，核心的质量指标和图形化界面输出会缺失，实际使用体验很差。所以除非你只做数据转换这种外围操作，否则还是老老实实装一个MATLAB。

3.2 配置MATLAB引擎API的完整步骤

如果你的MATLAB装好了，接下来需要让Python能够找到MATLAB的引擎。不同操作系统下路径不一样，Windows下一般在MATLAB安装目录的extern\engines\python里，Linux下类似。

打开终端，激活Kilosort4环境，然后进入该目录执行：

bash复制cd /usr/local/MATLAB/R2022b/extern/engines/python
python setup.py install

如果只装了MATLAB Runtime而没有完整MATLAB，这一步会失败，因为我上面说过了，引擎API需要完整MATLAB环境支持。装完后在Python中测试：

python复制import matlab.engine
eng = matlab.engine.start_matlab()
print(eng.eval("disp('hello')"))

能输出hello，说明Python到MATLAB的桥搭通了。我见过有人卡在这一步很久，因为Python版本和MATLAB版本不兼容，比如Python 3.10+配老版本的MATLAB R2019a，引擎API编译直接报错。建议MATLAB版本不要低于R2020b。

3.3 当需要自己编译cuda扩展时

Kilosort4在PyPI上虽然带了预编译的CUDA扩展，但不同GPU架构可能无法直接兼容，这个时候需要从源码编译。进入Kilosort源码目录：

bash复制cd Kilosort
python setup.py build_ext --inplace

这个过程会调用nvcc，所以系统里必须装好了CUDA Toolkit。编译时间视机器性能而定，一般几分钟到十几分钟。如果编译中报错提示找不到cuda.h，说明CUDA Toolkit没有正确加入环境变量。

Linux下需要把CUDA路径加到~/.bashrc：

bash复制export PATH=/usr/local/cuda-11.7/bin:$PATH
export LD_LIBRARY_PATH=/usr/local/cuda-11.7/lib64:$LD_LIBRARY_PATH

Windows下则要确认Visual Studio的MSVC工具链完整，CUDA安装时选了“Visual Studio Integration”选项。我自己在Windows上编译时，就遇到过一次因为VS版本过老导致编译器无法解析CUDA代码的报错，后来升级到VS2019才解决。

4. 首个测试运行：跑通样例数据才算安装成功

4.1 下载官方样例测试数据

Kilosort4仓库里自带了一些合成测试数据，可以拿来验证安装是否完整。如果你用pip安装的话，样例数据不在默认包里，需要单独从仓库下载。最简单的办法是直接克隆整个Kilosort仓库到本地，把其中的测试数据路径指过去。

我用的是官方在examples目录下的sampledata。这个数据量很小，但足以跑通完整的预处理、尖峰检测、排序流程。如果是自己做真实数据的话，后续可以按需生成配置参数，不过第一次测试不建议直接上百GB的探针数据，万一环境有问题，跑个几小时才报错就太浪费时间了。

4.2 通过Python API跑通全流程

确认环境后，可以写一个简短脚本测试：

python复制from kilosort import run_kilosort
from pathlib import Path

data_path = Path("path/to/sampledata/recording.dat")
settings = {
    "n_chan": 385,
    "sample_rate": 30000,
    "probe": "neuropixels",
    "n_gpu": 1,
}
results = run_kilosort(data_path, settings=settings)

有一个容易忽略的点：这里的n_chan是指通道数，Neuropixels 2.0的四探头配置是384通道，加上参考通道就是385。如果这个数字不对，后面的通道布局映射全都会错乱。sample_rate默认是30000Hz，Neuropixels原始采样率其实更高，但很多预处理在保存数据时已经降采样到30000，需要先确认自己数据实际是多少。

跑完之后，会在当前目录下生成kilosort4文件夹，里面包含排序后的聚类结果。看到输出里出现类似found 123 spikes in 0.35 GB of data这样的信息，就说明安装完全没问题了。

4.3 MATLAB调用方式的快速验证

如果你更习惯在MATLAB界面中操作Kilosort4，可以在MATLAB中直接切换到源码目录，然后调用主函数：

matlab复制addpath(genpath('path/to/Kilosort'));
runSorting('config_file.m');

这种情况下，需要确认Kilosort4自带的具体配置脚本已经按照你的数据格式改动过。用MATLAB调用虽然看起来稍微老式，但胜在可视化界面和手动调参方便，很多实验室至今仍保留这种工作流。

5. 常见安装问题和排查心得

5.1 GPU内存不足与显存溢出

这是Kilosort4安装完成后最常遇到的运行问题，原因并不复杂：Kilosort4为了追求速度，会把大量中间数据缓存在GPU上。当探针通道多、数据时间长时，显存很容易被打满。

解决思路有几个层次。第一，降低n_chan对应的批处理参数，Kilosort4支持的batch_size可以手动调小，官方默认参数较大，8GB显存往往不够。第二，用n_gpu=0强制回退到CPU模式，但这样速度会慢很多。第三，如果显卡本身只有4GB显存，建议直接换卡或者考虑用服务器的多卡并行。

我自己的经验是：Kilosort4跑Neuropixels 2.0 384通道30分钟以上的数据，最保守也要12GB显存的显卡。想用8GB显卡跑长记录，就要做好分块处理的准备，目前官方也支持分段运行再合并结果，但操作起来还是麻烦一些。

5.2 CUDA错误与版本不匹配的处理流程

安装中报CUDA error: unspecified launch failure或者no kernel image is available for execution on the device，这两个报错含义完全不同。前者多半是显存或者指针越界，后者多半是Kilosort4编译时的CUDA架构和你的显卡架构不匹配。

比如你的显卡是RTX 4090，架构是Ada Lovelace（sm_89），而Kilosort4预编译的扩展可能只适配到Ampere（sm_80）。这时候就要设置环境变量让PyTorch针对你的显卡重新生成代码：

bash复制export TORCH_CUDA_ARCH_LIST="8.9"

重新安装或编译Kilosort4的CUDA扩展之后，一般就能解决。建议在运行之前先看自己的显卡算力nvidia-smi --query-gpu=compute_cap --format=csv，然后把这个值填到环境变量里，能省掉非常多的排查时间。

5.3 MATLAB引擎启动失败或卡死

我在配置过程中遇到的最诡异的问题，是Kilosort4在Python调用MATLAB引擎时，偶尔出现启动后无响应。排查下来发现是工作目录权限的问题——MATLAB引擎进程无权写入当前目录作为临时工作空间。

解决方式是手动指定工作目录：

python复制import matlab.engine
eng = matlab.engine.start_matlab()
eng.cd(r'/path/to/writable/directory')

还有一个极端情况是，机器上同时装了多版本MATLAB，setup.py默认指向了旧版本，导致引擎版本和Kilosort4要求的新版接口不一致。这时候需要手动把旧版本引擎卸掉，重新注册新版本。Windows下可以在“控制面板-程序”里卸载MATLAB引擎相关的Python扩展，然后再从新版本目录安装一遍。

6. 一些值得收藏的参数设置和调试技巧

6.1 调整GPU参数以适配实验室数据

Kilosort4的官方默认参数，主要是基于Neuropixels 1.0和2.0的测试数据调优的。但不同实验室的电极布局、参考方式、采样频率都存在差异，直接跑默认参数往往结果不够理想。有几个参数值得仔细琢磨：

• threshold：尖峰检测阈值，默认是6，如果噪声大或信噪比低，可以降低到4-5。
• n_chan：通道数，与探针布局强相关，改成自定义探针文件时必须保持一致。
• AUCsplit：控制聚类分裂的敏感性，默认0.85过高会导致过度过分割，经验上可调至0.8。
• do_correction：漂移校正开关，数据质量好时建议关闭，能显著提升排序速度。

调试时可以先用小段数据跑一遍，根据输出的轮廓图、模板数量和尖峰波形质量判断是否需要调参。每次都全量重新运行，时间成本太高，小数据试参是更理智的做法。

6.2 将Kilosort4整合进SpikeInterface工作流

如果以后要做后续的质控、可视化、或者和其他尖峰排序器横向对比，SpikeInterface是个绕不开的工具。Kilosort4本身输出的结果格式虽然可以直接读取，但通过SpikeInterface统一处理会方便很多。

在Kilosort环境里顺手装一下：

bash复制pip install spikeinterface

然后就能用SpikeInterface的Kilosort4接口来调用：

python复制import spikeinterface.full as si
recording = si.read_binary("recording.dat", sampling_frequency=30000, num_chan=385, dtype="int16")
sorting = si.run_kilosort4(recording, output_folder="kilosort4_output")

好处是后面可以直接用si.compute_quality_metrics()计算一堆质控指标，也方便换用其他排序器对比效果，不需要改动数据读取层面的代码。

6.3 快速验证GPU环境是否健康的建议

无论安装过程多顺利，我始终建议在跑Kilosort4之前，先花几分钟做一个GPU环境健康检查。不光是PyTorch能否调用GPU，还要明确知道当前矩阵运算能跑多大规模。

我习惯用一个小脚本测试：

python复制import torch
x = torch.randn(10000, 10000, device="cuda")
y = torch.mm(x, x)
print(f"GPU memory used: {torch.cuda.memory_allocated() / 1e9:.2f} GB")

能在几秒内完成矩阵乘法且不报显存溢出，说明基本环境是健康的。这一步虽然看起来多此一举，但真能帮你区分问题是出在环境还是出在Kilosort4参数上。

7. 写在最后的几个安装体会

整套Kilosort4装下来，我个人最大的感受是：它之所以劝退很多人，不是难在某个包装不上，而是要同时维护CUDA、PyTorch、MATLAB引擎三条线之间的版本兼容。任何一个环节版本对不上，后面的报错都会带有极大的欺骗性。

如果让我重新走一遍流程，我会先花半小时把NVIDIA驱动、CUDA版本和PyTorch版本的兼容矩阵查明白，再动手装Kilosort4本身。而不是像最开始那样，先急着装完再去解决一个个报错。先查兼容关系，再动手安装，这个顺序真的能省出两三天时间。

另外，如果你要在一台多人共用的服务器上装，建议一定用conda建独立环境，不要图省事直接用base环境。服务器上环境一旦被搞乱，所有同事都会受影响，而且排查起来非常麻烦。用独立环境还能随时重建，出了问题删掉重来就行，成本很低。

最后分享一个实用技巧：Kilosort4跑完之后，它会生成一个config.json记录本次运行的全部参数，保存好这个文件非常有用。下次处理同类型数据时，直接把这个文件拷过去稍作修改，就能保证可重复性，对论文实验记录和实验室内部数据交接都是极好的存档方式。