Guide

Why installing Metasploit in Termux fails — and what to do instead

Almost every guide to running the Metasploit Framework on Android tells you to install Termux and run a setup script. Most of them also warn you, in the same breath, that it takes twenty to sixty minutes and that if it fails you should just run it again. That advice is honest about the symptom and silent about the cause. Here is the cause.

What actually breaks

Metasploit is a large Ruby application with native extensions. Installing it by hand on a phone means building those extensions on the phone, and that is where the process falls over. The failures are not random:

Native gems have to compile. Gems like nokogiri, pg, bcrypt_pbkdf and ed25519 ship C that must be built against the local toolchain. On a phone that means installing a compiler, headers and the right library versions first. A single missing header ends the install several minutes in, with an error from deep inside a build log.
Ruby versions drift. Metasploit tracks a Ruby version; Termux ships whatever is current. When those diverge, gems that built yesterday stop building today — which is why a script that worked when the tutorial was written fails when you run it.
The Play Store build of Termux is frozen. Google Play's API-level requirements left that build unable to update its packages. The Termux maintainers recommend the F-Droid or GitHub build instead. A great many "it just doesn't work" reports are this and nothing else.
The database is a separate problem. Metasploit wants PostgreSQL for workspaces, hosts, services and loot. Getting postgres running under Termux, and msfdb pointed at it, is its own sequence of steps that most guides skip — which is why so many people end up with a working msfconsole and no database.
Nothing is pinned. Each step pulls whatever is current, so the install is not reproducible. Two people following the same guide on the same day can get different results, and neither can help the other.

Option 1: fix the manual install

This is worth doing if you want to understand the stack, and it is the right answer if you need a specific Metasploit revision. In order:

Uninstall the Play Store Termux and install the F-Droid or GitHub build. Do this first — it invalidates most other troubleshooting.
pkg update && pkg upgrade, then install the build toolchain (clang, make, pkg-config, binutils) and the headers the gems need (libffi, openssl, libxml2, libxslt, postgresql) before touching Metasploit.
Install ruby, then let bundler build the gems. Expect this to be the slow part; a phone CPU compiling native extensions is genuinely slow, not stuck.
When a gem fails, read the first error in the log, not the last. The last line is bundler giving up; the first is the missing header that caused it.
Set up postgres and run msfdb init separately, afterwards.

Budget an afternoon the first time, and expect to repeat parts of it when Ruby moves.

Option 2: install an environment that is already built

This is what Lupus is. It is worth being precise about the claim, because the internet is full of imprecise ones: Lupus is not a different technology from Termux. It is built on a fork of termux-packages, and on the device it is a proot environment of the same family. The difference is that the compiling and the version-matching happened on build servers, not on your phone.

In practice that means the native gems are cross-compiled and shipped as packages, the Ruby and Metasploit versions are pinned together, and the database is configured before you ever see it. You install the app and get a working msfconsole plus a workspace database, rather than a build log.

On top of that it adds the things a phone actually needs: a graphical interface over msfconsole, Nmap and Nuclei, so you tap through a module's options instead of typing them on a touch keyboard, and a curated arsenal — Impacket, NetExec, Responder, sqlmap, ffuf, httpx, subfinder and more — installed the same way. Raw msfconsole is still there when you want it. See the full tool list.

Which one to pick

Learning how the stack fits together, or need a specific MSF revision: do the manual install. The knowledge transfers.
You want to run an engagement this evening: use something prebuilt. The build is not the interesting part of the work.

Either way, the tooling is for lawful, authorized testing — systems you own or have written permission to test.

Download Lupus Read the setup guide