How to Install Metasploit Framework - Complete Installation Guide for 2025

Metasploit Framework is the world's most widely-used penetration testing platform, providing security professionals with thousands of exploits, payloads, and auxiliary modules for authorized security testing. Whether you're a cybersecurity student, penetration tester, or security researcher, properly installing Metasploit is your first step toward mastering this powerful framework.

In this comprehensive guide, we'll walk you through installing Metasploit Framework on Linux (including Kali Linux), Windows, and macOS, configure the PostgreSQL database for optimal performance, and troubleshoot common installation issues.

⚠️ Legal Notice: Only use Metasploit on systems you own or have explicit written authorization to test. Unauthorized penetration testing is illegal and may violate laws including the Computer Fraud and Abuse Act (CFAA).

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!

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.