Kilosort4安装教程：从CUDA/PyTorch环境配置到GPU加速实战

1. 安装前必须搞清楚的3件事

Kilosort4 是当前神经电生理数据处理领域最热门的尖峰排序工具之一，很多做 Neuropixels、硅极探针或高密度阵列记录的课题组都在从旧版 Kilosort 2.5 / 3 往 Kilosort4 迁移。我接触 Kilosort4 是在一个多探针联合记录项目里，当时实验室服务器上的 CUDA 环境一团乱麻，装了两天才把环境理顺。后来帮好几个师弟师妹装过，发现大家踩的坑高度集中，基本都在环境匹配和 GPU 调用这两块。

先说结论：Kilosort4 的安装本身并不复杂，真正的门槛在于你的计算机有没有一块支持 CUDA 的 NVIDIA 显卡、Python/CUDA/PyTorch 版本是否匹配，以及 Windows 用户是否提前处理了动态链接库依赖。把这几个前置问题解决了，安装过程其实就是几条命令的事。

这篇教程适合谁：准备自己处理神经数据的新手研究生、从 MATLAB 版 Kilosort 迁移过来的老用户、以及要在实验室服务器上部署 Kilosort4 的课题组管理员。我会尽量把每一步的原理也讲清楚，而不是只丢给你一串命令，这样出了问题你知道从哪里排查。

1.1 Kilosort4 到底是个什么软件

简单说，Kilosort4 是一个基于 GPU 加速的尖峰排序算法，作用是把神经探针记录到的原始电压信号，自动拆分成一个个神经元的动作电位序列。你可以把它理解成“从一场几十个人的嘈杂对话录音里，把每个人的发言逐字分离出来”的工具，只不过这里的“人”是神经元，“对话录音”是高密度电极记录到的电信号。

和上一代 Kilosort 2.5 相比，Kilosort4 的核心改进是把深度学习和传统模板匹配结合得更紧密，引入了一种更灵活的漂移校正策略，处理长时间记录（比如连续记录几个小时甚至几天）时稳定性好很多。它不需要人工设置太多阈值参数，默认参数已经能跑出不错的结果。软件目前官方支持 Python 和 MATLAB 两种调用方式，但社区里绝大多数人用的是 Python 版本，因为配置更灵活、也更容易嵌入到你自己的分析 pipeline 里。

从安装视角看，Kilosort4 以 Python 包的形式发布在 PyPI 上，底层用 PyTorch 做神经网络推理，用 CUDA 做 GPU 加速，还依赖 numba 做 JIT 编译。理解了这条依赖链，你就明白为什么安装时容易出问题：任何一个环节的版本对不上，都会导致导入失败或者运行时报错。

1.2 你的电脑能不能跑（硬件与系统要求）

稍微冷峻一点说，Kilosort4 不是拿来就能跑的软件。它严重依赖 NVIDIA GPU 和 CUDA 生态，所以你的电脑必须满足下面这些硬性条件：

注意，Kilosort4 官方并不支持 AMD 显卡和苹果 M 系列芯片的 GPU 加速，虽然在 CPU 上理论也能跑，但速度会慢到让人怀疑人生，实操中没有意义。我们实验室有人试过在 MacBook 上用 CPU 模式跑 Kilosort4，一小段测试数据跑了快一个小时，而同一份数据放到 RTX 3090 上只要几分钟。

另外，你最好确认一下自己的 NVIDIA 驱动是否更新。方法很简单：在命令行输入 nvidia-smi，能看到 GPU 型号和驱动版本就说明驱动正常。如果你连 nvidia-smi 都执行不了，那大概率是驱动没装好，后面的步骤都无从谈起。

1.3 安装方式与“环境隔离”的必要性

为什么要单独说“环境隔离”？因为我见过太多人直接把 Kilosort4 装进系统默认的 Python 环境里，结果和 TensorFlow、旧版 PyTorch、其他科学计算包互相打架，最后依赖冲突到崩溃。Kilosort4 依赖的 PyTorch、numba、h5py 等库版本都很敏感，强烈建议你专门为它创建一个独立的 Python 环境。

隔离环境用 Anaconda 或 Miniconda 都行，我习惯用 Miniconda，因为它轻量，不预装一堆你用不到的包。后面我也会从 Miniconda 的安装讲起，带着大家一步步建环境。这一步真的别跳，它能在未来给你省掉大量的排错时间。

提示：如果你实验室的服务器已经有一个很老很乱的 Python 环境，尤其装了 TensorFlow 或老版本 PyTorch 的，建议不要在当前环境里硬装 Kilosort4。经验之谈，独立环境最省心。

2. 从零搭建 Python 与 CUDA 环境（保姆级）

这一节是所有步骤里最容易出问题的地方。Kilosort4 本身安装很快，但环境搭错会让你在验证环节卡住。我会带你把每一步都走一遍，并讲清楚每一条命令为什么这么写。

2.1 安装 Miniconda 并创建专用环境

Miniconda 的安装包可以去官网下载，Windows 用户注意在安装时勾选“Add Miniconda3 to my PATH”，否则后面命令行里找不到 conda 命令。Linux 用户下载 .sh 文件后执行：

bash复制bash Miniconda3-latest-Linux-x86_64.sh

装完之后创建一个专门给 Kilosort4 用的环境：

bash复制conda create -n kilosort4 python=3.10 -y
conda activate kilosort4

我推荐 Python 3.10。Kilosort4 官方写的是 Python 3.8 以上，但实际测试中 3.9 和 3.10 兼容性最好，3.11、3.12 有时会在 numba 或某些编译依赖上踩坑。创建环境时顺手把 python=3.10 写死，保险。

进入环境后，先升级一下 pip，避免后续安装时出现一些莫名其妙的版本解析问题：

bash复制pip install --upgrade pip

2.2 CUDA、cuDNN 与 PyTorch 的版本匹配

这里是最容易翻车的地方。Kilosort4 依赖 PyTorch，而 PyTorch 需要和你机器上的 CUDA 版本匹配。但这个“匹配”并不要求你手动安装完整的 CUDA Toolkit，因为 PyTorch 自带了 CUDA 运行时库。你真正需要关心的只有两件事：

第一，显卡驱动要足够新，支持你选定的 CUDA 版本。用 nvidia-smi 看右上角的 “CUDA Version”，比如显示 CUDA Version: 12.2，代表你的驱动最高支持 CUDA 12.2。只要 PyTorch 要求的 CUDA 版本小于等于这个数字，就能正常工作。

第二，安装 PyTorch 时选择对应的 CUDA 版本源。以 CUDA 11.8 为例，官方推荐的安装命令是：

bash复制pip install torch torchvision --index-url https://download.pytorch.org/whl/cu118

如果你的驱动支持 CUDA 12.x，也可以装 cu121 或更高版本：

bash复制pip install torch torchvision --index-url https://download.pytorch.org/whl/cu121

这里有个常见误区：很多人以为必须先手动安装 CUDA Toolkit，其实不是。你只需要保持 NVIDIA 驱动够新，PyTorch 自己会带上它需要的 CUDA 库。Kilosort4 底层是通过 PyTorch 调用 GPU 的，所以 PyTorch 能识别 GPU，Kilosort4 基本也就没问题。

安装完后可以用一句话验证 PyTorch 是否能看到 GPU：

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

如果输出 True 并显示你的显卡型号，恭喜，环境这一关已经过了大半。如果输出 False，不要急着继续，先检查驱动版本和 PyTorch 的 CUDA 版本是否匹配。常见原因是你装了 CPU 版的 PyTorch，把 --index-url 对应的 whl 源去掉后默认下载的就是 CPU 版，千万注意。

注意：Kilosort4 在某些版本组合下还依赖 cuDNN，但 PyTorch 在安装时会自动带上匹配的 cuDNN 动态库，一般情况下不需要你手动处理。除非你从源码编译且追求自定义 cuDNN 版本，否则不用额外操心。

2.3 编辑器选择与工作目录规划

到这一步，环境已经成熟，接下来要准备一个干净的工作目录。很多初学者喜欢用 Jupyter Notebook 直接跑，但我更推荐先用命令行验证安装，再用 VSCode 或 PyCharm 打开项目目录进行正式的数据处理。因为 Kilosort4 在运行时会生成大量中间文件和日志，用一个规范的目录结构能让你后期排查轻松很多。

我习惯这样组织目录：

text复制project_root/
├── data/          # 原始数据，通常是 .bin / .dat / .npy
├── results/       # Kilosort4 输出结果
├── settings/      # 自定义配置文件
└── scripts/       # 自己写的分析脚本

如果你用 VSCode，安装好 Python 插件后，按 Ctrl+Shift+P 选择解释器，直接选中你刚才创建的 kilosort4 环境即可。用 PyCharm 的话，新建项目时在解释器设置里选择 Conda Environment，然后指向 kilosort4。

3. Kilosort4 安装实操

环境准备妥了，现在正式开始安装 Kilosort4。我会讲两条路径：最省事的 pip 安装和适合折腾的源码安装。大多数人走第一条就够了。

3.1 用 pip 安装 Kilosort4（最简路径）

激活 kilosort4 环境后，直接执行：

bash复制pip install kilosort

这条命令会安装 Kilosort4 本体以及它的核心依赖，包括 numpy、scipy、matplotlib、tqdm、numba、h5py、sklearn 等。值得注意的是，Kilosort4 的默认安装包会尝试编译一些基于 CUDA 的扩展，如果你的 CUDA 环境有问题，这里可能直接报错。

安装过程如果顺利，你会看到类似 Successfully installed kilosort-4.x.x 的信息。如果安装过程中出现红色报错，先不要慌，看清楚是哪个依赖出了问题。最常见的是 numba 安装失败或版本冲突，可以手动指定一个兼容版本再装：

bash复制pip install numba==0.57.1
pip install kilosort

numba 对 Python 版本和 numpy 版本都有严格限制，这也是我推荐 Python 3.10 的原因之一，numba 在 3.10 下的兼容性最成熟。

3.2 从 GitHub 源码安装（进阶路径）

如果你希望使用最新开发版、或者需要修改源码调试，可以选择 git clone 方式安装。打开终端，进入你规划好的工作目录，执行：

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

这里 pip install . 会执行源码目录里的 setup.py，同样会拉取依赖并编译 CUDA 扩展。和 pip 安装相比，源码安装的差别主要在于你可以拿到更新的代码，还能在本地修改 kilosort 内部的模块。但要注意，源码版本可能有未稳定发布的新特性，遇到 bug 的概率也更高。我的建议是：想要稳定复现结果，用 PyPI 版；想要追新功能，用源码版。

3.3 Windows 用户注意：libzmq 依赖

如果你在 Windows 上安装 Kilosort4，装完包之后导入时可能会碰到一个叫 libzmq 的动态库缺失报错。这也是 Windows 上最经典的坑之一，错误信息大致是：

text复制ImportError: DLL load failed while importing kilosort

Kilosort4 的某些组件依赖 ZeroMQ 库，而 Windows 系统并不会自动帮你准备好对应的 .dll 文件。解决办法是下载 libzmq-mt-4_3_4-win64.dll，把它复制到与 kilosort 包同一个目录下，或者直接放到你的 C:\Windows\System32 文件夹里。还有一种更省事的办法是用 conda 安装 pyzmq：

bash复制conda install pyzmq

我个人在 Windows 工作站上实际测试，用 conda 安装 pyzmq 之后，libzmq 缺失的问题基本不会再出现，推荐优先尝试。

3.4 安装完成后的目录结构理解

安装完成后，你可以通过 pip show kilosort 查看包的具体安装位置。Kilosort4 的包里主要包含：

了解这些模块的位置对后续调参很重要。尤其是 parameters.py，里面定义了所有默认参数，包括批大小、阈值、漂移校正选项等。当你需要针对自己的数据做微调时，可以直接读取或修改这个文件。理解包结构也能帮你在报错时更快定位问题出在哪个环节。

4. 验证安装与第一次运行

很多人在这一步翻车，pip 装得挺顺利，结果一 import 就崩。所以验证环节我单独拿出来详细讲，把我会遇到的高频报错一并说明。

4.1 快速检查导入是否成功

激活环境后进入 Python，执行：

python复制import kilosort
print(kilosort.__version__)

如果没有任何报错并输出版本号，说明核心模块导入成功。如果这一步报错，请看下面的常见问题表：

导入成功只代表 Python 层面没问题，不代表 GPU 层面没问题。还需要实际跑一次小数据测试。

4.2 使用自带测试数据试跑

Kilosort4 的 GitHub 仓库里提供了一个测试数据生成脚本，可以生成一小段模拟数据，用来验证整个 pipeline 是否通顺。你可以在源码目录里找到示例 notebook，也可以用我下面这段代码来做快速验证：

python复制import numpy as np
from pathlib import Path
from kilosort import run_kilosort

# 创建测试数据目录
test_dir = Path('./test_kilosort')
test_dir.mkdir(exist_ok=True)

# 构造一段模拟原始数据：float32，200个通道，100秒，30kHz采样率
num_channels = 200
sample_rate = 30000
duration = 100
data = np.random.randn(duration * sample_rate, num_channels).astype('float32')
bin_file = test_dir / 'test_data.bin'
data.tofile(bin_file)

settings = {
    'data_dir': test_dir,
    'n_chan_bin': num_channels,
    'fs': sample_rate,
}

results = run_kilosort(settings)
print('Kilosort4 运行完成，输出文件保存在：', results)

这里我故意用纯随机噪声数据，其实没有任何真实神经信号，跑出来不会有有意义的尖峰结果，但它能完整走一遍数据读取、GPU 预处理的流程，是检验安装是否彻底的“冒烟测试”。

如果你用的是真实数据，需要在 settings 里正确指定 n_chan_bin、fs、dat_file 等关键信息。Kilosort4 默认读取二进制文件，通常是 float32 类型，且按“采样点 × 通道”的顺序存储。文件格式错了会直接导致运行报错或结果异常。

注意：run_kilosort 在运行时会要求你指定 data_dir 里有对应的 .bin 或 .dat 文件，不同版本对字段名稍有差异。如果遇到 KeyError: 'probe' 或类似提示，通常是缺少了探针几何信息相关的设置，需要补充 probe 字段或在配置里指定探针文件。

4.3 查看输出结果与关键日志

Kilosort4 运行完成后，会在 data_dir 下生成一系列文件，常见的有：

我强烈建议大家养成查看 log.txt 的习惯。Kilosort4 会把每个阶段的耗时、GPU 使用、数据维度信息都写入日志。如果你发现某一步耗时异常长，或者某个警告反复出现，多半是参数或数据格式设置不合理。

另一点提醒，不同版本的 Kilosort4 输出文件名可能略有差异，建议先在自己的数据上跑一次完整的默认流程，确认生成文件符合预期，再开始定制参数。

4.4 GPU 显存不足与 CUDA 报错速查

验证过程中最常见的 GPU 相关问题无非两类。

一类是 CUDA out of memory。这通常是因为 Kilosort4 默认会使用你 GPU 的大部分显存，如果你同时还在跑其他程序，显存不够就会报错。解决办法是在运行前设置环境变量限制 PyTorch 显存占用：

bash复制export PYTORCH_CUDA_ALLOC_CONF=max_split_size_mb:128

或者在代码里跳过某些显存占用大的模块。还有一个更直接的办法：换一块显存更大的 GPU，或者把数据分块处理，不要一次性灌入整段原始数据。

另一类是 CUDA driver version is insufficient。这种情况多发生在驱动太老、PyTorch 版本太新的组合上。先看驱动的 CUDA 版本，再看 PyTorch 要求的版本，如果驱动不够高，只能升级驱动，没有捷径。很多老服务器的系统管理员不愿意动驱动，我的建议是尽量在系统允许范围内把驱动升到较新版本，毕竟 Kilosort4 和 PyTorch 都不会为旧驱动做兼容。

5. 安装与运行中的高频问题排查

这一节总结我在实验室和帮别人装机时反反复复遇到的高频坑。每一条都是从真实报错里提炼出来的，强烈建议收藏留档。

5.1 GPU 无法识别 / CUDA 不可用

症状：torch.cuda.is_available() 返回 False。

排查步骤：

1. 运行 nvidia-smi，确认驱动正常且能看到 GPU。
2. 运行 python -c "import torch; print(torch.version.cuda)" 查看 PyTorch 编译时的 CUDA 版本。
3. 确认你安装的 PyTorch 不是 CPU 版。CPU 版的 wheel 文件名里会有 cpu 字样，安装时如果不指定 --index-url，默认可能就装成 CPU 版了。
4. 如果驱动没问题但 PyTorch 看不到 GPU，尝试重装对应 CUDA 版本的 PyTorch：

bash复制pip install torch torchvision --index-url https://download.pytorch.org/whl/cu121

疑似 nvidia-smi 显示 CUDA Version 12.x，但 --index-url cu118 的 PyTorch 不识别时，升级到 cu121 试试。PyTorch 要求驱动 CUDA 版本不低于编译版本，但高于一定范围一般也能兼容，不过偶尔有例外，直接匹配最稳。

5.2 编译错误、缺少 DLL 或 libstdc++

症状：导入 kilosort 时提示找不到 .dll 或 .so 文件，比如 libzmq、libstdc++-6.dll、cudart64_*.dll 等。

这类问题在 Windows 上尤其普遍。处理方法：

• 优先用 conda install pyzmq 解决 libzmq 问题。
• 对于其他缺失的 DLL，去搜索对应的运行时库安装包。最常见的是 Microsoft Visual C++ Redistributable，很多科学计算包都依赖它。如果运行 Python 时提示缺 VC 运行库，去微软官网下载最新的 vc_redist.x64.exe 安装即可。
• 在 Linux 上若提示缺 libstdc++ 相关库，说明本机 gcc 版本过旧，Kilosort4 的 CUDA 扩展是针对较新编译环境构建的，需要升级 gcc：

bash复制sudo apt install gcc-11 g++-11

或者用 conda 装一个较新的 gcc 到当前环境里：

bash复制conda install gcc_linux-64

这个方向最容易让新手抓狂，因为报错时根本不知道去哪找对应的库。我的经验是先看报错是发生在 import kilosort 还是运行 Kilosort4 的某个具体功能时。如果是后者，通常和 numba 的 JIT 编译环境有关，优先考虑 numba 版本问题。

5.3 数据路径和文件格式问题

症状：Kilosort4 开始运行后报错找不到文件、读取维度不对，或者结果输出为空。

Kilosort4 对数据格式的默认要求是：

如果报错信息里出现 error while reading binary file，先检查文件路径是否写对，再确认 n_chan_bin 是否和实际通道数一致。很多人的二进制文件是 int16 类型的，这在 Kilosort 早期版本很常见，但 Kilosort4 默认按 float32 处理。如果你的数据是 int16，需要在 settings 里显式声明，或者在预处理时转成 float32。

另外，Kilosort4 需要你提供探针的几何信息，也就是每个通道在物理空间中的坐标。Neuropixels 探针通常有标准配置，如果你用的是 Neuropixels 1.0/2.0，社区里有现成的配置文件，直接拿去用即可。如果用的是自定义探针，需要你自己准备一个 probe 文件，格式通常是 .npy 或 .mat，里面包含通道坐标和连接的参考通道信息。很多人忽略这一步，结果 Kilosort4 能装成功但跑起来就报 probe 相关错误。

5.4 安装到一半卡住或超时

Kilosort4 以及它依赖的 PyTorch、numba 体积都不小，国内网络环境下经常出现下载超时或中断。如果在安装过程中卡在 Downloading... 很久，建议配置国内 pip 镜像源提速：

bash复制pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple

注意，PyTorch 这种带 CUDA 依赖的包，用 PyPI 主源或镜像源可能拿不到正确的 GPU 版本，所以安装 PyTorch 时仍然建议使用官方 --index-url 指定的 wheel 源。Kilosort4 本体和其余依赖则可以通过镜像源加速安装。实际操作时，我会先装 PyTorch，再临时切换镜像源装 kilosort，两者互不干扰。

如果镜像源也慢，另一个办法是直接下载 wheel 文件，再用 pip install /path/to/xxxx.whl 离线安装。这个方法在服务器没有外网权限时很实用，我经常在实验室的离线机器上把安装包下载好后手动传上去装。

5.5 装好之后不会用：关于 MATLAB 版本的补充

不少老用户第一次接触 Kilosort4 时，还停留在 Kilosort 3 的 MATLAB 工作流里。Kilosort4 其实也保留了大量 MATLAB 相关的配置文件和数据接口，但官方推荐的 Python 工作流已经非常成熟，我不建议新用户再从 MATLAB 端入手。主要原因有两个：一是 MATLAB 端需要额外配置 MEX 编译环境，和 Python 版相比更容易出兼容问题；二是 Python 版的参数调优、批处理、结果可视化生态更完整，后续衔接 Phy、SpikeInterface 等工具也更方便。

如果你确实需要在 MATLAB 里调用 Kilosort4，安装思路是在 MATLAB 中先配置好 Python 环境，然后通过 MATLAB 的 py. 接口调用 py.kilosort.run_kilosort(...)。但这套链路的前提依然是你先在本机的 Python 环境里把 Kilosort4 装好，否则 MATLAB 端一无所获。所以我始终坚持：先把 Python 版跑通，再考虑 MATLAB 集成。

结尾：说点安装之外的实在话

装 Kilosort4 这件事，看着像是一个“跟着命令敲一遍”的流程，实际上一大半时间花在环境匹配上。我个人编译配环境的经验是：永远先确认 GPU 驱动和 PyTorch 之间的兼容关系，再动手装包；永远为 Kilosort4 建独立环境，不要偷懒直接 pip install 到 base 环境；遇到报错时先看日志和版本信息，不要盲目重装。如果你在安装过程中反复卡在同一个位置，尤其是 CUDA 相关报错，先去查一下目标机器是不是被别人占用了显存，或者驱动是不是很久没更新。我的经验里，这两种情况占了“安装没做错但死活跑不起来”的一半以上。

最后分享一个小技巧：Kilosort4 每次升级后，默认参数可能有细微变化，建议在正式跑实验数据之前，先用本地生成的模拟数据做一次完整回归测试，确认 GPU、依赖和输出文件都正常。很多神经数据分析团队都有自己的 “smoke test” 脚本，内容基本就是生成一段模拟数据、跑一次 Kilosort4、检查输出文件是否齐全。别嫌这一步麻烦，它能在你开始处理一周的连续记录数据之前，把环境问题提前暴露出来。