angr

9.2.209 verified Fri May 15 auth: no python

angr is a multi-architecture binary analysis toolkit, providing capabilities for dynamic symbolic execution, various static analyses, and program instrumentation on binaries. It is actively developed and maintained, with frequent minor and patch releases, and less frequent major version changes.

pip install angr

Common errors

error ModuleNotFoundError: No module named 'angr' ↓

cause This error occurs when the 'angr' package is not installed in the Python environment.

fix

Install 'angr' using pip: 'pip install angr'.

error ModuleNotFoundError: No module named 'distutils' ↓

cause This error occurs when the 'distutils' module is missing, often due to using Python 3.12 or later where 'distutils' is deprecated.

fix

Install the 'distutils' module using your package manager, e.g., 'sudo apt-get install python3-distutils' on Ubuntu.

error AttributeError: module 'angr' has no attribute 'Project' ↓

cause This error occurs when there is a naming conflict, such as having a script or directory named 'angr' in the working directory.

fix

Rename the conflicting script or directory to avoid the naming conflict.

error AttributeError: 'module' object has no attribute 'KS_ARCH_X86' ↓

cause This error occurs when the 'keystone' package is installed instead of 'keystone-engine', which conflicts with angr's dependencies.

fix

Uninstall 'keystone' and install 'keystone-engine' using pip: 'pip uninstall keystone' followed by 'pip install keystone-engine'.

error TypeError: unsupported operand type(s) ↓

cause This often arises during analysis when angr encounters unexpected data types in operations, potentially due to incompatible versions of angr or its dependencies, complex interactions with symbolic values, or issues within SimProcedures.

fix

Ensure all angr components and their dependencies (e.g., claripy, archinfo) are up-to-date and compatible by reinstalling them in a fresh Python virtual environment. If the issue persists with custom code, review how symbolic values and types are being handled.

Warnings

breaking With angr 9.0+, there was a significant refactoring around the 'KnowledgeBase'. Analysis results and program facts are now primarily stored in `project.kb`, instead of being directly attributes of analysis objects. Code interacting with older analysis result storage patterns will break. ↓

fix Migrate your code to access program information and analysis results via `project.kb`. Consult the official documentation for specific migration paths.

gotcha angr relies on several dependencies (like `pyvex` and `z3`) which include forked native code libraries. Installing directly into a global Python environment can lead to conflicts with existing system libraries or other Python projects. This is a common source of unexpected behavior or installation failures. ↓

fix Always install angr within a dedicated Python virtual environment (e.g., `venv`, `conda`).

gotcha Direct `pip install angr` is generally not supported on Windows due to complexities with its native code dependencies. Users on Windows typically need to install individual components manually or use the official Docker image. ↓

fix On Windows, consider using the official `angr/angr` Docker image or follow detailed source installation instructions for individual components if a native installation is required.

gotcha Binary analysis, especially symbolic execution, is computationally intensive and can be slow, leading to 'path explosion' for complex programs. Initial attempts may seem non-performant or get stuck. ↓

fix Start with small, focused binaries. Utilize angr's various analysis techniques (e.g., CFG, VSA) to reduce the search space before symbolic execution. Be mindful of state options and exploration techniques to prune irrelevant paths. Consult the 'Optimization considerations' section in the documentation.

Install

sudo apt-get install python3-dev libffi-dev build-essential

Install compatibility last tested: 2026-05-15 v9.2.102 installed · v9.2.215 latest

python os / libc status wheel install import disk mem side effects

3.10 alpine (musl) build_error - - - - - -

3.10 slim (glibc) sdist 19.2s 2.79s 354M 72.2M broken

3.11 alpine (musl) build_error - - - - - -

3.11 slim (glibc) sdist 18.9s 5.15s 397M 80.9M broken

3.12 alpine (musl) build_error - - - - - -

3.12 slim (glibc) sdist 20.9s 4.59s 378M 78.9M broken

3.13 alpine (musl) build_error - - - - - -

3.13 slim (glibc) build_error - 9.3s - - - -

3.9 alpine (musl) build_error - - - - - -

3.9 slim (glibc) sdist 27.7s 3.50s 463M 75.4M clean

Imports

angr
```
import angr
```

Quickstart

This quickstart loads a specified binary (defaults to '/bin/ls') into an angr Project, prints basic information, and creates an initial execution state. It demonstrates the fundamental steps for starting an analysis. The commented-out section shows a typical pattern for symbolic execution, which would require a specific challenge binary with known target addresses.

import angr
import os

binary_path = os.environ.get('ANGR_BINARY_PATH', '/bin/ls')

try:
    project = angr.Project(binary_path, auto_load_libs=False)
    print(f"Successfully loaded binary: {project.filename}")
    print(f"Architecture: {project.arch}")
    print(f"Entry point: {hex(project.entry)}")

    # Example of creating an initial state
    initial_state = project.factory.entry_state()
    print(f"Initial state created at: {hex(initial_state.addr)}")

    # Optional: Basic symbolic execution (requires a suitable binary and goal)
    # simgr = project.factory.simulation_manager(initial_state)
    # simgr.explore(find=0x400844, avoid=0x400850) # Replace with addresses relevant to your binary
    # if simgr.found:
    #     solution = simgr.found[0]
    #     print(f"Found solution input: {solution.posix.dumps(0)}")

except Exception as e:
    print(f"An error occurred: {e}")
    print("Please ensure 'ANGR_BINARY_PATH' is set to a valid executable, or that /bin/ls exists.")