Skip to main content

​
Installing PocketMine-MP

PocketMine-MP can be installed in several ways depending on your platform and use case. Choose the method that best suits your needs.

​
Installation Methods

Pre-built PHAR

Download and run the ready-to-use PHAR file (recommended for most users)

Docker

Run in a container with all dependencies included

From Source

Build from source code for development or customization

​
Pre-requisites

PocketMine-MP requires PHP 8.2 or newer with several non-standard extensions. PMMP provides custom PHP binaries that include all required extensions.

​
System Requirements

  • OS: Linux, macOS, or Windows
  • RAM: Minimum 2GB (4GB+ recommended)
  • PHP: 8.2 or newer (custom binaries recommended)
  • Disk Space: At least 1GB for server and worlds
This is the easiest method for most users.
1

Download PHP Binary

Download a pre-built PHP binary from pmmp/PHP-BinariesChoose the appropriate binary for your platform:
  • Linux (x86_64)
  • Windows (x86_64)
  • macOS (x86_64 or ARM64)
2

Download PocketMine-MP

Download the latest PocketMine-MP.phar from GitHub Releases
3

Extract and Setup

Extract the PHP binary and place PocketMine-MP.phar in the same directoryYour directory structure should look like:
pocketmine/
├── bin/
│   └── php7/
│       └── bin/
│           └── php
├── PocketMine-MP.phar
└── start.sh (or start.cmd for Windows)
4

Run the Server

Use the provided start script:
./start.sh
Or run directly:
./bin/php7/bin/php PocketMine-MP.phar

​
Using the Start Script

The start.sh script provides additional features: 
# Basic usage
./start.sh

# Specify custom PHP binary
./start.sh -p /path/to/php

# Specify custom PocketMine-MP.phar
./start.sh -f /path/to/PocketMine-MP.phar

# Enable auto-restart on crash
./start.sh -l
The -l flag enables loop mode, which automatically restarts the server if it crashes. To exit loop mode, press Ctrl+C during the 5-second restart countdown.

​
Method 2: Docker

See the Docker Setup Guide for detailed instructions on running PocketMine-MP in a container. Quick start: 
mkdir -p data plugins
sudo chown -R 1000:1000 data plugins
docker run -it -p 19132:19132/udp \
  -v $PWD/data:/data \
  -v $PWD/plugins:/plugins \
  ghcr.io/pmmp/pocketmine-mp

​
Method 3: Building from Source

For developers and contributors who want to build PocketMine-MP from source.

​
Pre-requisites

  • A bash shell (Git Bash for Windows)
  • git command-line tool
  • PHP 8.2 or newer
  • composer package manager
1

Clone the Repository

git clone https://github.com/pmmp/PocketMine-MP.git
cd PocketMine-MP
2

Install Dependencies

composer install
3

Run from Source

Run directly from source code:
php src/PocketMine.php

​
Building a PHAR

To create a distributable PocketMine-MP.phar: 
# For production builds
composer install --no-dev --classmap-authoritative
composer make-server
This creates PocketMine-MP.phar in the current directory.
Use --no-dev --classmap-authoritative flags for production builds to reduce file size and improve autoloading performance.

​
Custom Build Options

# Specify output filename
composer make-server -- --out MyServer.phar

# Development build (includes dev dependencies)
composer install
composer make-server

​
Custom PHP Binaries

Standard PHP installations may not include all required extensions for PocketMine-MP. Using PMMP’s custom PHP binaries is strongly recommended.
PocketMine-MP requires several non-standard PHP extensions:
  • pthreads (for multi-threading)
  • chunkutils2 (for chunk handling)
  • igbinary (for data serialization)
  • leveldb (for world storage)
  • crypto (for encryption)
  • And more…

​
Building Custom PHP

To build your own PHP binary with all required extensions: 
# Clone compile scripts (included as submodule)
git submodule update --init build/php

# Run compile script
cd build/php
./compile.sh -t linux64 -j 4
Pre-built binaries are available at pmmp/PHP-Binaries.

​
First Run Setup

On first run, PocketMine-MP will:
  1. Generate configuration files:
    • server.properties - Basic server configuration
    • pocketmine.yml - Advanced PocketMine-MP settings
    • ops.txt - Operator permissions
    • white-list.txt - Whitelist (if enabled)
  2. Create directory structure: 
    data/
├── players/      # Player data
├── worlds/       # World files
├── plugins/      # Plugin directory
└── plugin_data/  # Plugin configuration
  3. Generate default world
  4. Start accepting connections on port 19132
The setup wizard will guide you through initial configuration. You can also run with --no-wizard to skip the wizard and use default settings.

​
Verifying Installation

Once started, you should see: 
[Server thread/INFO]: Starting Minecraft: BE server version vX.XX.XX
[Server thread/INFO]: Loading server properties...
[Server thread/INFO]: Starting GS4 status listener
[Server thread/INFO]: Setting query port to 19132
[Server thread/INFO]: Server started on 0.0.0.0:19132
[Server thread/INFO]: Done (X.XXXs)! For help, type "help" or "?"

​
Next Steps

Quick Start Guide

Learn how to configure and use your server

Server Configuration

Customize server.properties and pocketmine.yml

Adding Plugins

Install plugins from Poggit

Docker Guide

Advanced Docker setup and usage

​
Troubleshooting

​
Port Already in Use

If you see “Failed to bind to port”, another service is using port 19132. 
# Find what's using the port (Linux/macOS)
sudo lsof -i :19132

# Change the port in server.properties
server-port=19133

​
PHP Extension Missing

If you see extension errors, you’re likely not using a PMMP PHP binary.
Download pre-built PHP binaries from pmmp/PHP-Binaries to avoid extension issues.

​
Permission Denied (Linux/macOS)

Make the start script executable: 
chmod +x start.sh

Build docs developers (and LLMs) love

Get started for freeTalk to us