# Kilosort4 is a new spike sorting algorithm, not a tuned Kilosort3

> Kilosort4 is a Python spike sorting pipeline with drift correction, distributed on PyPI with a Qt GUI, and it needs a CUDA capable GPU. The project is emphatic that parameters from earlier versions should not be carried over.

**MouseLand/Kilosort** — Fast spike sorting with drift correction

- Repository: https://github.com/MouseLand/Kilosort
- Website: https://kilosort.readthedocs.io/en/latest/
- Stars: 633 · Forks: 297
- Language: Python
- License: GPL-3.0
- Published: 2026-10-21 · Updated: 2026-10-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/mouseland-kilosort

## What the package actually installs

Kilosort is published on PyPI under the name kilosort, and the project describes it as a spike sorting pipeline with drift correction. The core install is small in terms of Python packages, and the dependency list in setup.py shows the shape of it: numeric work through numpy and scipy, machine learning through scikit-learn, torch as the tensor backend, numba for compiled kernels, faiss-cpu for nearest neighbour search, psutil for process and memory handling, tqdm for progress bars and matplotlib for plotting. The GUI is an optional extra built on pyqtgraph, qtpy and PyQt6, and setup.py goes out of its way to pick a working Qt binding, since if PyQt5 or PySide2 or PySide6 is already present it removes the PyQt6 entries and substitutes the matching one. Documentation builds are a third extra, with sphinx, nbsphinx, myst_parser, the sphinx read the docs theme and pandoc. The version number itself is not written in the file: setup.py uses setuptools-scm with use_scm_version, so the version is derived from the git tag at build time.

```python
install_deps = [
    'numpy>=1.20.0',
    'scipy',
    'scikit-learn',
    'tqdm',
    'torch>=2.1.0',
    'numba',
    'faiss-cpu',
    'psutil',
    'matplotlib'
]
```

## The algorithm changed, so old parameters are a trap

The README spends a paragraph warning about parameter reuse, and it is the most useful warning in the project. Kilosort4 is a new algorithm, and the main parameters, such as the detection thresholds, can affect the results in different ways than before, so reusing parameters from previous versions of Kilosort will probably not work well. The advice is to start with the default parameters and adjust from there based on what you see in Phy. The parameters themselves are documented in two places, by hovering over the name in the GUI and in kilosort.parameters.py, with a longer explanation on the parameters page of the documentation. The same section carries a warning for anyone arriving from the older versions: two bugs in Kilosort 2, 2.5 and 3, but not in 4, caused fewer spikes to be detected in roughly 7 millisecond periods at batch boundaries, which happened every 2.1866 seconds and was tracked as issue 594. The patch1 releases fix those bugs, and the project says it no longer provides in depth support for versions 1 to 3 and suggests trying Kilosort4 instead if the older versions cause trouble.

## The documented install is a conda environment plus a CUDA torch

The installation instructions are written for Anaconda distributions of Python and the conda environment manager, which the project calls the most user friendly approach, and it asks for a new issue if you use a different environment manager and need help. The steps are short, and the GPU part is the one that decides whether the run will be fast or painful.

```text
3. Create a new environment with `conda create --name kilosort python=3.11` (or any Python >= 3.9). If you have an older `kilosort` environment you can remove it with `conda env remove -n kilosort` before creating a new one.
4. To activate this new environment, run `conda activate kilosort`.
5. To install kilosort and the GUI, run `python -m pip install kilosort[gui]`. If you're on a zsh server, you may need to use `python -m pip install "kilosort[gui]" `.
6. Instead of step 5, you can install the minimal version of kilosort with `python -m pip install kilosort`.
7. To run Kilosort on GPU (strongly recommended), remove the CPU version of PyTorch with `pip uninstall torch` and proceed to 8. Otherwise, stop here.
8. Install the GPU version of PyTorch (for CUDA 11.8) with `pip3 install torch --index-url https://download.pytorch.org/whl/cu118`.
```

Two details in those steps catch people out. The environment must be activated before every run, and if you want to work through the example notebooks you also need conda install jupyter or pip install notebook in the same environment. The GUI is an extra rather than the default, and the minimal install exists for people running Kilosort4 in a pipeline.

## The GUI is a load, then run, then curate in Phy

Running the software means launching the graphical interface and walking through a short sequence, and the output is designed to be picked up by Phy, described in the project as the most popular spike sorting curating software.

```text
1. Open the GUI with `python -m kilosort`
3. Select the probe configuration (mat files recommended, they actually exclude off channels unlike prb files)
4. Hit `LOAD`. The data should now be visible.
5. Hit `Run`. This will run the pipeline and output the results in a format compatible with Phy, the most popular spike sorting curating software.
```

The step between launching and loading is where you point the interface at the path of the binary file and, optionally, the directory for results, and that is the point the project recommends putting the binary file on an SSD for faster processing. The output format is the handoff to the next tool: Kilosort4 writes results that Phy can open, which is why the curation step happens somewhere else.

## The hardware floor is 8GB of GPU memory

The system requirements are short and specific. Linux and Windows 64-bit are supported for running the code, at least 8GB of GPU RAM is required, and 12GB or more is recommended, with more recommendations in the hardware page of the documentation. The software is described as fully tested on Windows 10, Windows 11 and Ubuntu 20.04, while a subset of tests runs on macOS 13 without any guarantee of full support. The CUDA version matters too: the project notes that a different torch build may be needed depending on which CUDA version the graphics card supports, and that GeForce RTX 5000 series cards seem to work best with CUDA 12.8, while the documented install command pins the CUDA 11.8 build. The project also suggests putting the binary data file on an SSD for faster processing.

## Probes, notebooks and a deliberate distance from SpikeInterface

Three example notebooks ship in the docs/source/tutorials folder and in the documentation. The basic_example sets up a run on example data and shows how to modify parameters, load_data shows example data format conversion through SpikeInterface, and make_probe covers making a custom probe configuration. The probe step has a specific recommendation: mat files are recommended over prb files, because mat files exclude off channels, unlike prb files. The SpikeInterface relationship is deliberately limited. The project states that it does not provide support for SpikeInterface and is not involved in its development, and that if you hit problems running Kilosort4 through SpikeInterface you should run Kilosort4 directly instead. It points at the Kilosort4 GUI as a useful tool for checking that your probe and data are formatted correctly, which is a sensible debugging path in either direction.

## Phy does the curating, Kilosort4 sets the good units

The split of work with Phy is worth understanding before you interpret a result. Phy provides a manual clustering interface for refining the output of the algorithm, and Kilosort4 automatically marks the good units in Phy based on an estimated contamination rate of under 20 percent with spikes from other neurons, computed from refractory period violations. In other words the algorithm proposes, a contamination heuristic pre-marks, and a human curates. If you want to skip the local install entirely, the project also points at a Google Colab notebook that downloads test data, runs Kilosort4 on it and shows plots, which is the fastest way to see the output format before committing to the conda setup.

## A licence question the repository leaves open

Here is a detail to check before you build on this. The README licence badge states GPL v3 and links to the LICENSE file, while setup.py declares a different licence string. The repository also carries a CODE_OF_CONDUCT.md and the usual documentation and test infrastructure, with pytest.ini and tox.ini at the top level, an environment.yml and a separate environment_cpu.yml for a CPU install, and a tests directory. On releases, the version history is short and recent: v4.1.0 on 2025-07-18, v4.1.1 on 2025-08-27 and v4.1.3 on 2025-12-30, with the last push on 2026-09-25. Whatever the licence question turns out to be, the pattern of releases suggests a project in active work rather than an abandoned one, and the 2024 Nature Methods paper by Pachitariu, Sridhar, Pennington and Stringer is the citation the project asks users of versions 1 through 4 to include.

## Conclusion

Kilosort4 fits a neurophysiology lab that records extracellular data on a CUDA capable machine and curates results in Phy. It does not fit a laptop without a suitable GPU, since at least 8GB of GPU memory is required, nor a lab still standardising on Kilosort 1 to 3, which the project no longer supports in depth. Before you start, follow the conda steps with python=3.11 and install a torch build matching your CUDA version, keep the default parameters for the first run, and settle the licence question yourself, because the README badge says GPL v3 while setup.py declares a BSD licence.

## FAQ

### What hardware does Kilosort4 need to run?

At least 8GB of GPU RAM is required, and 12GB or more is recommended. Linux and Windows 64-bit are supported and the software is fully tested on Windows 10, Windows 11 and Ubuntu 20.04, while a subset of tests runs on macOS 13 without a guarantee of full support.

### How do I install Kilosort4 with the GUI?

Create a conda environment with python=3.11, activate it, and run python -m pip install kilosort[gui] for the full version or python -m pip install kilosort for the minimal one. The project writes the instructions for conda and asks for an issue if you use a different environment manager.

### Can I reuse parameters from Kilosort 3 in Kilosort4?

The project advises against it, because Kilosort4 is a new algorithm and the main parameters such as the detection thresholds affect the results differently. Start from the default parameters and adjust after looking at the output in Phy.

### Does Kilosort4 work with SpikeInterface?

The project states that it does not provide support for SpikeInterface and is not involved in its development, and suggests running Kilosort4 directly if you encounter problems through SpikeInterface. The Kilosort4 GUI is recommended as a way to check that your probe and data are formatted correctly.

## Sources

- [License: GPL-3.0](https://github.com/MouseLand/Kilosort/blob/main/LICENSE)
- [MouseLand/Kilosort on GitHub](https://github.com/MouseLand/Kilosort)
- [Project website](https://kilosort.readthedocs.io/en/latest/)
- [README](https://github.com/MouseLand/Kilosort/blob/main/README.md)
- [Releases](https://github.com/MouseLand/Kilosort/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/mouseland-kilosort