{"id":8568,"library":"pyvex","title":"pyvex","description":"PyVEX is a Python interface to libVEX, Valgrind's VEX Intermediate Representation (IR) engine. It provides bindings to translate machine code from various architectures into a common, architecture-agnostic, side-effects-free IR, facilitating static and dynamic program analysis. PyVEX is a foundational component of the angr binary analysis framework and is actively maintained with frequent releases, typically alongside the broader angr project.","status":"active","version":"9.2.211","language":"en","source_language":"en","source_url":"https://github.com/angr/pyvex","tags":["binary analysis","intermediate representation","reverse engineering","VEX IR","angr"],"install":[{"cmd":"pip install pyvex","lang":"bash","label":"Install PyVEX"}],"dependencies":[{"reason":"Required Python version.","package":"python","version":">=3.10","optional":false},{"reason":"Runtime dependency for bit manipulation.","package":"bitstring","optional":false},{"reason":"Used for Python Foreign Function Interface to interact with libVEX (C library).","package":"cffi","optional":false},{"reason":"Provides architecture definitions necessary for lifting binary code into VEX IR. While not a hard PyPI dependency, it is practically required for most usage.","package":"archinfo","optional":false}],"imports":[{"note":"The `lift` function is the primary entry point for translating binary code into VEX IR. It requires an architecture definition from `archinfo`.","symbol":"lift","correct":"import pyvex\nimport archinfo\nirsb = pyvex.lift(b'\\x90', 0x400000, archinfo.ArchAMD64())"},{"note":"The Intermediate Representation Super-Block (IRSB) is the main object representing a lifted code block.","symbol":"IRSB","correct":"from pyvex import IRSB\n# ... or access via lifted block:\n# irsb = pyvex.lift(...)\n# type(irsb) == pyvex.IRSB"}],"quickstart":{"code":"import pyvex\nimport archinfo\n\n# Binary code: 5 NOPs (0x90) for AMD64\nbinary_code = b\"\\x90\\x90\\x90\\x90\\x90\"\n# Base address for the code\nbase_address = 0x400400\n# Architecture definition\narchitecture = archinfo.ArchAMD64()\n\n# Lift the binary code into a VEX Intermediate Representation Super-Block (IRSB)\nirsb = pyvex.lift(binary_code, base_address, architecture)\n\nprint(\"--- Lifted IRSB ---\")\nirsb.pp() # Pretty-print the IRSB\n\nprint(\"\\n--- IRSB Statements ---\")\nfor stmt in irsb.statements:\n    stmt.pp()\n\nprint(\"\\n--- Next IR Expression (Jump Target) ---\")\nirsb.next.pp()\nprint(f\"Jump Kind: {irsb.jumpkind}\")","lang":"python","description":"This quickstart demonstrates how to lift a small block of AMD64 NOP instructions into PyVEX's IRSB (Intermediate Representation Super-Block). It then pretty-prints the entire IRSB, iterates through its statements, and shows how to access the default exit (jump target) expression and kind. This requires `archinfo` to be installed."},"warnings":[{"fix":"Consult the `angr` and `pyvex` release notes for detailed migration guides. Ensure all `angr` ecosystem libraries are updated to compatible versions.","message":"Major version bumps (e.g., from 8.x to 9.x) in pyvex, especially as part of the broader angr project, can introduce API changes and require specific dependency versions. This can necessitate updating related libraries like `archinfo` and `angr` in tandem to maintain compatibility.","severity":"breaking","affected_versions":"<9.0.0"},{"fix":"Avoid `max_inst=1` for architectures with delay slots or complex instruction semantics. Allow PyVEX to lift more bytes/instructions or handle `SimIRSBError` gracefully by checking if the IRSB is empty (`len(irsb.statements) == 0`).","message":"When lifting certain instruction types (e.g., MIPS branches or jumps) with `max_inst=1` (limiting to one instruction), PyVEX might return an empty IRSB because these instructions often require 'delay slots' to be processed together. This can lead to a `SimIRSBError` if an empty block is passed to downstream analysis.","severity":"gotcha","affected_versions":"All versions"},{"fix":"For deeper semantic analysis (e.g., dataflow, symbolic execution), integrate PyVEX with higher-level binary analysis frameworks like `angr` which build this context upon the VEX IR.","message":"PyVEX provides a *syntactic* representation of a basic block. This means it describes the operations and control flow but does not inherently provide semantic context like the actual data written by a store instruction or the live values of registers at a given point without further analysis.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure that the necessary C/C++ build tools for Visual Studio are fully installed, including desktop development with C++ workloads. Sometimes, manually launching the appropriate 'x64 Native Tools Command Prompt for VS' and running `pip install pyvex` from there can resolve environment path issues.","message":"Windows installations might encounter C compiler errors, often related to missing include files (e.g., 'stdarg.h') during the build process of the underlying libVEX C component, even with Visual Studio installed.","severity":"gotcha","affected_versions":"All versions on Windows"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Try reinstalling `pyvex` (`pip uninstall pyvex && pip install pyvex`). If the issue persists, check system-wide dependencies that `libVEX` might rely on (e.g., C runtime libraries).","cause":"This error typically indicates that the underlying C library (libVEX) that `pyvex` binds to could not be loaded or initialized correctly. This might be due to a corrupted installation, missing shared libraries, or environmental issues.","error":"ImportError: libvex failed to initialize"},{"fix":"Review the input `binary_code`, `base_address`, and `architecture` parameters passed to `pyvex.lift`. If using `max_inst` or `max_bytes`, consider increasing them or removing the limits to allow `pyvex` to lift a complete, valid block. Explicitly check `len(irsb.statements)` after lifting.","cause":"This specific error, often seen when using `angr` or directly manipulating `IRSB` objects, occurs when a lifted block of code (IRSB) is empty. This can happen if `pyvex.lift` fails to decode any instructions or if specific lifting parameters (like `max_inst=1` on architectures with delay slots) prevent a meaningful block from being generated.","error":"pyvex.errors.LiftingException: Empty IRSB passed to SimIRSB."},{"fix":"Ensure that 'Desktop development with C++' workload is installed for your Visual Studio version. Launch a 'x64 Native Tools Command Prompt for VS' and run `pip install pyvex` from within that environment. This ensures the correct compiler and include paths are set.","cause":"During `pip install pyvex` on Windows, this indicates a failure to compile the C components of `libVEX` because a standard C header file (`stdarg.h`) or other essential build tools are not found by the compiler.","error":"error: Unable to build libVEX. ... fatal error C1083: Cannot open include file: 'stdarg.h'"}]}