{"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":"python","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":[{"wrong":"import pyvex\nimport archinfo","symbol":"pyvex","correct":"import pyvex"},{"wrong":"pyvex.lift","symbol":"IRSBCaller","correct":"from pyvex import IRSBCaller"},{"wrong":"","symbol":"IRExpr","correct":"from pyvex import IRExpr"}],"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,"search_vec":"'activ':56 'agnost':31 'alongsid':62 'analysi':42,52,68 'angr':50,65,75 'architectur':25,30 'architecture-agnost':29 'binari':51,67 'bind':18 'broader':64 'code':22 'common':28 'compon':47 'dynam':40 'effect':34 'engin':15,72 'facilit':37 'foundat':46 'framework':53 'free':35 'frequent':59 'interfac':6 'intermedi':12,69 'ir':14,36,74 'libvex':8 'machin':21 'maintain':57 'program':41 'project':66 'provid':17 'python':5 'pyvex':1,2,43 'releas':60 'represent':13,70 'revers':71 'side':33 'side-effects-fre':32 'static':38 'translat':20 'typic':61 'valgrind':9 'various':24 'vex':11,73","created_at":"2026-04-16T17:02:51.333144+00:00","updated_at":"2026-04-16T17:02:51.333144+00:00","problems":null,"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"9.2.221","cli_name":"","cli_version":null,"type":"library","homepage":"https://api.angr.io/projects/pyvex/en/latest/","github":"https://github.com/angr/pyvex","docs":null,"changelog":null,"pypi":"https://pypi.org/project/pyvex/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["data","observability"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-30","last_verified":"2026-06-30","next_check":"2026-07-30","install_tag":null}}