{"id":5545,"library":"unicorn","title":"Unicorn CPU Emulator Engine","description":"Unicorn is a lightweight, multi-platform, multi-architecture CPU emulator framework based on QEMU. It provides Python bindings for emulating various CPU architectures (ARM, AArch64, M68K, MIPS, PowerPC, RISCV, SPARC, S390x, TriCore, X86), which is widely used in security research, reverse engineering, and dynamic binary analysis. The library is actively maintained, with the current version being 2.1.4, and releases occurring frequently to address bugs, enhance features, and improve stability.","status":"active","version":"2.1.4","language":"en","source_language":"en","source_url":"https://github.com/unicorn-engine/unicorn","tags":["CPU emulation","reverse engineering","security","dynamic analysis","binary analysis"],"install":[{"cmd":"pip install unicorn","lang":"bash","label":"Install with pip"}],"dependencies":[],"imports":[{"note":"The `Uc` class is the primary entry point for the emulator.","symbol":"Uc","correct":"from unicorn import *"},{"note":"Constants for architectures, modes, and registers are typically imported from architecture-specific submodules like `unicorn.x86_const`, `unicorn.arm_const`, etc.","symbol":"UC_ARCH_X86, UC_MODE_32, UC_X86_REG_ECX","correct":"from unicorn.x86_const import *"}],"quickstart":{"code":"from unicorn import *\nfrom unicorn.x86_const import *\n\nX86_CODE32 = b'\\x41\\x4a' # INC ecx; DEC edx\nADDRESS = 0x1000000\n\nprint('Emulate i386 code')\n\ntry:\n    # Initialize emulator in X86-32bit mode\n    mu = Uc(UC_ARCH_X86, UC_MODE_32)\n\n    # Map 2MB memory for this emulation\n    mu.mem_map(ADDRESS, 2 * 1024 * 1024)\n\n    # Write machine code to be emulated to memory\n    mu.mem_write(ADDRESS, X86_CODE32)\n\n    # Initialize machine registers\n    mu.reg_write(UC_X86_REG_ECX, 0x1234)\n    mu.reg_write(UC_X86_REG_EDX, 0x7890)\n\n    # Emulate code in infinite time & unlimited instructions\n    mu.emu_start(ADDRESS, ADDRESS + len(X86_CODE32))\n\n    # Print out some registers\n    print('Emulation done. Below is the CPU context')\n    r_ecx = mu.reg_read(UC_X86_REG_ECX)\n    r_edx = mu.reg_read(UC_X86_REG_EDX)\n    print(f'>>> ECX = 0x{r_ecx:x}')\n    print(f'>>> EDX = 0x{r_edx:x}')\n\nexcept UcError as e:\n    print(f'ERROR: {e}')","lang":"python","description":"This example demonstrates how to initialize the Unicorn engine for x86 32-bit architecture, map memory, write machine code, set initial register values, execute the code, and then read the final register values. The code `INC ecx; DEC edx` increments ECX and decrements EDX."},"warnings":[{"fix":"Review official Unicorn 2.x documentation and sample code to adapt to the new API, especially for Python bindings and memory hook behavior (see below).","message":"Major API changes were introduced between Unicorn 1.x and 2.x, particularly in the Python bindings which were 'strongly typed and many improvements'. While initial 2.0.0 releases claimed backward compatibility, subsequent patches indicate reverts of 'previous break changes' and removal of 'Unicorn 1 hacks'.","severity":"breaking","affected_versions":"1.x to 2.x"},{"fix":"Ensure that memory hooks for read/write errors explicitly map the required memory region before returning `true` to indicate successful handling.","message":"The behavior of memory hooks changed significantly between Unicorn 1 and Unicorn 2. If a user's `UC_HOOK_MEM_READ`/`UC_HOOK_MEM_WRITE` hook returns `true` (indicating the issue was handled) but does not correctly map memory, Unicorn 2.x will not know how to proceed, whereas Unicorn 1.x had undefined behavior.","severity":"breaking","affected_versions":"1.x to 2.x"},{"fix":"Upgrade to Unicorn version 2.1.3 or higher immediately (`pip install --upgrade unicorn`).","message":"Previous versions (prior to 2.1.3) of the Unicorn library contained security vulnerabilities. Users are strongly urged to update to the latest version for critical security fixes.","severity":"deprecated","affected_versions":"< 2.1.3"},{"fix":"Upgrade to Unicorn version 2.1.2 or higher (`pip install --upgrade unicorn`).","message":"The Unicorn 2.1.0 release series experienced stability issues. Version 2.1.2 was released specifically to resolve these problems. Users who were on 2.1.0 or 2.1.1 are advised to upgrade.","severity":"gotcha","affected_versions":"2.1.0, 2.1.1"},{"fix":"Upgrade to version 2.1.4 or later if you are experiencing installation issues on macOS ARM64, or consider building from source for affected versions.","message":"Unicorn 2.1.2 temporarily ceased providing binary wheels for macOS ARM64 due to GitHub Actions runner limitations. While this issue has been resolved in 2.1.4 and wheels are distributed again, users might encounter build issues on macOS ARM64 for versions 2.1.2 and 2.1.3.","severity":"gotcha","affected_versions":"2.1.2, 2.1.3"},{"fix":"Review code that inspects or relies on the PC's exact value, especially in exception handling or non-hooked execution paths, to ensure it aligns with the new consistent behavior.","message":"As of version 2.1.4, Unicorn guarantees a consistent Program Counter (PC) in all emulation cases. Previous versions might have had inconsistent PC behavior for performance reasons. Code relying on the former (inconsistent) PC state might behave differently.","severity":"gotcha","affected_versions":"< 2.1.4"}],"env_vars":null,"last_verified":"2026-04-13T00:00:00.000Z","next_check":"2026-07-12T00:00:00.000Z"}