gitwtfhub

wtf is unicorn?

unicorn-engine/unicorn — explained in plain English

Analysis updated 2026-06-24

8,954CAudience · researcherComplexity · 4/5LicenseSetup · moderate

TL;DR

A CPU emulation framework that lets software pretend to be an ARM, x86, MIPS, or other processor, so security researchers can safely run and inspect machine code without real hardware.

Mindmap

mindmap
  root((repo))
    What it does
      CPU emulation
      Instruction tracing
      Memory hooks
    Supported CPUs
      ARM and ARM64
      x86 and x64
      MIPS RISC-V SPARC
    Use cases
      Malware analysis
      Firmware inspection
      Security research
    Bindings
      Python
      Go Rust Java Ruby

Code map

Detail Auto

An interactive map of this repo's files and how they connect — its source is parsed live in your browser. Click Visualize to build it.

filefunction / class

Why would anyone build with this?

REASON 1

Safely run and analyze a suspicious binary or firmware snippet without booting real hardware or risking your own machine.

REASON 2

Attach callbacks to specific memory addresses in an unknown binary to trace exactly what it does at each step.

REASON 3

Build a malware analysis tool that can emulate multiple CPU architectures using Python bindings.

REASON 4

Study how an embedded device firmware behaves by emulating the target CPU type on your laptop.

What's in the stack?

CPythonGoRustJavaRuby

How it stacks up

unicorn-engine/unicornnonstriater/learn-algorithmsantirez/kilo
Stars8,9548,9368,902
LanguageCCC
Setup difficultymoderateeasyeasy
Complexity4/52/52/5
Audienceresearcherdeveloperdeveloper

Figures from each repo's GitHub metadata at analysis time.

How do you spin it up?

Difficulty · moderate Time to first run · 30min

Python bindings install via pip, building from C source for other languages requires a C compiler.

GPLv2, free to use and modify, but if you distribute software that includes this code you must release your source code under the same license.

Wtf does this do

Unicorn is a CPU emulation framework, meaning it lets software pretend to be a processor and execute code written for a different type of chip. It is used primarily by security researchers and reverse engineers who need to run or inspect small pieces of machine code in a controlled environment without booting an actual device or operating system. The framework supports a wide range of processor types, including ARM, ARM64, x86 (in 16, 32, and 64-bit modes), MIPS, PowerPC, RISC-V, SPARC, and several others. This makes it useful when analyzing firmware or binary files that target hardware you do not physically own. It is built on top of QEMU, an established open-source machine emulator, but focuses specifically on CPU-level emulation rather than full system emulation. Unicorn is written in C and provides bindings for a long list of other languages, including Python, Go, Rust, Java, Ruby, and many more, so it can be called from whatever language a researcher or developer prefers. It runs on Windows, Linux, macOS, and several other operating systems. The project uses just-in-time compilation internally to keep execution fast. One notable feature is fine-grained instrumentation: you can attach callbacks to specific memory addresses or instruction types, which lets you observe exactly what a piece of code does at each step. This is a common need when analyzing malware or studying how unknown binaries behave. The project is distributed under the GPLv2 license and is actively looking for contributors. Additional documentation for compiling and using the library lives in the docs folder rather than the main README.

Yoink these prompts

Prompt 1
Show me a Python example using the Unicorn engine that emulates a small x86-64 shellcode snippet, reads the register values after execution, and prints what changed.
Prompt 2
How do I use Unicorn to set a memory hook that fires every time a specific address is read or written during emulation? Show a Python example.
Prompt 3
I have an ARM firmware binary I want to analyze. Walk me through loading it into Unicorn, mapping the correct memory regions, and running a function from a known offset.
Prompt 4
What is the difference between Unicorn and QEMU for emulating firmware? When should I choose Unicorn over running a full QEMU system emulation?

Frequently asked questions

wtf is unicorn?

A CPU emulation framework that lets software pretend to be an ARM, x86, MIPS, or other processor, so security researchers can safely run and inspect machine code without real hardware.

What language is unicorn written in?

Mainly C. The stack also includes C, Python, Go.

What license does unicorn use?

GPLv2, free to use and modify, but if you distribute software that includes this code you must release your source code under the same license.

How hard is unicorn to set up?

Setup difficulty is rated moderate, with roughly 30min to a first successful run.

Who is unicorn for?

Mainly researcher.

View the repo → Decode another repo

This repo across BitVibe Labs

Don't trust strangers blindly. Verify against the repo.