Install & Compatibility
Where this runs
tested against v0.9.2 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.910 runs
build_error
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 1.6s · import 0.051s · 25MB
23MB installed
● package 23MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Ks
✓ from keystone import Ks
The main assembler class.
KS_ARCH_X86
✓ from keystone import KS_ARCH_X86, KS_MODE_32
Constants for architecture and mode selection. Typically imported along with Ks.
KeystoneError
✓ from keystone import KeystoneError
The base exception class for Keystone operations.
This quickstart demonstrates how to initialize the Keystone assembler for a specific architecture and mode (X86-32bit) and then assemble a simple assembly instruction string into its corresponding bytecode. It also shows basic error handling.
from keystone import *
try:
# Initialize Keystone for X86-32bit architecture
ks = Ks(KS_ARCH_X86, KS_MODE_32)
# Assemble a simple instruction
opcode, count = ks.asm(b"inc eax")
print(f"Assembled instruction bytes: {opcode}")
print(f"Number of instructions assembled: {count}")
# Example with multiple instructions
opcode_multi, count_multi = ks.asm(b"add ecx, 10; mov eax, ebx")
print(f"Assembled multiple instructions bytes: {opcode_multi}")
print(f"Number of instructions assembled: {count_multi}")
except KeystoneError as e:
print(f"Keystone error: {e}")
Debug
Known issues
gotchaIncorrectly specifying the architecture (KS_ARCH_*) or mode (KS_MODE_*) can lead to assembly failures or incorrect output. Always ensure these constants match the target CPU and instruction set.fixCarefully select the `KS_ARCH_*` and `KS_MODE_*` constants when initializing `Ks`. For example, `Ks(KS_ARCH_ARM, KS_MODE_ARM + KS_MODE_THUMB)` for ARM Thumb mode.
affects: All versions
gotchaAssembly instructions are case-insensitive for most architectures, but the syntax must be correct for the chosen architecture. Malformed instructions will raise `KeystoneError: Syntax error`.fixDouble-check the assembly instruction string against the target architecture's syntax. Use `try...except KeystoneError` to gracefully handle assembly failures.
affects: All versions
gotchaThe `Ks.asm()` method expects a byte string (e.g., `b"inc eax"`) for the instruction. Passing a regular string might work on some Python versions or implicitly convert, but explicit byte strings are safer and more consistent.fixAlways provide assembly instructions as byte strings, e.g., `ks.asm(b"mov rax, 0")`.
affects: All versions (Python 3.x)
Errors
Common errors & fixes
ImportError: No module named 'keystone'
The Python package is named `keystone-engine` on PyPI, but its internal module is `keystone`. This error usually occurs if the package was not installed or if there's a virtual environment issue.
fixEnsure `keystone-engine` is installed correctly: `pip install keystone-engine`. If in a virtual environment, ensure it's activated.
keystone.KeystoneError: Invalid architecture (KS_ERR_ARCH)
The architecture specified during `Ks` initialization is invalid or not supported by Keystone.
fixVerify that you are using a valid `KS_ARCH_*` constant (e.g., `KS_ARCH_X86`, `KS_ARCH_ARM`). Refer to the `keystone` module for available constants.
keystone.KeystoneError: Syntax error (KS_ERR_ASM_SYNTAX)
The provided assembly instruction string is syntactically incorrect for the chosen architecture and mode.
fixReview the assembly instruction for typos, incorrect registers, or unsupported mnemonics. Ensure it conforms to the target architecture's assembly syntax.
Upgrade
Version history
0.9.2latest on PyPI · released Jun 21, 2020
Audit
Dependencies
No dependency data recorded yet.