{"id":9864,"library":"keystone-engine","title":"Keystone Engine Assembler","description":"Keystone Engine is a lightweight multi-architecture assembler framework, providing Python bindings to its powerful C core. It supports various architectures including X86, ARM, ARM64, MIPS, PowerPC, SPARC, SystemZ, and more. The current version is 0.9.2, and it maintains a stable release cadence focused on feature enhancements and bug fixes.","status":"active","version":"0.9.2","language":"en","source_language":"en","source_url":"https://github.com/keystone-engine/keystone","tags":["assembler","reverse-engineering","security","binary-analysis","machine-code"],"install":[{"cmd":"pip install keystone-engine","lang":"bash","label":"Install Python package"}],"dependencies":[],"imports":[{"note":"The main assembler class.","symbol":"Ks","correct":"from keystone import Ks"},{"note":"Constants for architecture and mode selection. Typically imported along with Ks.","symbol":"KS_ARCH_X86","correct":"from keystone import KS_ARCH_X86, KS_MODE_32"},{"note":"The base exception class for Keystone operations.","symbol":"KeystoneError","correct":"from keystone import KeystoneError"}],"quickstart":{"code":"from keystone import * \n\ntry:\n    # Initialize Keystone for X86-32bit architecture\n    ks = Ks(KS_ARCH_X86, KS_MODE_32)\n    \n    # Assemble a simple instruction\n    opcode, count = ks.asm(b\"inc eax\")\n    \n    print(f\"Assembled instruction bytes: {opcode}\")\n    print(f\"Number of instructions assembled: {count}\")\n    \n    # Example with multiple instructions\n    opcode_multi, count_multi = ks.asm(b\"add ecx, 10; mov eax, ebx\")\n    print(f\"Assembled multiple instructions bytes: {opcode_multi}\")\n    print(f\"Number of instructions assembled: {count_multi}\")\n\nexcept KeystoneError as e:\n    print(f\"Keystone error: {e}\")","lang":"python","description":"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."},"warnings":[{"fix":"Carefully 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.","message":"Incorrectly 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Double-check the assembly instruction string against the target architecture's syntax. Use `try...except KeystoneError` to gracefully handle assembly failures.","message":"Assembly instructions are case-insensitive for most architectures, but the syntax must be correct for the chosen architecture. Malformed instructions will raise `KeystoneError: Syntax error`.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always provide assembly instructions as byte strings, e.g., `ks.asm(b\"mov rax, 0\")`.","message":"The `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.","severity":"gotcha","affected_versions":"All versions (Python 3.x)"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Ensure `keystone-engine` is installed correctly: `pip install keystone-engine`. If in a virtual environment, ensure it's activated.","cause":"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.","error":"ImportError: No module named 'keystone'"},{"fix":"Verify 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.","cause":"The architecture specified during `Ks` initialization is invalid or not supported by Keystone.","error":"keystone.KeystoneError: Invalid architecture (KS_ERR_ARCH)"},{"fix":"Review the assembly instruction for typos, incorrect registers, or unsupported mnemonics. Ensure it conforms to the target architecture's assembly syntax.","cause":"The provided assembly instruction string is syntactically incorrect for the chosen architecture and mode.","error":"keystone.KeystoneError: Syntax error (KS_ERR_ASM_SYNTAX)"}]}