Skip to main content
Keeping your PocketMine-MP server updated ensures you have the latest features, performance improvements, bug fixes, and security patches.

​
Before Updating

Always backup your server before updating. Updates can occasionally cause issues with plugins or worlds.

​
Pre-update Checklist

1

Backup everything

# Backup critical files and directories
cp -r worlds/ worlds.backup/
cp -r plugins/ plugins.backup/
cp server.properties server.properties.backup
cp pocketmine.yml pocketmine.yml.backup
cp -r plugin_data/ plugin_data.backup/
2

Check release notes

  • Visit GitHub Releases
  • Read changelog for breaking changes
  • Note API version changes
  • Review migration guides
3

Verify plugin compatibility

  • Check if your plugins support the new version
  • Visit Poggit for plugin updates
  • Contact plugin developers if unsure
4

Schedule downtime

  • Notify players in advance
  • Choose low-traffic time
  • Plan for potential rollback time
5

Test on development server

If possible, test the update on a separate server first

​
Update Methods

PocketMine-MP can update itself automatically: 
# In server console
stop

# Start server with update flag
./start.sh --update

# Or on Windows
start.cmd --update
Automatic updates only work for point releases (e.g., 5.0.0 → 5.0.1). Major version updates require manual installation.

​
Method 2: Manual Update

1

Stop the server

stop
# Or press Ctrl+C
2

Download new version

cd /path/to/server

# Download latest stable release
wget https://github.com/pmmp/PocketMine-MP/releases/download/VERSION/PocketMine-MP.phar

# Or use curl
curl -L -o PocketMine-MP.phar https://github.com/pmmp/PocketMine-MP/releases/download/VERSION/PocketMine-MP.phar
3

Replace old version

# Backup old version
mv PocketMine-MP.phar PocketMine-MP.phar.old

# Move new version
mv PocketMine-MP.phar.new PocketMine-MP.phar

# Set permissions
chmod +x PocketMine-MP.phar
4

Start server

./start.sh

​
Method 3: Docker Update

If using the official Docker image: 
# Pull latest image
docker pull ghcr.io/pmmp/pocketmine-mp:latest

# Stop container
docker stop pocketmine

# Remove old container
docker rm pocketmine

# Start with new image
docker run -d \
  --name pocketmine \
  -p 19132:19132/udp \
  -v $(pwd)/data:/data \
  ghcr.io/pmmp/pocketmine-mp:latest

​
After Updating

1

Verify server starts

Check console for errors during startup
2

Check version

version
# Output should show new version
3

Test core functionality

  • Join the server
  • Check world loading
  • Test commands
  • Verify plugins work
4

Update plugins

# Check for incompatible plugins
plugins

# Update plugins from Poggit or plugin sources
# Replace outdated .phar files
5

Monitor for issues

  • Watch console for errors
  • Check server.log
  • Monitor performance (TPS, memory)
  • Listen to player feedback
6

Remove old backup (optional)

# After confirming everything works
rm -rf worlds.backup/
rm -rf plugins.backup/
rm PocketMine-MP.phar.old

​
Understanding Release Channels

PocketMine-MP uses different release channels:

Stable

Recommended for production
  • Thoroughly tested
  • No known major bugs
  • Suitable for public servers
  • Updated less frequently

Beta

For testing upcoming features
  • New features
  • Less tested
  • May have bugs
  • For adventurous admins

Alpha

Early testing versions
  • Very new features
  • Likely has bugs
  • Breaking changes possible
  • For developers/testers

Development

Bleeding edge
  • Latest commits
  • Unstable
  • Can break anytime
  • For development only

​
Configure Release Channel

pocketmine.yml
auto-updater:
  enabled: true
  # Choose: stable, beta, alpha, development
  preferred-channel: stable
  suggest-channels: true
Development builds require explicit opt-in:
settings:
  enable-dev-builds: true
Use development builds only for testing, never for production servers.

​
Major Version Updates

Major version updates (e.g., 4.x → 5.x) often include:
  • Breaking API changes
  • Plugin incompatibility
  • Configuration changes
  • World format updates

​
Major Update Process

1

Research breaking changes

  • Read migration guides
  • Review release notes thoroughly
  • Check GitHub discussions
2

Update all plugins first

  • Get versions compatible with new API
  • Remove plugins without updates
  • Find alternatives if needed
3

Test extensively

  • Set up test server with backup data
  • Run full update process
  • Test for several days
4

Plan migration day

  • Schedule maintenance window
  • Notify players well in advance
  • Prepare rollback plan
5

Perform update

Follow manual update method above
6

Monitor closely

Watch for issues for first few days
Major updates are released infrequently. Most updates are minor versions with backward compatibility.

​
Rollback Procedure

If the update causes critical issues:
1

Stop the server

stop
2

Restore old version

# Restore PocketMine-MP
mv PocketMine-MP.phar PocketMine-MP.phar.broken
mv PocketMine-MP.phar.old PocketMine-MP.phar
3

Restore backups

# Only if worlds were corrupted
rm -rf worlds/
mv worlds.backup/ worlds/

# Restore plugins if needed
rm -rf plugins/
mv plugins.backup/ plugins/
4

Restart server

./start.sh
5

Report issues

  • Create GitHub issue with details
  • Include crash dumps
  • Describe what went wrong
Rollback is why backups are critical. Always backup before updating.

​
Update Best Practices

  • Check for updates weekly
  • Subscribe to GitHub release notifications
  • Join Discord for announcements
  • Read changelogs regularly
  • Update sequentially through versions
  • Don’t jump multiple major versions
  • Read all changelogs between versions
  • Keep multiple backup generations
  • Store backups off-server
  • Test backup restoration occasionally
  • Keep notes on custom settings
  • Document plugin configurations
  • Track what you’ve changed from defaults
  • Clone production to test server
  • Update test server first
  • Verify everything works before production update

​
Automated Update Script

Example update script for Linux servers:
update.sh
#!/bin/bash
SERVER_DIR="/path/to/server"
BACKUP_DIR="/path/to/backups"
DATE=$(date +%Y-%m-%d_%H-%M-%S)

# Stop server (if using systemd)
sudo systemctl stop pocketmine

# Backup
mkdir -p "$BACKUP_DIR/$DATE"
cp -r "$SERVER_DIR/worlds" "$BACKUP_DIR/$DATE/"
cp -r "$SERVER_DIR/plugins" "$BACKUP_DIR/$DATE/"
cp "$SERVER_DIR/server.properties" "$BACKUP_DIR/$DATE/"
cp "$SERVER_DIR/pocketmine.yml" "$BACKUP_DIR/$DATE/"
cp "$SERVER_DIR/PocketMine-MP.phar" "$BACKUP_DIR/$DATE/"

# Download latest
cd "$SERVER_DIR"
wget -O PocketMine-MP.phar.new https://github.com/pmmp/PocketMine-MP/releases/latest/download/PocketMine-MP.phar

# Replace
mv PocketMine-MP.phar PocketMine-MP.phar.old
mv PocketMine-MP.phar.new PocketMine-MP.phar
chmod +x PocketMine-MP.phar

# Start server
sudo systemctl start pocketmine

# Check status
sleep 5
sudo systemctl status pocketmine

echo "Update complete! Backup stored in $BACKUP_DIR/$DATE"
Test automated scripts thoroughly before using in production.

​
Getting Update Notifications

  1. Go to PocketMine-MP repository
  2. Click “Watch” → “Custom” → “Releases”
  3. Receive email notifications for new releases

​
Frequently Asked Questions

Usually yes, especially for major version updates. Check plugin compatibility:
  • Visit plugin pages on Poggit
  • Read plugin update notes
  • Test plugins after server update
  • Replace incompatible plugins
No. server.properties and pocketmine.yml are preserved during updates. However:
  • New options may be added with defaults
  • Deprecated options may be removed
  • Some values may change behavior
  • Always review changelogs
Yes, with caveats:
  • Restore old PocketMine-MP.phar
  • May need to restore world backups
  • Some new features may break
  • Data created in new version may not work
  • Always use pre-update backups
For stable channel:
  • Update for security patches immediately
  • Update for bug fixes when convenient
  • Update for new features as desired
  • Generally, update monthly or when notified
Check for updates: Weekly
Some options:
  • Contact hosting support for assistance
  • Request they enable auto-updates
  • Use hosting control panel update feature
  • Consider switching to better hosting
  • Migrate to VPS for full control

​
Next Steps

Configuration

Optimize settings after updating

Troubleshooting

Resolve issues after updates

Build docs developers (and LLMs) love

Get started for freeTalk to us