capstone

library5.0.9pypypi✓ verified 25d ago

Capstone is a lightweight, multi-platform, and multi-architecture disassembly framework. It provides robust Python bindings, allowing developers to programmatically disassemble machine code for various architectures like X86, ARM, Mips, and PowerPC. Widely used in binary analysis and reverse engineering, Capstone aims to be a comprehensive disassembly engine for the security community. The library is actively maintained, with the current stable version being 5.0.7, and receives regular updates including new architecture support and bug fixes.

serialization http-networking devops

pip install capstone

package ↗homepage ↗

INSTALL

IMPORT

SIG · CAPSTONE

capstone

serializationpythonv5.0.9

Install

1.7s avg

Import

127ms

Disk

26MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v5.0.9 · 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

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.130s · 28.4MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.7s · import 0.124s · 29MB

26MB installed

● package 26MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

✓ from capstone import Cs, CS_ARCH_X86, CS_MODE_64

✗ from capstone import *

While 'import *' works, it's generally discouraged in larger projects to avoid name collisions and improve readability. Explicitly import required symbols.

This quickstart demonstrates how to initialize the Capstone engine for different architectures (X86 64-bit and ARM) and then disassemble a byte string, printing the address, mnemonic, and operand string for each instruction.

from capstone import Cs, CS_ARCH_X86, CS_MODE_64 # X86 64-bit code to disassemble CODE = b"\x55\x48\x8b\x05\xb8\x13\x00\x00\x48\x8b\x01\x49\x8b\x40\x10\x48\x8d\x34\x24" # Initialize Capstone for X86 64-bit architecture md = Cs(CS_ARCH_X86, CS_MODE_64) # Disassemble the code print("Disassembling X86 64-bit code:") for i in md.disasm(CODE, 0x1000): print("0x%x:\t%s\t%s" % (i.address, i.mnemonic, i.op_str)) # Example with a different architecture (ARM) from capstone import CS_ARCH_ARM, CS_MODE_ARM ARM_CODE = b"\x04\xe0\x2d\xe5\x00\x00\x00\x00" md_arm = Cs(CS_ARCH_ARM, CS_MODE_ARM) print("\nDisassembling ARM code:") for i in md_arm.disasm(ARM_CODE, 0x1000): print("0x%x:\t%s\t%s" % (i.address, i.mnemonic, i.op_str))

capstone --version

Debug

Known issues

breakingCapstone undergoes significant changes between major versions (e.g., 3.0, 4.0, 5.0), introducing new features, architectures, and sometimes API modifications. For instance, version 3.0.5-rc2 had API version bumps and new `cs_option()` modes. The RISC-V module, in particular, saw enormous changes in a recent update. Users should review release notes and migration guides when upgrading across major versions.

fix

Always consult the official release notes and upgrade guides for the specific versions you are migrating between. Re-test your code thoroughly after major version upgrades.

affects: All major version upgrades (e.g., 3.x to 4.x, 4.x to 5.x)

gotchaWhen installing via `pip`, the `capstone` Python package automatically builds and includes its own native C core library. If you have a system-installed `libcapstone` and wish to use it instead, you must set the `LIBCAPSTONE_PATH` environment variable before installation to inhibit the bundled core build. Failure to do so will result in two copies of the library, potentially leading to confusion or unexpected behavior.

fix

If you intend to use a pre-existing `libcapstone` installation, set the environment variable `LIBCAPSTONE_PATH` (e.g., `export LIBCAPSTONE_PATH=/path/to/your/libcapstone`) before running `pip install capstone`.

affects: All versions where a system `libcapstone` might conflict with the pip-installed package.

breakingIn Capstone versions prior to 3.0.5-rc2, accessing irrelevant data fields when `skipdata` and `detail` modes were enabled might have silently returned default values. Since 3.0.5-rc2, the Python binding explicitly raises an error in such cases. This change ensures stricter error handling but can break older code relying on the previous, more lenient behavior.

fix

Ensure your code only accesses relevant data fields for the current instruction and mode. If you rely on `skipdata` and `detail` modes, adapt your error handling or data access logic to account for explicit error raising.

affects: Prior to 3.0.5-rc2 (leniency) to 3.0.5-rc2 and newer (strict error).

gotchaUsing `from capstone import *` is convenient for quick scripts but can lead to name collisions with other modules or variables in larger projects. This makes code less explicit and harder to debug.

fix

Prefer explicit imports, e.g., `from capstone import Cs, CS_ARCH_X86, CS_MODE_64`, to clearly identify where symbols originate and avoid potential conflicts.

affects: All versions (general Python best practice).

Errors

Common errors & fixes

ImportError: ERROR: fail to load the dynamic library.

The Python bindings for Capstone cannot find or load the underlying native Capstone C library. This often indicates an issue with the installation, missing system dependencies, or an architecture mismatch (e.g., trying to load a 32-bit library with a 64-bit Python interpreter).

fix

Ensure Capstone is correctly installed using `pip install capstone`. If the problem persists, it might require checking system library paths (LD_LIBRARY_PATH on Linux, PATH on Windows), or for platform-specific issues like incompatible architectures on macOS (e.g., Apple Silicon vs. x86_64 builds). Reinstalling Capstone may also resolve corrupted installations.

ModuleNotFoundError: No module named 'capstone'

The 'capstone' Python package is not installed in the currently active Python environment, or the Python interpreter cannot find it in its list of search paths.

fix

Install the package using pip: `pip install capstone`. If you are using virtual environments, ensure the correct environment is activated before installing or running your script.

Capstone stops at invalid instruction / Incomplete disassembly

By default, Capstone's disassembler will halt when it encounters a sequence of bytes that it cannot interpret as a valid instruction for the specified architecture and mode. This is common when executable code is interleaved with data.

fix

Enable the `skipdata` option on the disassembler engine instance by setting `md.skipdata = True`. This instructs Capstone to skip over uninterpretable bytes and attempt to resume disassembly from the next valid instruction.

ImportError: cannot import name 'Cs' from 'capstone'

This error occurs when the Python interpreter finds the 'capstone' module, but it cannot locate or import the specific name 'Cs' (or other expected components like architecture constants) from within it. This can be due to a corrupted installation, an outdated version of the bindings, or a local Python file or directory named 'capstone' shadowing the installed library.

fix

Reinstall the Capstone library to ensure all components are correctly present: `pip install --upgrade --force-reinstall capstone`. Additionally, verify that there are no local files or folders named `capstone.py` or `capstone` in your project directory that might be causing a naming conflict.

Upgrade

Version history

5.0.9latest on PyPI · released May 28, 2026

Audit

Dependencies

pythonrequiredRequires Python 3.8 or newer for the current version.

libcapstoneoptionalThe Python package bundles the native C core; typically no separate installation is required unless inhibiting the bundled build with LIBCAPSTONE_PATH.

Agent activity

37 hits · last 30 days

node

Amazon

OpenAI (training)

Resources

packagehttps://pypi.org/project/capstone/ ↗

homepagehttps://www.capstone-engine.org ↗