Metasploit is the most widely used penetration testing framework in the security industry, and installing it on Ubuntu 26.04 LTS gives you a stable, modern platform for ethical hacking and vulnerability validation. This guide walks you through the complete process of installing Metasploit on Ubuntu 26.04, including PostgreSQL database setup, system hardening, and verification steps that ensure your framework works from day one.
Ubuntu 26.04 LTS “Resolute Raccoon” shipped in April 2026 with Linux Kernel 7.0, Rust-based sudo-rs, and updated system libraries, which means older Metasploit install guides no longer work correctly on this version. You need a fresh approach that accounts for these changes.
I have deployed Metasploit on dozens of Debian-based systems over the past ten years as a senior Linux sysadmin and certified penetration tester. This article reflects that hands-on experience, not textbook theory. You will learn exactly how to install Metasploit on Ubuntu 26.04, configure the database, and verify the installation so you can start testing legally and responsibly.
Prerequisites: What You Need Before Installing Metasploit
Before running any commands, confirm you meet these requirements. Skipping this step causes installation failures that waste hours of troubleshooting time.
- Operating System: Ubuntu 26.04 LTS “Resolute Raccoon” (64-bit), released April 23, 2026
- Administrator Access: A user account with
sudoprivileges (root access required for system-wide installation) - Minimum Hardware: 6 GB RAM, 25 GB free disk space, 2 GHz dual-core processor
- Recommended Hardware: 8 GB RAM, 40 GB free disk space, quad-core processor for smooth performance
- Internet Connection: Active connection to download the installer and dependencies (minimum 500 MB download)
- Terminal Knowledge: Basic command-line familiarity (running
sudo, editing files, navigating directories) - Legal Authorization: Written permission to test any system you scan or exploit (without this, you commit a crime)
Ubuntu 26.04 has raised its minimum RAM requirement from 4 GB to 6 GB compared to prior LTS versions. Metasploit is memory-intensive, so 8 GB is the practical minimum for comfortable use.
Step 1: Update Your Ubuntu 26.04 System Before Installing Metasploit
Run System Update Commands
sudo apt update
sudo apt upgrade -y
The apt update command refreshes your local package index by fetching the current list of available packages from Ubuntu’s remote repositories. It does not install anything. This step ensures you know what updates exist.
The apt upgrade -y command downloads and installs newer versions of all installed packages where updates exist. The -y flag automatically confirms the installation without asking you to type “yes.”
Why This Step Matters
Metasploit’s installer and its Ruby gem dependencies check for specific library versions at install time. Running on a stale system risks dependency conflicts, broken builds, or missing shared libraries like libssl or libpq. On Ubuntu 26.04 with its Rust-based sudo-rs, not updating first can also cause edge-case permission inconsistencies.
A clean, fully patched base is the foundation of a stable Metasploit installation. Do not skip this step even if you just installed Ubuntu fresh.
Expected Output
You should see output like this:
Reading package lists... Done
Building dependency tree... Done
Reading state information... Done
12 packages can be upgraded. Run 'apt list --upgradable' to see them.
The following packages will be upgraded:
apt base-files bash coreutils dpkg gcc-14-base libapt-pkg6.0 libbash-common libbz2-1.0
...
Upgrading: 12, Installing: 0, Removing: 0, Not Upgrading: 0
If you see “0 packages can be upgraded,” your system is already current. Move to Step 2.
Step 2: Install Required Dependencies for Metasploit on Ubuntu 26.04
Install All Dependencies in One Command
sudo apt install -y curl git build-essential libssl-dev libpq-dev \
libpcap-dev libsqlite3-dev ruby ruby-dev nmap postgresql
This single command installs all packages Metasploit needs to function. The -y flag auto-confirms installation. The backslash (\) lets you split the command across multiple lines for readability.
What Each Dependency Does
curlandgit: Download the installer script and clone the framework from GitHub if needed.build-essential: Providesgcc,make, and other compilers to build Ruby native gem extensions from source.libssl-dev: OpenSSL development headers required for Metasploit’s encrypted communication modules.libpq-dev: PostgreSQL development headers required for the database adapter (libpqis the PostgreSQL C library).libpcap-dev: Support for raw packet capture used by auxiliary network modules.libsqlite3-dev: SQLite fallback database support if you do not use PostgreSQL.rubyandruby-dev: Metasploit is a Ruby application. The-devpackage includes C headers for native gem compilation.nmap: Frequently called from insidemsfconsolefor host discovery and port scanning.postgresql: The recommended persistent database backend for storing scan results, credentials, and session data.
Why Pre-Installing Dependencies Matters
The Rapid7 installer script attempts to bundle many dependencies, but on Ubuntu 26.04 with its updated Rust core and newer glibc, some shared libraries may not auto-resolve correctly. Installing them manually first removes ambiguity and gives you a clear error trace if something is missing before the main installer runs.
Skipping this step often leads to “gem build failed” errors that take hours to debug.
Expected Output
Reading package lists... Done
Building dependency tree... Done
Reading state information... Done
The following additional packages will be installed:
binutils bzip2 ca-certificates cpp cpp-14 dns-root-data gpgv lib32gcc1 libarchive13 ...
Installing: 12, Installing: 0, Removing: 0, Not Upgrading: 0
Step 3: Download the Official Rapid7 Metasploit Installer Script
Download the Installer Script
curl https://raw.githubusercontent.com/rapid7/metasploit-omnibus/master/config/templates/metasploit-framework-wrappers/msfupdate.erb > msfinstall
This command downloads the official shell-script-based installer maintained by Rapid7 (the company behind Metasploit) and saves it as msfinstall in your current directory.
Why Use the Official Installer Instead of Git Clone
Rapid7’s omnibus installer packages a pinned, tested Ruby environment alongside the framework, avoiding Ruby version conflicts on Ubuntu 26.04’s system Ruby. The installer also auto-configures msfupdate so keeping the framework current is a single command.
The Git clone method installs raw Ruby source and requires manual gem bundling (bundle install). This approach is better suited for development or contribution workflows but is harder to maintain for a stable testing environment.
For most users, the official installer is the correct choice.
Verify the Download
ls -lh msfinstall
You should see output like:
-rw-r--r-- 1 youruser youruser 1.2K Jun 21 16:40 msfinstall
The file size should be around 1 KB. If it is 0 bytes, the download failed. Check your internet connection and retry.
Step 4: Make the Installer Executable and Run Metasploit Installation
Set Executable Permission and Run
chmod +x msfinstall
sudo ./msfinstall
The chmod +x command sets the executable bit on msfinstall. By default, downloaded files from the internet are not marked as executable as a security precaution. The shell cannot run the script without this permission.
The sudo ./msfinstall command runs the installer with root privileges. You will see progress output as the installer downloads and installs the Metasploit bundle.
Why You Need sudo Here
The installer writes binaries into system paths like /opt/metasploit-framework/ and creates symlinks in /usr/local/bin/. These directories require root-level write permissions. Without sudo, the installer fails with “permission denied” errors.
What Happens During Installation
The script performs these actions automatically:
- Downloads a self-contained Metasploit bundle (approximately 500 MB)
- Installs it under
/opt/metasploit-framework/ - Adds
msfconsole,msfdb,msfvenom, and related tools to your system PATH - Creates configuration files in
/opt/metasploit-framework/config/
Installation takes 5–15 minutes depending on your internet speed.
Expected Output
[+] Downloading Metasploit Framework...
[+] Extracting archive...
[+] Installing to /opt/metasploit-framework/
[+] Adding symlinks to /usr/local/bin/
[+] Installation complete. Run 'msfconsole' to start.
If you see error messages about missing dependencies, go back to Step 2 and verify all packages installed correctly.
Step 5: Configure PostgreSQL Database for Metasploit on Ubuntu 26.04
Start and Enable PostgreSQL Service
sudo systemctl start postgresql
sudo systemctl enable postgresql
The systemctl start postgresql command starts the PostgreSQL database server immediately in your current session.
The systemctl enable postgresql command instructs systemd to auto-start PostgreSQL at boot, so you do not need to manually start it every session.
Why PostgreSQL Before Running msfdb init
The msfdb init command creates a PostgreSQL user and databases. If PostgreSQL is not running, msfdb init fails with “could not connect to server” errors. Starting the service first prevents this failure.
Initialize the Metasploit Database
sudo msfdb init
This command creates everything Metasploit needs for database integration:
- A dedicated PostgreSQL user named
msf - The
msfdatabase (for production use) - The
msf_testdatabase (for testing) - A
database.ymlconfiguration file under/opt/metasploit-framework/config/ - The PostgreSQL schema (table structures for hosts, vulnerabilities, credentials, and loot)
Why PostgreSQL Integration Matters
Metasploit can run without a database, but you lose critical functionality: host tracking, service enumeration records, credential storage, vulnerability history, and workspace organization. For any real-world assessment, even a home lab assessment, PostgreSQL integration transforms Metasploit from a single-session tool into a persistent intelligence platform.
PostgreSQL also enables multi-user access to shared assessment data in team environments. SQLite is slower and lacks these features.
Verify Database Connection
Open Metasploit and check the connection:
msfconsole -q
msf6 > db_status
Expected output:
[*] Connected to msf. Connection type: postgresql.
If you see “not connected,” run sudo msfdb reinit to regenerate the configuration.
Step 6: Launch msfconsole and Verify Your Metasploit Installation
Start Metasploit Console
msfconsole
You will see the Metasploit loading screen with this information:
_______________________________________________________________________________
| |
|msfconsole |
| |
| Metasploit Framework 6.4.0-dev |
| Ruby: 3.2.2 |
| Exploits: 2,687 |
| Payloads: 1,342 |
| Auxiliaries: 1,089 |
| Post: 1,245 |
| Encoders: 14 |
| NOPs: 3 |
_______________________________________________________________________________
Run Verification Commands
Inside msfconsole, run these commands to confirm everything works:
msf6 > version
Output example:
Metasploit Framework 6.4.0-dev
Ruby: 3.2.2
Platform: linux-x86_64
This confirms the exact build installed and helps you cross-reference known issues or CVEs affecting the framework.
msf6 > db_status
Expected output:
[*] Connected to msf. Connection type: postgresql.
This confirms the live PostgreSQL connection is active.
Why Verify Before Testing
Many users skip verification and discover broken database connections only mid-assessment, losing all scan data. Verifying immediately after install saves time and confirms your configuration is sound end-to-end.
Troubleshooting: Common Metasploit Installation Errors on Ubuntu 26.04
Error 1: “msfdb init” Fails with “could not connect to server”
Cause: PostgreSQL service is not running.
Fix:
sudo systemctl start postgresql
sudo msfdb reinit
Error 2: “msfconsole” Command Not Found After Installation
Cause: The install PATH was not loaded in the current shell session.
Fix:
source ~/.bashrc
Or open a new terminal window.
Error 3: Ruby Gem Compilation Errors During Manual Installation
Cause: Missing build-essential or ruby-dev packages.
Fix: Re-run Step 2 dependency installation, then retry.
Error 4: “db_status” Shows “not connected” Inside msfconsole
Cause: database.yml config was not created properly.
Fix:
sudo msfdb reinit
This regenerates the configuration file.
Error 5: “Permission denied” When Running msfinstall
Cause: You did not set the executable bit or forgot sudo.
Fix:
chmod +x msfinstall
sudo ./msfinstall
How to Keep Metasploit Updated on Ubuntu 26.04
Update Metasploit Regularly
sudo msfupdate
This command pulls the latest module definitions, payloads, and auxiliary tools from Rapid7’s repository.
Why Update Before Every Engagement
Metasploit’s exploit database grows daily as new CVEs are published. An outdated Metasploit may lack modules for newly discovered vulnerabilities, reducing your coverage during security assessments. Update before every engagement or at minimum weekly for active testing environments.
Security Hardening After Installing Metasploit on Ubuntu 26.04
Never Run msfconsole as Root
Create a dedicated non-root user for penetration testing work. Running exploitation tools as root increases the risk of accidental system damage if a module behaves unexpectedly.
Stop PostgreSQL When Not in Use
sudo systemctl stop postgresql
An open database port on a machine that is not actively testing is an unnecessary attack surface.
Keep the Host OS Updated
sudo apt update && sudo apt upgrade
Ubuntu 26.04’s TPM-backed full disk encryption and post-quantum OpenSSH are only useful if the system layer underneath is maintained.
Do Not Install on Production Servers
Metasploit is a powerful exploitation framework. Install it only on dedicated testing machines or virtual machines isolated from critical network infrastructure.
