Files
proxmark3/doc/md/Installation_Instructions/Linux-Installation-Instructions.md
T
iceman1001andClaude Opus 5 730fad4c16 Add configure_environment.sh and make configure
A first-run check for a freshly cloned repo, so a new user finds out what is
missing before a build fails halfway through.

Checks the host toolchain (GNU make, gcc/g++, pkg-config, git, gcc >= 8 for
Qt6), the arm-none-eabi toolchain plus a linkable ARM C library, the required
client libraries (readline, bz2, lz4, libcrypto) and the optional ones, the
bundled-fallback ones, a Python venv with tools/requirements.txt, and on Linux
the dialout/uucp membership, the udev blacklist rule, ModemManager and the
rights on /dev/ttyACM*. Also the tracked .dummy files that hold the firmware
object directories in git, since nothing recreates those.

Detection is by probe, not by querying the package manager: pkg-config where a
.pc file exists, otherwise a real compile-and-link of the header with its -l
flag. Python requirements are compared offline through importlib.metadata.

The device side is covered too: it resolves PLATFORM and PLATFORM_EXTRAS the
way make does, rejects unknown platforms and the combinations Makefile.hal
errors on later (BWM off PM5, BTADDON on PM5, ...), and when there is no
Makefile.platform at all it lists the platforms and offers to write one for the
device the user picks, rather than silently building an RDV4 image.

It changes nothing by default. It asks before creating a venv and before
writing a Makefile.platform, and only --install touches the package manager.
Missing items are mapped to package names for apt, pacman, dnf, zypper, brew
and port and printed as one paste-ready line; NixOS is pointed at
tools/shell.nix.

make configure runs it. The script stays directly callable because make stops
on an invalid PLATFORM before it could run any target.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-11-14 09:55:17 +07:00

14 KiB

Linux Installation Instructions

Table of Contents

External resources

^Top

You might want to follow one of these external resources to get an overview, but please still read carefully this page as some instructions may have evolved.

Linux Installation Video Screenshot

Install the required dependencies

^Top

On Debian / Ubuntu / Kali / ParrotOS / Raspbian / DragonOS

^Top

First what we want to do is get an update for the system. If you need to apply updates do this before installing the Proxmark3 software.
An system upgrade was carried out prior to following these instructions.

Update the packages list

sudo apt-get update
sudo apt-get upgrade -y
sudo apt-get auto-remove -y

Install the requirements

sudo apt-get install --no-install-recommends git ca-certificates build-essential pkg-config \
libreadline-dev gcc-arm-none-eabi libnewlib-dev qt6-base-dev \
libbz2-dev liblz4-dev zlib1g-dev libbluetooth-dev libpython3-dev libssl-dev libgd-dev

On recent distros such as Debian Forky, you may have a conflict between gcc-arm-none-eabi and libnewlib-dev. In this case, ignore libnewlib-dev in favor of picolibc-arm-none-eabi:

sudo apt-get install --no-install-recommends git ca-certificates build-essential pkg-config \
libreadline-dev gcc-arm-none-eabi picolibc-arm-none-eabi qt6-base-dev \
libbz2-dev liblz4-dev zlib1g-dev libbluetooth-dev libpython3-dev libssl-dev libgd-dev

If you want to compile crack5opencl, you will also need opencl-dev or, on newer distros such as Debian Forky, ocl-icd-opencl-dev.

If you don't need...

👉 If you don't need the native Bluetooth support in the client,
you can skip the installation of libbluetooth-dev.

👉 If you don't need the graphical components of the Proxmark3 client (such as in hw tune),
you can skip the installation of qt6-base-dev.

👉 If you don't need support for Python3 scripts in the Proxmark3 client,
you can skip the installation of libpython3-dev.

👉 If you don't need support for decompressing compressed Google Smart Tap payloads in the Proxmark3 client, you can skip the installation of zlib1g-dev.

👉 If you don't need support for NFC ePaper devices,
you can skip the installation of libgd-dev.

Failed to load module...

⚠️ If you get some (non blocking) error at runtime such as Gtk-Message: Failed to load module "canberra-gtk-module"
you may have to install libcanberra-gtk-module.

On ArchLinux

^Top

sudo pacman -Syu git base-devel readline bzip2 lz4 zlib arm-none-eabi-gcc \
arm-none-eabi-newlib qt6-base bluez python gd --needed

If you want to compile crack5opencl, you will also need ocl-icd.

If you don't need...

👉 If you don't need the native Bluetooth support in the client,
you can skip the installation of bluez.

👉 If you don't need the graphical components of the Proxmark3 client (such as in hw tune),
you can skip the installation of qt6-base.

👉 If you don't need support for Python3 scripts in the Proxmark3 client,
you can skip the installation of python.

👉 If you don't need support for decompressing compressed Google Smart Tap payloads in the Proxmark3 client, you can skip the installation of zlib.

👉 If you don't need support for NFC ePaper devices,
you can skip the installation of gd.

On Fedora

^Top

sudo dnf install git make gcc gcc-c++ arm-none-eabi-gcc-cs arm-none-eabi-newlib \
readline-devel bzip2-devel lz4-devel zlib-ng-compat-devel qt6-qtbase-devel bluez-libs-devel \
python3-devel libatomic openssl-devel gd-devel

If you want to compile crack5opencl, you will also need mesa-libOpenCL and ocl-icd-devel.

If you don't need...

👉 If you don't need the native Bluetooth support in the client,
you can skip the installation of bluez-libs-devel.

👉 If you don't need the graphical components of the Proxmark3 client (such as in hw tune),
you can skip the installation of qt6-qtbase-devel.

👉 If you don't need support for Python3 scripts in the Proxmark3 client,
you can skip the installation of python3-devel.

👉 If you don't need support for decompressing compressed Google Smart Tap payloads in the Proxmark3 client, you can skip the installation of zlib-ng-compat-devel.

👉 If you don't need support for NFC ePaper devices,
you can skip the installation of gd-devel.

On openSUSE Leap 15.6

^Top

sudo zypper install git patterns-devel-base-devel_basis gcc-c++ \
readline-devel libbz2-devel liblz4-devel zlib-devel \
python3-devel libqt5-qtbase-devel libopenssl-devel gd-devel
sudo zypper addrepo https://download.opensuse.org/repositories/home:wkazubski/15.6/home:wkazubski.repo && \
sudo zypper --gpg-auto-import-keys refresh && \
sudo zypper install cross-arm-none-eabi-gcc15 cross-arm-none-eabi-newlib

Note that Bluez is not available on openSUSE Leap so the native Bluetooth support won't be available in the client.

Note that the instructions above are for an usage with Qt5. In case of conflict with the presence of development files of Qt6, you can force Qt5 with make SKIPQT6=1.

It is possible to compile the proxmark3 client with Qt6 but with some caveats because the default compiler is GCC 7 and Qt6 requires at least GCC 8:

  • install gcc15 gcc15-c++ instead of gcc-c++
  • install qt6-core-devel qt6-widgets-devel instead of libqt5-qtbase-devel
  • set default compiler to GCC 15 instead of GCC 7
sudo update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-15 100 && \
sudo update-alternatives --install /usr/bin/g++ g++ /usr/bin/g++-15 100 && \
sudo update-alternatives --install /usr/bin/cc cc /usr/bin/gcc-15 100 && \
sudo update-alternatives --install /usr/bin/c++ c++ /usr/bin/g++-15 100

On openSUSE Tumbleweed

^Top

sudo zypper install git patterns-devel-base-devel_basis gcc-c++ \
readline-devel libbz2-devel liblz4-devel zlib-devel bluez-devel \
python3-devel qt6-core-devel qt6-widgets-devel libopenssl-devel gd-devel \
cross-arm-none-gcc12 cross-arm-none-newlib-devel

If you want to compile crack5opencl, you will also need ocl-icd-devel

If you don't need...

👉 If you don't need the graphical components of the Proxmark3 client (such as in hw tune),
you can skip the installation of qt6-core-devel qt6-widgets-devel.

👉 If you don't need support for Python3 scripts in the Proxmark3 client,
you can skip the installation of python3-devel.

👉 If you don't need support for decompressing compressed Google Smart Tap payloads in the Proxmark3 client, you can skip the installation of zlib-devel.

👉 If you don't need support for NFC ePaper devices,
you can skip the installation of gd-devel.

On NixOS

^Top

While in the cloned proxmark repo, run

nix-shell tools/shell.nix

This will bring in all required packages to build the client and firmware with all available features.

Please note, the shell does not change device permissions, so your user must be a part of the dialout group. see here for information on adding your user to that group.

If you don't need...

👉 If you don't need the graphical components of the Proxmark3 client (such as in hw tune),
you can comment out qt6Packages.qtbase and qt6Packages.wrapQtAppsHook in shell.nix.

👉 If you don't need support for Python3 scripts in the Proxmark3 client,
you can comment out python3 in shell.nix.

👉 If you don't need support for decompressing compressed Google Smart Tap payloads in the Proxmark3 client, you can comment out zlib in shell.nix.

👉 If you don't need support for NFC ePaper devices,
you can comment out gd in shell.nix.

Clone the repository

^Top

git clone https://github.com/RfidResearchGroup/proxmark3.git
cd proxmark3

Check your build environment

^Top

Before the first build, let the repo check itself over:

./configure_environment.sh

It reports, one line per check, whether this machine has what the project needs:

  • GNU make, gcc / g++, pkg-config, git, and a gcc new enough for Qt6
  • the arm-none-eabi toolchain and a linkable ARM C library, needed for the firmware
  • the required client libraries (readline, bz2, lz4, libcrypto) and the optional ones (zlib, bluez, libpython3, Qt, libgd), each labelled with the feature it enables
  • which PLATFORM your Makefile.platform selects, and whether the PLATFORM_EXTRAS tokens are valid for it
  • a Python venv and the packages from tools/requirements.txt
  • membership of the dialout (or uucp) group, the udev blacklist rule, whether ModemManager is running, and the access rights on /dev/ttyACM0
  • the tracked .dummy files that hold the firmware object directories in git

Nothing is installed and nothing is changed, apart from the two questions below. The last lines tell you what, if anything, is still missing, as one ready-to-paste install command for your distribution. Exit status is 0 when the build can proceed.

make configure runs the same thing. Call the script directly when make itself refuses to start, for instance after a typo in PLATFORM, since make stops on that before it could run any target.

Tell it which Proxmark you have

^Top

Without a Makefile.platform every build targets a Proxmark3 RDV4, and that image does not work on another board. When the file is absent the script lists the platforms and offers to write one for your device:

[ warn ] no Makefile.platform, every build will be for PLATFORM=PM3RDV4
         flashing an RDV4 image to another board gives a non-working device
         PM3RDV4      Proxmark3 RDV4                                 (the default)
         PM3GENERIC   Proxmark3 RDV1, RDV2, Easy, rysccorps, clones
         PM3ICOPYX    iCopy-X and Proxmark3 Max, with PLATFORM_EXTRAS=FLASH
         PM3ULTIMATE  Proxmark3 Ultimate (XC2S50)
         PM5          Proxmark5 Iceman Edition (Artery AT32F435/437)

         Which device do you have?
           1) Proxmark3 RDV4
           2) Proxmark3 RDV4 with the Blue Shark BT add-on
           3) Proxmark3 RDV1 / RDV2 / Easy / generic clone
           4) Proxmark5 Iceman Edition
           5) Proxmark5 with the Battery Wireless Mod
           6) iCopy-X or Proxmark3 Max
           7) Proxmark3 Ultimate
           0) skip, I will write Makefile.platform myself

Answer 0 and copy Makefile.platform.sample yourself if you want the standalone mode, the 256KB options or anything else it does not ask about. An existing Makefile.platform is never overwritten, only checked.

If you already have one, the script confirms what it resolves to and catches the combinations the firmware build rejects later on, such as PLATFORM_EXTRAS=BWM on anything other than PLATFORM=PM5.

Let it install what is missing

^Top

./configure_environment.sh --install

This asks before each step, then installs the missing system packages with apt-get / pacman / dnf / zypper, creates the Python venv and installs tools/requirements.txt into it. Add -y to skip the questions, --extras to also consider the optional requirement files under fpga/, tools/ePassport/ and tools/btaddon/, and --help for the rest.

On NixOS, use nix-shell tools/shell.nix instead; the script says so.

Check ModemManager

^Top

⚠️ Very important ⚠️

^Top

make sure ModemManager will not interfere, otherwise it could brick your Proxmark3! Read carefully this page about ModemManager and follow its instructions.

Check connection

^Top

Check the proxmark is being picked up by your computer. Plug it in, then:

sudo dmesg | grep -i usb

It should show up as a CDC device:

usb 2-1.2: Product: PM3
usb 2-1.2: Manufacturer: proxmark.org
cdc_acm 2-1.2:1.0: ttyACM0: USB ACM device

And a new /dev/ttyACM0 should have appeared.

Get permissions to use /dev/ttyACM0

^Top

Add current user to the proper groups to get permission to use /dev/ttyACM0.

This step can be done from the Iceman Proxmark3 repo with:

make accessrights

Then, you need to logout and login in again for your new group membership to be fully effective.

To test you have the proper read & write rights, plug the Proxmark3 and execute:

[ -r /dev/ttyACM0 ] && [ -w /dev/ttyACM0 ] && echo ok

It must return ok. Otherwise this means you've got a permission problem to fix.

Compile and use the project

^Top

Now you're ready to follow the compilation instructions.