spimdisasm

A matching MIPS disassembler API and front-ends with built-in instruction analysis.

Currently supports all the CPU instructions for MIPS I, II, III and IV.

Mainly focused on supporting Nintendo 64 binaries, but it should work with other MIPS platforms too.

Features

Produces matching assembly.
Supports .text, .data, .rodata and .bss disassembly.
- The reloc section from Zelda 64 and some other games is supported too, but no front-end script uses it yet.
Generates separated files for each section of a file (.text, .data, .rodata and .bss).
Supports multiple files spliting from a single input binary.
Automatic function detection.
- Can detect if a function is handwritten too.
hi/lo pairing with high success rate.
Automatic pointer and symbol detection.
Function spliting with rodata migration.
Supports floats and doubles in rodata.
String detection with medium to high success rate.
Allows to set user-defined function and symbol names.
Big, little and middle endian support.
Autogenerated symbols can be named after the section they come from (RO_ and B_ for .rodata and .bss sections) or its type (STR_, FLT_ and DBL_ for string, floats and doubles respectively).
Simple file boundary detection.
- Detects boundaries on .text and .rodata sections
Lots of features can be turned on and off.
MIPS instructions features:
- Named registers for MIPS VR4300's coprocessors.
- Support for many pseudoinstructions.
- Properly handle move to/from coprocessor instructions.
- Support for numeric, o32, n32 and n64 ABI register names.
Some workarounds for some specific compilers/assemblers:
- SN64/PSYQ:
  - div/divu fix: tweaks a bit the produced div, divu and break instructions.
Support for specific MIPS instruction sets:
- N64's RSP instruction disassembly support.
  - RSP decoding has been tested to build back to matching assemblies with armips.
- PS1's R3000 GTE instruction set support.
- PSP's R4000 ALLEGREX instruction set support.
- PS2's R5900 EE instruction set support.
(Experimental) Same VRAM overlay support.
- Overlays which are able to reference symbols from other overlays in other categories/types is supported too.
- NOTE: This feature lacks lots of testing and probably has many bugs.

Installing

The recommended way to install is using from the PyPi release, via pip:

python3 -m pip install -U spimdisasm

If you use a requirements.txt file in your repository, then you can add this library with the following line:

spimdisasm>=1.42.4,<2.0.0

Development version

The development version is located at the 1.x branch.

The recommended way to install a locally cloned repo is by passing the -e (editable) flag to pip.

python3 -m pip install -e .

In case you want to mess with the latest development version without wanting to clone the repository, then you could use the following command:

python3 -m pip uninstall spimdisasm
python3 -m pip install git+https://github.com/Decompollaborate/spimdisasm.git@1.x

NOTE: Installing the development version is not recommended unless you know what you are doing. Proceed at your own risk.

Versioning and changelog

This library follows Semantic Versioning. We try to always keep backwards compatibility, so no breaking changes should happen until a major release (i.e. jumping from 1.X.X to 2.0.0).

To see what changed on each release check either the CHANGELOG.md file or check the releases page on Github. You can also use this link to check the latest release.

How to use

This repo can be used either by using the existing front-end scripts or by creating new programs on top of the back-end API.

Front-end

Every front-end CLI tool has its own --help screen.

The included tool can be executed with either spimdisasm modulename (for example spimdisasm disasmdis --help) or directly modulename (for example spimdisasm --help)

singleFileDisasm: Allows to disassemble a single binary file, producing matching assembly files.
disasmdis: Disassembles raw hex passed to the CLI as a MIPS instruction.
elfObjDisasm: [EXPERIMENTAL] Allows to disassemble elf files. Generated assembly files are not guaranteed to match or even be assemblable.
rspDisasm: Disassemblies RSP binaries.

Back-end

TODO

Check the already existing front-ends is recommended for now.

References

Metadata

Release files for spimdisasm 1.42.4

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for spimdisasm 1.42.4
File	Size	Uploaded
spimdisasm-1.42.4.tar.gz	110.8 kB	Aug 6, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for spimdisasm 1.42.4
File	Interpreter	ABI	Platform	Reset
spimdisasm-1.42.4-py3-none-any.whl 141.2 kB Aug 6, 2026	Python 3	none	any	Details

Total release size: 252.0 kB

Release files / spimdisasm-1.42.4.tar.gz

Download URL	spimdisasm-1.42.4.tar.gz
Size	110.8 kB
Tags	Source
SHA-256 checksum How to use checksums	`0a2c8db54615226288b7f6c86edcc844a654df96321572fa8b8e35667e1b903f`
BLAKE2b-256 checksum How to use checksums	`7c3165d8d495cf76ab134641f5baa31b5b78b91753cd3bbbef92fd1116533fd9`
Upload date	Aug 6, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/6.1.0 CPython/3.13.7`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/Decompollaborate/spimdisasm
Publishing commit: github.com/Decompollaborate/spimdisasm/tree/4b5d4c68eeb9f9eae14b3bb713971433ae2c3c43

Workflow

Publishing configuration: github.com/Decompollaborate/spimdisasm/blob/4b5d4c68eeb9f9eae14b3bb713971433ae2c3c43/.github/workflows/ci.yml
Publishing logs: github.com/Decompollaborate/spimdisasm/actions/runs/31100356678/attempts/1

Artifact

Subject: spimdisasm-1.42.4.tar.gz
SHA-256 checksum: 0a2c8db54615226288b7f6c86edcc844a654df96321572fa8b8e35667e1b903f Verifying attestations

Release files / spimdisasm-1.42.4-py3-none-any.whl

Download URL	spimdisasm-1.42.4-py3-none-any.whl
Size	141.2 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`816111a7d80a9037029a8fff0b12eec5a55358a52407f85498aa9b14e9e69a5f`
BLAKE2b-256 checksum How to use checksums	`3fc420a1e2966a536c3ab3882acec2c42a08c0f8a06c5ec906c51c886363c0bc`
Upload date	Aug 6, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/6.1.0 CPython/3.13.7`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/Decompollaborate/spimdisasm
Publishing commit: github.com/Decompollaborate/spimdisasm/tree/4b5d4c68eeb9f9eae14b3bb713971433ae2c3c43

Workflow

Publishing configuration: github.com/Decompollaborate/spimdisasm/blob/4b5d4c68eeb9f9eae14b3bb713971433ae2c3c43/.github/workflows/ci.yml
Publishing logs: github.com/Decompollaborate/spimdisasm/actions/runs/31100356678/attempts/1

Artifact

Subject: spimdisasm-1.42.4-py3-none-any.whl
SHA-256 checksum: 816111a7d80a9037029a8fff0b12eec5a55358a52407f85498aa9b14e9e69a5f Verifying attestations