Installation - Pumpkin

This guide covers multiple methods for installing Pumpkin. Choose the method that best fits your needs.

System requirements

Minimum requirements

CPU: 2 cores
RAM: 2GB
Storage: 1GB for server files, plus space for worlds
OS: Linux, macOS, or Windows

Recommended requirements

CPU: 4+ cores
RAM: 4GB or more
Storage: SSD with 10GB+ available
Network: Stable internet connection for online mode

Software requirements

For Docker: Docker 20.10+ and Docker Compose 2.0+ (optional)
For source builds: Rust 1.89+ and Cargo
For running: Minecraft Java Edition 1.21.11 (clients)

Installation methods

Docker

Recommended for most users

From source

Best for development

Pre-built binary

Quick setup (when available)

Docker installation

Docker is the recommended installation method for most users. It provides isolation, easy updates, and consistent behavior across platforms.

Prerequisites

Install Docker and Docker Compose:

sudo apt-get update
sudo apt-get install docker.io docker-compose-v2
sudo systemctl enable --now docker

Using Docker run

Run Pumpkin with a single command:

docker run -d \
  --name pumpkin \
  -p 25565:25565 \
  -p 19132:19132/udp \
  -v $(pwd)/pumpkin-data:/pumpkin \
  -e RUST_BACKTRACE=1 \
  --restart unless-stopped \
  ghcr.io/pumpkin-mc/pumpkin:master

Options explained:

-d: Run in background (detached mode)
--name pumpkin: Container name for easy reference
-p 25565:25565: Expose Java Edition port
-p 19132:19132/udp: Expose Bedrock Edition port
-v $(pwd)/pumpkin-data:/pumpkin: Mount volume for persistent data
-e RUST_BACKTRACE=1: Enable backtraces for debugging
--restart unless-stopped: Auto-restart on crashes

Using Docker Compose

For production deployments, use Docker Compose:

Create docker-compose.yml

Create a docker-compose.yml file:

docker-compose.yml

services:
  pumpkin:
    image: ghcr.io/pumpkin-mc/pumpkin:master
    ports:
      - "25565:25565"
      - "19132:19132/udp"
    volumes:
      - ./data:/pumpkin
    environment:
      - RUST_BACKTRACE=1
    security_opt:
      - no-new-privileges:true
    restart: unless-stopped
    stdin_open: true
    tty: true
    cap_drop:
      - ALL
    read_only: true

This configuration includes security best practices like dropping capabilities and running with a read-only filesystem.

Start the server

Launch Pumpkin:

docker compose up -d

View logs:

docker compose logs -f pumpkin

Manage the server

Useful commands:

# Stop the server
docker compose down

# Restart the server
docker compose restart

# Update to latest version
docker compose pull
docker compose up -d

# Access server console
docker attach pumpkin
# Press Ctrl+P, Ctrl+Q to detach without stopping

Building Docker image locally

To build the Docker image yourself:

git clone https://github.com/Pumpkin-MC/Pumpkin.git
cd Pumpkin
docker build -t pumpkin:local .

The Dockerfile uses a multi-stage build:

Builder stage: Compiles Pumpkin from source using rust:1-alpine3.23
Runtime stage: Creates minimal Alpine-based image with just the binary

This results in a small, efficient container image.

Building from source

Building from source gives you the latest features and allows customization.

Install Rust

Install Rust toolchain

Install Rust using rustup:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env

Verify installation

Confirm Rust is installed:

rustc --version
cargo --version

You should see Rust 1.89 or later.

Clone and build

Clone the repository

git clone https://github.com/Pumpkin-MC/Pumpkin.git
cd Pumpkin

Build in release mode

Compile Pumpkin with optimizations:

cargo build --release

This will:

Download and compile all dependencies
Apply release optimizations (LTO, single codegen unit)
Take 5-15 minutes on first build
Produce a binary at target/release/pumpkin

Release builds are 10-100x faster than debug builds. Always use --release for running a server.

Run the server

Start Pumpkin:

./target/release/pumpkin

Or use Cargo:

cargo run --release

The server will create a config directory with default configuration on first run.

Development build

For development and testing:

# Build and run in debug mode (faster compilation, slower runtime)
cargo run

# Run tests
cargo test

# Run clippy linter
cargo clippy --all-targets

# Format code
cargo fmt

Debug builds have significantly lower performance. Use --release for any performance testing or actual gameplay.

Pre-built binaries

Pre-built binaries will be available for stable releases. Currently, Pumpkin is in active development, so building from source or using Docker is recommended. Check the GitHub Releases page for available downloads once the first stable version is released.

Post-installation setup

After installing Pumpkin, configure your server:

Configuration files

Pumpkin creates two configuration files in the config directory:

# Basic server configuration
java_edition = true
java_edition_address = "0.0.0.0:25565"
bedrock_edition = true
bedrock_edition_address = "0.0.0.0:19132"

seed = 0  # Random seed generated on first run
max_players = 1000
view_distance = 16
simulation_distance = 10

default_difficulty = "Normal"
op_permission_level = 4

allow_nether = true
allow_end = true
hardcore = false

online_mode = true
encryption = true

motd = "A blazingly fast Pumpkin server!"
tps = 20.0

default_gamemode = "Survival"
force_gamemode = false

scrub_ips = true
use_favicon = true
favicon_path = null

default_level_name = "world"

allow_chat_reports = false
white_list = false
enforce_whitelist = false

See the configuration guide for detailed explanations of all options.

Directory structure

Pumpkin creates the following directory structure:

.
├── config/
│   ├── configuration.toml
│   └── features.toml
├── world/              # Default world (if not specified)
│   ├── region/
│   ├── level.dat
│   └── ...
└── pumpkin             # Executable (if built from source)

Firewall configuration

Open the required ports in your firewall:

sudo ufw allow 25565/tcp  # Java Edition
sudo ufw allow 19132/udp  # Bedrock Edition
sudo ufw allow 25575/tcp  # RCON (optional)

Updating Pumpkin

Docker

Update to the latest version:

docker compose pull
docker compose up -d

From source

Pull the latest changes and rebuild:

cd Pumpkin
git pull
cargo build --release

Always back up your world and configuration files before updating.

Uninstalling

Docker

Remove the container and images:

docker compose down
docker rmi ghcr.io/pumpkin-mc/pumpkin:master

To also remove data:

rm -rf ./data  # or your mounted volume directory

From source

Simply delete the Pumpkin directory:

rm -rf Pumpkin

Troubleshooting

Rust version too old

Update Rust to the latest stable version:

rustup update stable
rustup default stable

Build fails with linker errors

Install build dependencies:

sudo apt-get install build-essential pkg-config libssl-dev

Permission denied (Docker)

Add your user to the docker group:

sudo usermod -aG docker $USER
newgrp docker

Port already in use

Find and stop the process using the port:

# Linux/macOS
sudo lsof -i :25565
sudo kill -9 <PID>

# Windows
netstat -ano | findstr :25565
taskkill /PID <PID> /F

Next steps

Configuration

Configure your server settings

World Management

Set up and manage your worlds

Commands

Learn available server commands

Deployment

Deploy to production

For additional help, join the Discord community or check the GitHub issues.

Getting Started

Configuration

Core Features

Deployment

Development

​System requirements

​Minimum requirements

​Recommended requirements

​Software requirements

​Installation methods

Docker

From source

Pre-built binary

​Docker installation

​Prerequisites

​Using Docker run

​Using Docker Compose

​Building Docker image locally

​Building from source

​Install Rust

​Clone and build

​Development build

​Pre-built binaries

​Post-installation setup

​Configuration files

​Directory structure

​Firewall configuration

​Updating Pumpkin

​Docker

​From source

​Uninstalling

​Docker

​From source

​Troubleshooting

​Rust version too old

​Build fails with linker errors

​Permission denied (Docker)

​Port already in use

​Next steps

Configuration

World Management

Commands

Deployment

Build docs developers (and LLMs) love

System requirements

Minimum requirements

Recommended requirements

Software requirements

Installation methods

Docker installation

Prerequisites

Using Docker run

Using Docker Compose

Building Docker image locally

Building from source

Install Rust

Clone and build

Development build

Pre-built binaries

Post-installation setup

Configuration files

Directory structure

Firewall configuration

Updating Pumpkin

Docker

From source

Uninstalling

Docker

From source

Troubleshooting

Rust version too old

Build fails with linker errors

Permission denied (Docker)

Port already in use

Next steps