rabbitizer

1.16.0 verified Sat May 09 auth: no python

Rabbitizer is a MIPS instruction decoder library for Python (and Rust/C) that supports multiple MIPS ISAs including R3000GTE, R4000Allegrex, R5900EE, and more. Current version is 1.16.0, with a 2.0.0-alpha series in development. It is used primarily in decompilation toolchains like Decompollaborate's tools. Release cadence is irregular, roughly monthly.

pip install rabbitizer

Common errors

error ImportError: cannot import name 'Instruction' from 'rabbitizer' ↓

cause Usually due to incomplete installation or building from source without the required dependencies (Rust compiler).

fix

Reinstall prebuilt wheels: pip install --force-reinstall rabbitizer. If that fails, check Python version compatibility.

error AttributeError: 'Instruction' object has no attribute 'opcode' ↓

cause In older versions (<1.x?) the API might be different, but in 1.16.0 'opcode' exists. Possibly a version mismatch or typo.

fix

Ensure you have version 1.16.0: pip install rabbitizer==1.16.0

error ValueError: Invalid word: ... ↓

cause The 32-bit word passed to Instruction() is not a valid MIPS instruction or has incorrect byte order.

fix

Ensure the word is a 32-bit integer (can be hex). For big-endian MIPS, you may need to byte-swap if reading from a little-endian file. Use struct.unpack('>I', ...) to get the correct word.

Warnings

deprecated Using Instruction.opcode().name() is deprecated in favor of Instruction.mnemonic_display(). The new method handles dynamic suffixed instructions (R5900EE) correctly. ↓

fix Use instr.mnemonic_display() instead of instr.opcode().name() to get the opcode string.

gotcha The library is a native extension (Rust/C) and wheels are provided for many platforms, but on PyPI only certain Python versions are prebuilt. If building from source, you need a Rust compiler and Cargo. Missing these causes a cryptic ImportError. ↓

fix Install prebuilt wheels by using a Python version and platform that has wheels (see PyPI). If you must build from source, install Rust via rustup.

Imports

Instruction

wrong

from rabbitizer.instruction import Instruction

correct

from rabbitizer import Instruction

The main classes are in the top-level package, not submodules.

RabbitizerConfig
```
from rabbitizer import RabbitizerConfig
```

Quickstart

Basic usage: create an Instruction from a 32-bit word, then access its properties.

from rabbitizer import Instruction, RabbitizerConfig

# Decode a MIPS instruction from its hex word
word = 0x0C000000  # jal 0x0
instr = Instruction(word)
print(instr.mnemonic())  # jal
print(instr.opcode().name())  # jal
print(instr.arguments())  # list of arguments

# Access register names
print(instr.rs.name())  # $zero
print(instr.rt.name())  # $zero
print(instr.rd.name())  # $zero