Installing I2P on macOS (The Long Way)

What You’ll Need

• A Mac running macOS 10.14 (Mojave) or later
• Administrator access to install applications
• About 15-20 minutes of time
• Internet connection for downloading installers

Overview

This installation process has four main steps:

1. Install Java - Download and install Oracle Java Runtime Environment
2. Install I2P - Download and run the I2P installer
3. Configure I2P App - Set up the launcher and add to your dock
4. Configure I2P Bandwidth - Run the setup wizard to optimize your connection

Part One: Install Java

I2P requires Java to run. If you already have Java 8 or later installed, you can skip to Part Two.

Step 1: Download Java

Visit the Oracle Java download page and download the macOS installer for Java 8 or later.

Step 2: Run the Installer

Locate the downloaded .dmg file in your Downloads folder and double-click to open it.

Step 3: Allow Installation

macOS may display a security prompt because the installer is from an identified developer. Click Open to proceed.

Step 4: Install Java

Click Install to begin the Java installation process.

Step 5: Wait for Installation

The installer will copy files and configure Java on your system. This usually takes 1-2 minutes.

Step 6: Installation Complete

When you see the success message, Java is installed! Click Close to finish.

Part Two: Download and Install I2P

Now that Java is installed, you can install the I2P router.

Step 1: Download I2P

Visit the Downloads page and download the I2P for Unix/Linux/BSD/Solaris installer (the .jar file).

Step 2: Run the Installer

Double-click the downloaded i2pinstall_X.X.X.jar file. The installer will launch and ask you to select your preferred language.

Step 3: Welcome Screen

Read the welcome message and click Next to continue.

Step 4: Important Notice

The installer will display an important notice about updates. I2P updates are end-to-end signed and verified, even though this installer itself is unsigned. Click Next.

Step 5: License Agreement

Read the I2P license agreement (BSD-style license). Click Next to accept.

Step 6: Select Installation Directory

Choose where to install I2P. The default location (/Applications/i2p) is recommended. Click Next.

Step 7: Select Components

Leave all components selected for a complete installation. Click Next.

Step 8: Start Installation

Review your choices and click Next to begin installing I2P.

Step 9: Installing Files

The installer will copy I2P files to your system. This takes about 1-2 minutes.

Step 10: Generate Launch Scripts

The installer creates launch scripts for starting I2P.

Step 11: Installation Shortcuts

The installer offers to create desktop shortcuts and menu entries. Make your selections and click Next.

Step 12: Installation Complete

Success! I2P is now installed. Click Done to finish.

Part Three: Configure I2P App

Now let’s make I2P easy to launch by adding it to your Applications folder and Dock.

Step 1: Open Applications Folder

Open Finder and navigate to your Applications folder.

Step 2: Find I2P Launcher

Look for the I2P folder or the Start I2P Router application inside /Applications/i2p/.

Step 3: Add to Dock

Drag the Start I2P Router application to your Dock for easy access. You can also create an alias on your desktop.

Tip: Right-click the I2P icon in the Dock and select Options → Keep in Dock to make it permanent.

Part Four: Configure I2P Bandwidth

When you first launch I2P, you’ll run through a setup wizard to configure your bandwidth settings. This helps optimize I2P’s performance for your connection.

Step 1: Launch I2P

Click the I2P icon in your Dock (or double-click the launcher). Your default web browser will open to the I2P Router Console.

Step 2: Welcome Wizard

The setup wizard will greet you. Click Next to begin configuring I2P.

Step 3: Language and Theme

Select your preferred interface language and choose between light or dark theme. Click Next.

Step 4: Bandwidth Test Information

The wizard will explain the bandwidth test. This test connects to the M-Lab service to measure your internet speed. Click Next to proceed.

Step 5: Run Bandwidth Test

Click Run Test to measure your upload and download speeds. The test takes about 30-60 seconds.

Step 6: Test Results

Review your test results. I2P will recommend bandwidth settings based on your connection speed.

Step 7: Configure Bandwidth Sharing

Choose how much bandwidth you want to share with the I2P network:

• Automatic (Recommended): I2P manages bandwidth based on your usage
• Limited: Set specific upload/download limits
• Unlimited: Share as much as possible (for fast connections)

Click Next to save your settings.

Step 8: Configuration Complete

Your I2P router is now configured and running! The router console will show your connection status and allow you to browse I2P sites.

Getting Started with I2P

Now that I2P is installed and configured, you can:

1. Browse I2P sites: Visit the I2P homepage to see links to popular I2P services
2. Configure your browser: Set up a browser profile to access .i2p sites
3. Explore services: Check out I2P email, forums, file sharing, and more
4. Monitor your router: The console shows your network status and statistics

Useful Links

• Router Console: http://127.0.0.1:7657/
• Configuration: http://127.0.0.1:7657/config
• Address Book: http://127.0.0.1:7657/susidns/addressbook
• Bandwidth Settings: http://127.0.0.1:7657/config

Re-running the Setup Wizard

If you want to change your bandwidth settings or re-configure I2P later, you can re-run the welcome wizard from the Router Console:

1. Go to I2P Setup Wizard
2. Follow the wizard steps again

Troubleshooting

I2P Won’t Start

• Check Java: Make sure Java is installed by running java -version in Terminal
• Check permissions: Ensure the I2P folder has the correct permissions
• Check logs: Look at ~/.i2p/wrapper.log for error messages

Browser Can’t Access I2P Sites

• Make sure I2P is running (check the Router Console)
• Configure your browser’s proxy settings to use HTTP proxy 127.0.0.1:4444
• Wait 5-10 minutes after starting for I2P to integrate into the network

Slow Performance

• Run the bandwidth test again and adjust your settings
• Make sure you’re sharing some bandwidth with the network
• Check your connection status in the Router Console

Uninstalling I2P

To remove I2P from your Mac:

1. Quit the I2P router if it’s running
2. Delete the /Applications/i2p folder
3. Delete the ~/.i2p folder (your I2P configuration and data)
4. Remove the I2P icon from your Dock

Next Steps

• Join the community: Visit i2pforum.net or check out I2P on Reddit
• Learn more: Read the I2P documentation to understand how the network works
• Get involved: Consider contributing to I2P development or running infrastructure

Congratulations! You’re now part of the I2P network. Welcome to the invisible internet!