1Before You Start
2================
3
4Binwalk supports Python 2.7 - 3.x. Although most systems have Python2.7 set as their default Python interpreter, binwalk does run faster in Python3. Installation procedures for both are provided below.
5
6Installation
7============
8
9Installation follows the typical Python installation procedure:
10
11```bash
12# Python2.7
13$ sudo python setup.py install
14```
15
16```bash
17# Python3.x
18$ sudo python3 setup.py install
19```
20
21**NOTE**: Older versions of binwalk (e.g., v1.0) are not compatible with the latest version of binwalk. It is strongly recommended that you uninstall any existing binwalk installations before installing the latest version in order to avoid API conflicts.
22
23Dependencies
24============
25
26Besides a Python interpreter, there are no installation dependencies for binwalk. All dependencies are optional run-time dependencies, and unless otherwise specified, are available from most Linux package managers.
27
28Although all binwalk run-time dependencies are optional, the `python-lzma` module is highly recommended for improving the reliability of signature scans. This module is included by default in Python3, but must be installed separately for Python2.7:
29
30```bash
31$ sudo apt-get install python-lzma
32```
33
34Binwalk uses [pyqtgraph](http://www.pyqtgraph.org) to generate graphs and visualizations, which requires the following:
35
36```bash
37# Python2.7
38$ sudo apt-get install libqt4-opengl python-opengl python-qt4 python-qt4-gl python-numpy python-scipy python-pip
39$ sudo pip install pyqtgraph
40```
41
42```bash
43# Python3.x
44$ sudo apt-get install libqt4-opengl python3-opengl python3-pyqt4 python3-pyqt4.qtopengl python3-numpy python3-scipy python3-pip
45$ sudo pip3 install pyqtgraph
46```
47
48Binwalk's `--disasm` option requires the [Capstone](http://www.capstone-engine.org/) disassembly framework and its corresponding Python bindings:
49
50```bash
51# Python2.7
52$ sudo apt-get install python-pip
53$ sudo pip install capstone
54```
55
56```bash
57# Python3.x
58$ sudo apt-get install python3-pip
59$ sudo pip3 install capstone
60```
61
62Binwalk relies on multiple external utilties in order to automatically extract/decompress files and data:
63
64```bash
65# Install standard extraction utilities
66$ sudo apt-get install mtd-utils gzip bzip2 tar arj lhasa p7zip p7zip-full cabextract cramfsprogs cramfsswap squashfs-tools
67```
68
69```bash
70# Install sasquatch to extract non-standard SquashFS images
71$ sudo apt-get install zlib1g-dev liblzma-dev liblzo2-dev
72$ git clone https://github.com/devttys0/sasquatch
73$ (cd sasquatch && make && sudo make install)
74```
75
76```bash
77# Install jefferson to extract JFFS2 file systems
78$ sudo pip install cstruct
79$ git clone https://github.com/sviehb/jefferson
80$ (cd jefferson && sudo python setup.py install)
81```
82
83```bash
84# Install ubi_reader to extract UBIFS file systems
85$ sudo apt-get install liblzo2-dev python-lzo
86$ git clone https://github.com/jrspruitt/ubi_reader
87$ (cd ubi_reader && sudo python setup.py install)
88```
89
90```bash
91# Install unstuff (closed source) to extract StuffIt archive files
92$ wget -O - http://my.smithmicro.com/downloads/files/stuffit520.611linux-i386.tar.gz | tar -zxv
93$ sudo cp bin/unstuff /usr/local/bin/
94```
95
96Note that for Debian/Ubuntu users, all of the above dependencies can be installed automatically using the included `deps.sh` script:
97
98```bash
99$ sudo ./deps.sh
100```
101
102Installing the IDA Plugin
103=========================
104
105If IDA is installed on your system, you may optionally install the binwalk IDA plugin:
106
107```bash
108$ python setup.py idainstall --idadir=/home/user/ida
109```
110
111Likewise, the binwalk IDA plugin can be uninstalled:
112
113```bash
114$ python setup.py idauninstall --idadir=/home/user/ida
115```
116
117
118Uninstalling Binwalk
119====================
120
121If binwalk has been installed to a standard system location (e.g., via `setup.py install`), it can be removed by running:
122
123```bash
124# Python2.7
125$ sudo python setup.py uninstall
126```
127
128```bash
129# Python3
130$ sudo python3 setup.py uninstall
131```
132
133Note that this does _not_ remove any of the manually installed dependencies.
134
135