Skip to content

Installation

Jump to bottom
xwings edited this page Jul 6, 2025 · 3 revisions

Installation

Qiling Framework is written in Python and supports multiple platforms and architectures. This guide covers various installation methods.

Prerequisites

Python 3

Qiling requires Python 3.8 or newer. For development, Python 3.11 is recommended as Qiling will transition to this version.

Installing Python 3

Windows:

  • Use Microsoft Store to install Python 3.8 or newer
  • Alternatively, download from python.org

Linux (Ubuntu/Debian):

sudo apt update
sudo apt install python3 python3-pip python3-venv

Linux (Red Hat/CentOS/Fedora):

sudo dnf install python3 python3-pip python3-venv
# or for older versions
sudo yum install python3 python3-pip python3-venv

macOS:

# Using Homebrew
brew install python3

# Using MacPorts
sudo port install python310

Python Virtual Environment (Recommended)

Using a virtual environment keeps Qiling's dependencies isolated from other Python projects.

Creating a Virtual Environment

# Create virtual environment
python3 -m venv qlenv

# Activate on Linux/macOS
source qlenv/bin/activate

# Activate on Windows
qlenv\Scripts\activate

Installation Methods

Method 1: Install via pip (Recommended)

The simplest installation method:

Stable Release:

pip install qiling

Development Branch (Latest Features):

pip install --user https://github.com/qilingframework/qiling/archive/dev.zip

Method 2: Install from Source (For Developers)

Recommended for users who want to:

  • Develop tools on top of Qiling
  • Stay current with latest fixes
  • Contribute to the project
git clone -b dev https://github.com/qilingframework/qiling.git
cd qiling
git submodule update --init --recursive
pip install .

For Development:

pip install -e .  # Editable install

Method 3: Docker Installation

For minimal system impact and easy cleanup:

Pull the Image:

docker pull qilingframework/qiling:latest

Run Container:

docker run -it qilingframework/qiling:latest

With Port Publishing (for network services):

docker run -it -p 8080:8080 qilingframework/qiling:latest

With Volume Mounting:

docker run -it -v /path/to/your/files:/qiling/work qilingframework/qiling:latest

Platform-Specific Setup

Windows - DLL Collection

Due to legal reasons, Qiling cannot bundle Windows DLL files. If you have a legal Windows copy, collect required DLLs:

  1. Run as Administrator:
examples\scripts\dllscollector.bat
  1. For Docker users, bind-mount DLLs:
docker run -dt --name qiling \
  -v /analysis/win/rootfs/x86_windows:/qiling/examples/rootfs/x86_windows \
  -v /analysis/win/rootfs/x8664_windows:/qiling/examples/rootfs/x8664_windows \
  qilingframework/qiling:latest

macOS - Keystone Engine Fix

On macOS 10.14+, keystone-engine may fail to compile. Install from source:

git clone https://github.com/keystone-engine/keystone
cd keystone
mkdir build
cd build
../make-share.sh
cd ../bindings/python
sudo make install

Then install Qiling:

pip install qiling

Linux - Additional Dependencies

Some distributions may require additional packages:

Ubuntu/Debian:

sudo apt install build-essential cmake

Red Hat/CentOS/Fedora:

sudo dnf install gcc gcc-c++ cmake make

Optional Dependencies

AFL++ Support (Linux only)

For fuzzing capabilities:

pip install qiling[afl]

Radare2 Integration

For advanced analysis:

pip install qiling[r2]

All Optional Dependencies

pip install qiling[all]

Verification

Test your installation:

from qiling import Qiling
from qiling.const import QL_ARCH, QL_OS

# Test basic import
print("Qiling installed successfully!")

# Test shellcode emulation
shellcode = b'\x48\x31\xc0'  # xor rax, rax
ql = Qiling(code=shellcode, archtype=QL_ARCH.X8664, ostype=QL_OS.LINUX)
print("Basic functionality works!")

Or use the command line tool:

qltool --help

Troubleshooting

Common Issues

Import Error: No module named 'qiling'

  • Ensure you're in the correct virtual environment
  • Verify installation with pip list | grep qiling

Unicorn Engine Installation Issues

pip install --upgrade unicorn

Permission Errors

  • Use virtual environment instead of system-wide installation
  • On Linux/macOS, avoid sudo pip install

Windows: Missing Visual C++ Build Tools

  • Install Microsoft C++ Build Tools
  • Or use pre-compiled packages: pip install --only-binary=all qiling

Getting Help

Next Steps

After installation, check out:

Clone this wiki locally