How to Install Metasploit on Debian 13, 12 and 11

Security labs become easier to repeat when module search, payload generation, database-backed workspaces, and safe target checks all run from one console. To install Metasploit on Debian without replacing Debian’s system Ruby, Python, or PostgreSQL packages, use Rapid7’s official Metasploit Framework APT repository.

Debian 13 (Trixie), Debian 12 (Bookworm), and Debian 11 (Bullseye) can use Rapid7’s nightly APT packages. Debian’s default repositories do not currently provide a metasploit-framework package, and the Snap Store package uses a separate third-party Snap path, so this APT workflow keeps the package source, updates, database setup, and removal under APT.

Metasploit is a dual-use security framework. Use it only on systems you own, operate, or have explicit written permission to assess, and keep lab targets separate from production systems whenever possible.

Install Metasploit Framework on Debian

Choose the Debian Package Source

Rapid7’s APT repository is the package-manager path for Debian systems that need the packaged Metasploit Framework. The other available paths use different packaging models, so keep them separate from this APT workflow.

Package Path	Status on Debian	Use Case
Rapid7 APT repository	Official Metasploit Framework packages for Debian/Ubuntu package managers	Recommended for normal Debian lab systems and repeatable updates
Snap Store package	Separate Snap package maintained outside Rapid7’s APT repository	Only for users who deliberately want Snap packaging and its permission model; set up Snap on Debian as a separate workflow
Source checkout	Development workflow from the Metasploit Framework source tree	Framework development, not the packaged Debian lab install path

Use only one Metasploit package path on the same system. Mixing APT, Snap, and source checkouts can make the active msfconsole command depend on PATH order instead of the package you intend to run.

Update Debian and Install Repository Tools

Refresh enabled APT sources first, then install the small tools needed to fetch HTTPS content and convert Rapid7’s signing key into a local keyring:

sudo apt update
sudo apt install ca-certificates curl gpg

These commands use sudo because package installation and repository files are root-owned. If your account cannot run sudo commands yet, add a user to sudoers on Debian before continuing.

Do not install Debian’s postgresql package for this method. The Rapid7 package includes the PostgreSQL runtime used by the msfdb helper, and the default database setup stores data under your own account instead of using Debian’s system PostgreSQL service.

Add the Rapid7 Signing Key

Import Rapid7’s current Metasploit package-signing key into a dedicated APT keyring. The curl command guide explains the -fsSL option set used for quiet HTTPS downloads that still fail on server errors.

curl -fsSL https://apt.metasploit.com/metasploit-framework.gpg.key | sudo gpg --dearmor --yes -o /usr/share/keyrings/metasploit-framework.gpg

Check the fingerprint from the saved keyring before trusting the new source:

gpg --quiet --show-keys --with-fingerprint /usr/share/keyrings/metasploit-framework.gpg

pub   rsa4096 2015-05-26 [SC] [expires: 2030-01-11]
      97B3 2012 EA11 76F0 5372  7A95 C048 F0B4 9DEE C457
uid                      Release Engineering <r7_re@rapid7.com>

Create the Metasploit APT Source

Rapid7’s Metasploit nightly installer documentation points Debian and Ubuntu users at https://apt.metasploit.com. These commands use the same repository and signing key but write a DEB822 .sources file so the source is easier to inspect and remove. The repository still uses lucid as its suite name, so keep that value exactly as written instead of replacing it with trixie, bookworm, or bullseye.

Rapid7 currently publishes Debian-family packages for amd64, arm64, armhf, and i386. The guarded source block writes the DEB822 file only when the current Debian architecture matches one of those package indexes:

(
  set -e
  arch="$(dpkg --print-architecture)"

  case "$arch" in
    amd64|arm64|armhf|i386)
      printf '%s\n' \
      'Types: deb' \
      'URIs: https://apt.metasploit.com' \
      'Suites: lucid' \
      'Components: main' \
      "Architectures: $arch" \
      'Signed-By: /usr/share/keyrings/metasploit-framework.gpg' | sudo tee /etc/apt/sources.list.d/metasploit-framework.sources > /dev/null
      ;;
    *)
      printf 'Rapid7 does not publish Metasploit APT packages for %s.\n' "$arch" >&2
      exit 1
      ;;
  esac
)

The sudo tee command writes the source file as root. A normal shell redirection would run as your user and fail because /etc/apt/sources.list.d/ is root-owned.

Refresh APT and Install Metasploit

Refresh APT again so Debian reads the Rapid7 source, then confirm that the package candidate comes from apt.metasploit.com before installing it:

sudo apt update
apt-cache policy metasploit-framework

The policy output should list https://apt.metasploit.com under the version table. Rapid7 rebuilds nightly packages frequently, so the exact package version changes over time.

Install the framework package after the source and candidate look correct:

sudo apt install metasploit-framework

Review the APT transaction before confirming. On amd64, expect roughly 400 MB to download and close to 900 MB installed because Rapid7 bundles the framework runtime inside the package.

Verify Metasploit Framework on Debian

Confirm that Debian can find the console launcher and that the package is installed:

command -v msfconsole
dpkg-query -W -f='${db:Status-Abbrev} ${binary:Package}\n' metasploit-framework

Relevant output starts with the launcher path and an installed package state:

/usr/bin/msfconsole
ii  metasploit-framework

Rapid7 registers msfconsole, msfvenom, msfdb, and related tools through Debian’s update-alternatives system. The user-facing commands live under /usr/bin/, while the active executables point into /opt/metasploit-framework/bin/.

Set Up the Metasploit Database on Debian

Metasploit can open without a database, but database-backed workspaces preserve hosts, services, notes, credentials, and imported scan results between sessions. Initialize the per-user database with defaults:

msfdb init --use-defaults

Successful initialization creates the database under ~/.msf4/db and starts the bundled PostgreSQL runtime:

Running the 'init' command for the database:
Creating initial database schema
Database initialization successful

Check the database state from the helper. Some Rapid7 nightly packages can print RubyGems warning lines before the status block; the important result is the database status itself.

msfdb status

Running the 'status' command for the database:
Database started

Verify the database connection from inside msfconsole without staying in the interactive prompt. A first console run may print Metasploit’s initial setup banner before the database status line.

msfconsole -q -x 'db_status; exit -y'

[*] Connected to msf. Connection type: postgresql.

Run First Metasploit Console Checks

Start the console from a terminal when you are ready to work interactively:

msfconsole

Inside the msf6 > prompt, begin with read-only discovery commands. These commands show help, search module metadata, and inspect a module without running it against any target:

help
search type:auxiliary name:scanner
info auxiliary/scanner/ssh/ssh_version
exit -y

Console Command	Use
help	Lists console commands and command categories.
search	Finds modules by type, platform, name, CVE, author, or keyword.
info	Shows module description, options, references, and requirements before any run attempt.
db_status	Confirms whether the console is connected to the Metasploit database.
exit -y	Leaves the console without an extra confirmation prompt.

Understand Modules and Datastore Options

Rapid7’s Metasploit basics documentation covers the console workflow, and its module-options documentation explains datastore values such as set and setg. For a first Debian session, inspect module behavior before setting a target or running anything.

Concept	First-Session Meaning
auxiliary modules	Support modules such as scanners and enumerators. Inspect them with info before any run attempt.
exploit modules	Modules that attempt to use a vulnerability. Run them only against authorized lab targets after reviewing required options.
payload modules	Code paired with an exploit after a successful compromise. Payloads are not needed for install verification.
post modules	Modules used after an authorized session already exists.
Datastore options	set applies a value to the current module; setg creates a global default. Prefer module-level values while learning so settings do not leak into later modules.

If your lab workflow uses scan imports or db_nmap, install Nmap on Debian first. For controlled beginner scans, review Nmap command examples before pointing tools at any network outside your written authorization.

Update Metasploit Framework on Debian

Because this install uses an APT source, update Metasploit through APT. The --only-upgrade option upgrades the package only if it is already installed, so it will not turn an update command into a new install on a system that does not have Metasploit yet.

sudo apt update
sudo apt install --only-upgrade metasploit-framework

Rapid7 also ships an msfupdate helper, but APT keeps the source, version candidate, and cleanup path visible through standard Debian package-manager commands.

Troubleshoot Metasploit Framework on Debian

APT Cannot Verify the Metasploit Repository

A key or Signed-By error usually means the keyring is missing, the source file points to a different key path, or an older setup left a duplicate source behind. Check the active source first:

cat /etc/apt/sources.list.d/metasploit-framework.sources
gpg --quiet --show-keys --with-fingerprint /usr/share/keyrings/metasploit-framework.gpg

If APT still reports a Metasploit key or duplicate-source error, remove legacy filenames used by older setup instructions, then repeat the Rapid7 key and DEB822 source steps:

sudo rm -f /etc/apt/sources.list.d/metasploit-framework.list
sudo rm -f /etc/apt/sources.list.d/metasploit.list
sudo rm -f /usr/share/keyrings/metasploit.gpg
sudo apt update

APT Shows No Metasploit Package Candidate

Default Debian sources do not expose metasploit-framework. If apt-cache policy metasploit-framework prints no candidate or does not list apt.metasploit.com, confirm the Rapid7 source exists and that your architecture is one of the published Debian-family package indexes:

dpkg --print-architecture
cat /etc/apt/sources.list.d/metasploit-framework.sources
sudo apt update
apt-cache policy metasploit-framework

Supported APT architectures are amd64, arm64, armhf, and i386. Other Debian architectures need a different approach, such as a development source checkout maintained outside this package-manager workflow.

Metasploit Shows No Database Connection

Confirm the missing connection with the same non-interactive console check used earlier:

msfconsole -q -x 'db_status; exit -y'

A console without a database connection usually prints this status:

[*] postgresql selected, no connection

Check the per-user database state before changing it:

msfdb status

If the database exists but is stopped, start it and retest the console connection:

msfdb start
msfconsole -q -x 'db_status; exit -y'

If msfdb status reports that no database exists, initialize it, then repeat the console database check:

msfdb init --use-defaults
msfconsole -q -x 'db_status; exit -y'

Ruby Gem Warnings Appear During msfdb Commands

Some Rapid7 nightly packages print bundled Ruby warning lines before normal msfdb output. Run the status check and read the database state after the warning lines. Relevant lines can include the warning first, followed by the actual database status:

msfdb status

WARN: Unresolved or ambiguous specs during Gem::Specification.reset:
      base64 (>= 0.2)
      logger (~> 1.6)
Running the 'status' command for the database:
Database started

Update Metasploit first. If msfdb status still reports Database started and msfconsole connects to PostgreSQL, the warning is coming from the bundled Metasploit runtime rather than a missing Debian package. Avoid running system Ruby cleanup commands against Debian’s Ruby just to silence a warning from the bundled framework.

Remove Metasploit Framework from Debian

Delete the Metasploit Database

The database cleanup removes Metasploit’s local database and configuration under your account. Export or back up anything you still need before confirming the delete prompt.

If you initialized the Metasploit database, delete it before removing the package so the helper can stop the bundled PostgreSQL process cleanly:

msfdb delete

The command asks whether to delete existing data and configurations. Answer yes only when you are ready to remove the local database:

[?] Would you like to delete your existing data and configurations? []:

Purge Metasploit and Remove the APT Source

Purge the package after any database cleanup is complete:

sudo apt purge metasploit-framework

Remove the DEB822 source and legacy filenames used by older Metasploit setup instructions or helper runs. The keyring cleanup leaves a key in place if another APT source still references it:

sudo rm -f /etc/apt/sources.list.d/metasploit-framework.sources
sudo rm -f /etc/apt/sources.list.d/metasploit-framework.list
sudo rm -f /etc/apt/sources.list.d/metasploit.list

for keyring in /usr/share/keyrings/metasploit-framework.gpg /usr/share/keyrings/metasploit.gpg; do
  if find /etc/apt/sources.list /etc/apt/sources.list.d -type f -print0 2>/dev/null | xargs -0r grep -Fqs -- "$keyring"; then
    printf 'Metasploit keyring still referenced by another APT source: %s\n' "$keyring"
  else
    sudo rm -f "$keyring"
  fi
done

sudo apt update

Refresh Bash’s command cache if you are checking removal in the same terminal session, then confirm the launcher, package record, and repository candidate are gone:

hash -r
command -v msfconsole || echo "msfconsole removed"
dpkg-query -W -f='${db:Status-Abbrev} ${binary:Package}\n' metasploit-framework 2>/dev/null || echo "metasploit-framework package record removed"
apt-cache policy metasploit-framework

After the source cleanup, the launcher check should report msfconsole removed, and dpkg-query should report that the package record was removed. apt-cache policy metasploit-framework may print no package block at all; if it still shows a candidate from apt.metasploit.com, another Metasploit source file remains enabled.

Remove Remaining Metasploit User Data

Removing ~/.msf4 deletes Metasploit profile data for the current Linux account, including local configuration, logs, and any remaining workspace files.

Check whether the profile directory still exists:

find "$HOME" -maxdepth 1 -name ".msf4" -print

If the command prints /home/username/.msf4 for your account and you no longer need that profile data, remove it:

rm -rf "$HOME/.msf4"

Conclusion

Metasploit Framework is installed on Debian through Rapid7’s APT repository, with the console, database helper, update path, and cleanup steps separated cleanly. For lab reconnaissance, pair it with Nmap on Debian, then keep scans narrow and authorized before importing results into Metasploit workspaces.