How to Install Metasploit Framework

The fastest way to install Metasploit Framework depends on your platform: on Kali Linux it is already pre-installed (just run msfconsole); on other Linux distributions use Rapid7's official nightly installer script (msfinstall); and on Windows and macOS you download the signed installer package from the official Metasploit sites. After installing, you initialize the PostgreSQL database with msfdb init and verify the setup inside msfconsole by running db_status and version. The whole process takes 5–15 minutes on a typical machine.

That is the summary an AI overview would give you. What it can't give you is the part that actually matters when the install goes sideways: which method is right for your situation, why the Windows path needs a Defender exclusion before you start, how to fix the "No database connection" error that trips up most beginners, and how to prove your install actually works before you rely on it. This guide walks all of that, per operating system, with a copy-paste command flow and a verification checklist.

⚠️ Authorization notice: Metasploit is a legitimate security tool, but only run it against systems you own or have explicit written authorization to test. Unauthorized use violates laws including the U.S. Computer Fraud and Abuse Act (CFAA) and its international equivalents. Practice on deliberately vulnerable targets like Metasploitable, not on anything you don't have permission to touch.

Which install method should I use?

Pick your row, run the command, and skip straight to that platform's section below. Kali is the recommended starting point for beginners — everything is pre-wired.

Platform	Recommended method	Core command	Database
Kali Linux (2020.1+)	Already pre-installed	msfconsole (update via apt upgrade metasploit-framework)	PostgreSQL pre-configured; msfdb init if needed
Debian / Ubuntu	Official Rapid7 nightly installer	curl .../msfinstall > msfinstall && chmod 755 msfinstall && ./msfinstall	Install PostgreSQL, then sudo msfdb init
Other Linux (Fedora/RHEL/Arch)	Same nightly installer (detects distro)	./msfinstall	Install PostgreSQL, then sudo msfdb init
Windows 10/11	Signed .msi from windows.metasploit.com	Run installer as Administrator, then msfdb.bat init	Bundled PostgreSQL — no separate install
macOS	Signed .pkg from osx.metasploit.com	Run .pkg, then msfdb init	Install PostgreSQL via Homebrew

The one-line rule: if you are learning, use Kali Linux — the framework, Ruby, and PostgreSQL are already installed and integrated. If you must stay on your existing OS, use the official Rapid7 installer for that platform and never a third-party mirror (the installer runs with root/admin privileges).

The install-to-verify flow

Every platform follows the same four-stage sequence. Install the framework, set up the PostgreSQL database, launch the console, then confirm it works — don't skip the last stage.

What is Metasploit Framework?

Metasploit Framework is an open-source penetration testing platform developed by Rapid7. It provides security professionals with:

• Exploit modules: Pre-built exploits for known vulnerabilities
• Payloads: Code that executes on target systems (shells, Meterpreter, etc.)
• Auxiliary modules: Scanners, fuzzers, and reconnaissance tools
• Post-exploitation modules: Tools for maintaining access and gathering information
• Encoders: Payload obfuscation to evade detection

Unlike the commercial Metasploit Pro version, Metasploit Framework is completely free and maintained by the security community.

System Requirements

Before installing Metasploit, ensure your system meets these requirements:

Minimum Requirements:

• CPU: Dual-core processor (quad-core recommended)
• RAM: 4GB minimum (8GB+ recommended for heavy use)
• Disk Space: 2GB for Metasploit + 10GB+ for database and modules
• Network: Internet connection for updates and module downloads

Software Dependencies:

• Ruby: Version 3.0 or higher (included in installers)
• PostgreSQL: Version 12+ (for database support)
• Git: For installing from source (optional)

Installing Metasploit on Kali Linux

Kali Linux is the most popular platform for Metasploit, as it comes pre-installed with the framework and all dependencies.

Method 1: Using Pre-installed Metasploit (Kali 2020.1+)

Since Kali Linux 2020.1, Metasploit comes pre-installed. To verify and update:

# Check if Metasploit is installed
msfconsole --version

# Update Metasploit to latest version
sudo apt update && sudo apt upgrade metasploit-framework -y

Method 2: Fresh Installation via APT

If Metasploit isn't installed or you need a clean installation:

# Update package lists
sudo apt update

# Install Metasploit Framework
sudo apt install metasploit-framework -y

# Install PostgreSQL (required for database)
sudo apt install postgresql postgresql-contrib -y

Setting Up the Database on Kali Linux

Metasploit requires a PostgreSQL database for storing host information, scan results, and credentials:

# Start PostgreSQL service
sudo systemctl start postgresql

# Enable PostgreSQL to start on boot
sudo systemctl enable postgresql

# Initialize the Metasploit database
sudo msfdb init

# Verify database connection
msfconsole -q
msf6 > db_status

You should see output confirming: [*] Connected to msf. Connection type: postgresql.

Installing Metasploit on Ubuntu/Debian Linux

For non-Kali Debian-based systems, use the official Rapid7 installer:

Step 1: Download and Run the Installer Script

# Download the official installer
curl https://raw.githubusercontent.com/rapid7/metasploit-omnibus/master/config/templates/metasploit-framework-wrappers/msfupdate.erb > msfinstall

# Make it executable
chmod 755 msfinstall

# Run the installer (requires sudo)
sudo ./msfinstall

This script will:

• Add Rapid7's GPG key to your system
• Add the Metasploit repository to your package sources
• Install Metasploit Framework and dependencies
• Set up the correct permissions

Step 2: Install and Configure PostgreSQL

# Install PostgreSQL
sudo apt install postgresql postgresql-contrib -y

# Start PostgreSQL service
sudo systemctl start postgresql
sudo systemctl enable postgresql

# Initialize Metasploit database
sudo msfdb init

Step 3: Verify Installation

# Launch Metasploit console
msfconsole

# Check database connection
msf6 > db_status

# Check Metasploit version
msf6 > version

Installing Metasploit on Windows

Installing Metasploit on Windows requires additional considerations due to antivirus software and permissions.

Step 1: Configure Windows Defender (Critical!)

Before installation, add exclusions to Windows Defender to prevent false positives:

1. Open Windows Security → Virus & threat protection
2. Under "Virus & threat protection settings," click Manage settings
3. Scroll to Exclusions and click Add or remove exclusions
4. Add the following folder: C:\metasploit-framework

Step 2: Download the Windows Installer

1. Visit: https://windows.metasploit.com/metasploitframework-latest.msi
2. Download the .msi installer package (approximately 300MB)
3. Right-click the installer and select "Run as Administrator"

Step 3: Complete the Installation Wizard

• Accept the license agreement
• Choose installation directory (default: C:\metasploit-framework)
• Select components (install all recommended components)
• Wait for installation to complete (5-10 minutes)

Step 4: Initialize the Database

Open Command Prompt as Administrator and run:

# Navigate to Metasploit directory
cd C:\metasploit-framework\bin

# Initialize database
msfdb.bat init

# Launch Metasploit console
msfconsole.bat

Note: On Windows, Metasploit uses a bundled PostgreSQL instance, so you don't need to install it separately.

Installing Metasploit on macOS

macOS installation is straightforward using the official installer package.

Step 1: Download the macOS Installer

Visit: https://osx.metasploit.com/metasploitframework-latest.pkg

Step 2: Install the Package

1. Double-click the downloaded .pkg file
2. Follow the installation wizard
3. Provide administrator password when prompted
4. Allow installation to complete

Step 3: Install PostgreSQL (via Homebrew)

# Install Homebrew (if not already installed)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install PostgreSQL
brew install postgresql

# Start PostgreSQL service
brew services start postgresql

# Initialize Metasploit database
msfdb init

Step 4: Add Metasploit to PATH

# Add to your shell profile (~/.zshrc or ~/.bash_profile)
echo 'export PATH=/opt/metasploit-framework/bin:$PATH' >> ~/.zshrc

# Reload shell configuration
source ~/.zshrc

# Test Metasploit
msfconsole --version

Installing from Source (Advanced)

For developers or users who want the latest bleeding-edge features:

# Install dependencies (Debian/Ubuntu)
sudo apt install build-essential zlib1g-dev libpq-dev libpcap-dev libsqlite3-dev ruby-dev

# Clone the repository
git clone https://github.com/rapid7/metasploit-framework.git
cd metasploit-framework

# Install Ruby dependencies
gem install bundler
bundle install

# Run Metasploit
./msfconsole

Pros:

• Access to latest features and fixes
• Ability to contribute to development
• Full control over installation

Cons:

• Requires manual updates (git pull)
• More complex troubleshooting
• May encounter unstable builds

Database Configuration and Optimization

Why Use a Database?

While Metasploit can run without a database, many essential features require it:

• Workspace management: Organize different penetration tests
• Host tracking: Store discovered hosts and services
• Credential storage: Save captured credentials
• Loot management: Store files extracted from targets
• Session tracking: Manage multiple active sessions

Essential Database Commands

# Check database status
db_status

# Create a new workspace
workspace -a pentest_project

# List all workspaces
workspace

# Switch between workspaces
workspace pentest_project

# View stored hosts
hosts

# View stored services
services

# View captured credentials
creds

Database Maintenance

# Rebuild database (if corrupted)
msfdb reinit

# Delete database
msfdb delete

# Check database service status
msfdb status

# Start database service
msfdb start

# Stop database service
msfdb stop

Common Installation Issues and Solutions

Issue 1: "Bundler gem required" Error

Symptoms: Error message stating "Metasploit requires the Bundler gem to be installed"

Solution:

# Install Bundler gem
gem install bundler

# Navigate to Metasploit directory
cd /opt/metasploit-framework

# Install dependencies
bundle install

Issue 2: Database Connection Failed

Symptoms: db_status shows "No database connection"

Solution:

# Ensure PostgreSQL is running
sudo systemctl status postgresql

# If not running, start it
sudo systemctl start postgresql

# Reinitialize database
sudo msfdb reinit

# Verify connection
msfconsole -q
msf6 > db_status

Issue 3: Permission Denied Errors (Linux/macOS)

Symptoms: Permission errors when running msfconsole or updating

Solution:

# Fix ownership of Metasploit directory
sudo chown -R $(whoami) /opt/metasploit-framework

# Fix database permissions
sudo msfdb reinit

Issue 4: Antivirus Blocking Installation (Windows)

Symptoms: Installation fails or files are quarantined

Solution:

1. Temporarily disable real-time protection
2. Add C:\metasploit-framework to exclusions
3. Re-run the installer as Administrator
4. Re-enable real-time protection after installation

Issue 5: Ruby Version Conflicts

Symptoms: Errors about Ruby version compatibility

Solution:

# Check Ruby version
ruby --version

# Use the bundled Ruby (recommended)
# The installer includes the correct Ruby version

# If using system Ruby, install rbenv or rvm
# to manage Ruby versions separately

Updating Metasploit

Keeping Metasploit up-to-date ensures you have the latest exploits and security patches.

Updating on Linux (APT Installation)

# Update package lists
sudo apt update

# Upgrade Metasploit
sudo apt upgrade metasploit-framework

Updating via msfupdate (Installer Method)

# Update Metasploit Framework
sudo msfupdate

# Or manually update modules
msfconsole -q
msf6 > msfupdate

Updating from Source

# Navigate to Metasploit directory
cd metasploit-framework

# Pull latest changes
git pull

# Update Ruby dependencies
bundle install

Verifying Your Installation

After installation, verify everything works correctly:

# Launch Metasploit console
msfconsole

# Inside msfconsole, run these verification commands:

# 1. Check version
msf6 > version

# 2. Verify database connection
msf6 > db_status

# 3. Search for a module
msf6 > search ms17-010

# 4. Load a module
msf6 > use exploit/multi/handler

# 5. Show module options
msf6 exploit(multi/handler) > show options

# 6. Exit console
msf6 > exit

If all these commands work without errors, your installation is successful!

Post-install verification checklist

Tick each item before you consider the install done and start any authorized engagement:

• msfconsole launches without Ruby or gem errors
• version prints a current build number (framework updates almost daily)
• db_status reports Connected to msf. Connection type: postgresql
• PostgreSQL is enabled to start on boot (systemctl enable postgresql on Linux)
• search ms17-010 returns module results (module database loaded)
• use exploit/multi/handler then show options runs cleanly
• A workspace exists for your project (workspace -a project_name)
• (Windows) C:\metasploit-framework is excluded in Windows Defender
• You have written authorization for every target you plan to test

Once the console is running, you can build your first module commands visually instead of memorizing syntax:

Best Practices for Metasploit Installation

1. Use Official Sources: Always download from official Rapid7 or Kali repositories
2. Database Setup: Configure PostgreSQL immediately after installation
3. Regular Updates: Update Metasploit weekly to get new modules and fixes
4. Workspace Organization: Create separate workspaces for different projects
5. Antivirus Exclusions: Properly configure exclusions to prevent false positives
6. Backup Database: Regularly export database contents for important projects
7. Resource Scripts: Create .rc files to automate common setup tasks
8. Documentation: Keep notes on custom configurations and installed gems

Next Steps After Installation

Once Metasploit is installed, explore these essential topics:

1. Learn msfconsole Commands: Familiarize yourself with search, use, set, and exploit commands
2. Understand Modules: Explore the difference between exploits, auxiliary, and post modules
3. Practice with Vulnerable VMs: Use Metasploitable, DVWA, or HackTheBox for legal practice
4. Master Meterpreter: Learn advanced post-exploitation with Meterpreter sessions
5. Database Workflow: Practice workspace management and data organization
6. Automation: Create resource scripts for repetitive tasks

Helpful Resources:

• Metasploit Unleashed - Free official training
• Rapid7 Documentation - Official Metasploit docs
• Metasploit Command Builder - Generate commands visually

Conclusion

Installing Metasploit Framework is straightforward once you understand the platform-specific requirements and potential pitfalls. Whether you choose Kali Linux for its pre-configured environment, Windows for familiarity, or macOS for convenience, following this guide ensures a smooth installation process.

Remember that Metasploit is a powerful tool that should only be used for authorized security testing. Always obtain explicit written permission before testing any system or network you don't own. Improper use may be illegal and result in serious legal consequences.

With Metasploit properly installed and configured, you're ready to begin your journey into penetration testing, vulnerability assessment, and ethical hacking. Start with vulnerable practice environments, continue learning through official documentation, and always practice responsible disclosure when you discover real vulnerabilities.

Ready to start building Metasploit commands? Try our Metasploit Command Builder to generate msfconsole commands with a visual interface, complete with module presets and payload selectors.