Skip to main content
Paper provides extensive configuration options through multiple configuration files. This guide covers the essential configuration files and settings you’ll need to customize your server.

​
Configuration Files Overview

Paper uses several configuration files, each serving a different purpose:
FilePurpose
server.propertiesCore Minecraft server settings
bukkit.ymlBukkit platform configuration
spigot.ymlSpigot platform configuration
commands.ymlCommand aliases and overrides
config/paper-global.ymlPaper global configuration
config/paper-world-defaults.ymlPaper world default settings
permissions.ymlPermission definitions
help.ymlCustom help topics
Paper stores its configuration files in the config/ directory. The main Paper configurations are paper-global.yml and paper-world-defaults.yml.

​
server.properties

This is the primary configuration file for basic server settings. It’s generated on first run.

​
Essential Settings

server.properties
# Network Settings
server-ip=
server-port=25565
query.port=25565

# World Settings
level-name=world
level-seed=
generator-settings={}
level-type=minecraft\:normal

# Gameplay Settings
difficulty=normal
gamemode=survival
force-gamemode=false
hardcore=false
pvp=true

# Player Settings
max-players=20
player-idle-timeout=0
view-distance=10
simulation-distance=10

# Security
online-mode=true
white-list=false
enforce-whitelist=false
allow-flight=false

# Performance
max-tick-time=60000
max-world-size=29999984
entity-broadcast-range-percentage=100

# Server Information
motd=A Minecraft Server
resource-pack=
resource-pack-prompt=
resource-pack-sha1=

​
Key Configuration Options

  • server-ip - The IP address to bind to (leave empty for all interfaces)
  • server-port - The port players connect to (default: 25565)
  • online-mode - Enable Mojang authentication (true for production servers)
  • level-name - The name of the world folder
  • level-seed - World generation seed (empty for random)
  • level-type - World type (normal, flat, large_biomes, amplified)
  • allow-nether - Enable the Nether dimension
  • allow-end - Enable the End dimension (configured in bukkit.yml)
  • difficulty - Game difficulty (peaceful, easy, normal, hard)
  • gamemode - Default game mode (survival, creative, adventure, spectator)
  • hardcore - Enable hardcore mode (permanent death)
  • pvp - Allow player vs player combat
  • spawn-monsters - Allow hostile mob spawning
  • spawn-animals - Allow passive mob spawning
  • view-distance - How far players can see (2-32 chunks, 10 recommended)
  • simulation-distance - How far chunks are actively simulated (3-32)
  • max-tick-time - Watchdog timeout in milliseconds
  • entity-broadcast-range-percentage - Entity visibility range (100 = default)
Setting online-mode=false disables Mojang authentication and allows cracked clients. This is a security risk and should only be used for local testing or with a proxy like Velocity.

​
bukkit.yml

Bukkit configuration file with spawn limits and basic settings.
bukkit.yml
settings:
  allow-end: true
  warn-on-overload: true
  permissions-file: permissions.yml
  update-folder: update
  plugin-profiling: false
  connection-throttle: 4000
  query-plugins: true
  deprecated-verbose: default
  shutdown-message: Server closed
  minimum-api: none
  use-map-color-cache: true

spawn-limits:
  monsters: 70
  animals: 10
  water-animals: 5
  water-ambient: 20
  water-underground-creature: 5
  axolotls: 5
  ambient: 15

chunk-gc:
  period-in-ticks: 600

ticks-per:
  animal-spawns: 400
  monster-spawns: 1
  water-spawns: 1
  water-ambient-spawns: 1
  water-underground-creature-spawns: 1
  axolotl-spawns: 1
  ambient-spawns: 1
  autosave: 6000

aliases: now-in-commands.yml

​
Important bukkit.yml Settings

  • spawn-limits - Maximum number of each mob type per world
  • ticks-per.autosave - How often to save worlds (6000 = 5 minutes)
  • connection-throttle - Minimum milliseconds between connections from same IP
  • warn-on-overload - Show warnings when server is running slowly
Reference: docs.papermc.io/paper/reference/bukkit-configuration

​
commands.yml

Configure command aliases and override vanilla permissions.
commands.yml
command-block-overrides: []
ignore-vanilla-permissions: false

aliases:
  icanhasbukkit:
    - "version $1-"
  # Add custom aliases:
  # tpa:
  #   - "teleport $1 $2"

​
Creating Command Aliases

You can create shortcuts for commonly used commands:
commands.yml
aliases:
  # Simple alias
  gmc:
    - "gamemode creative $1-"
  
  # Multiple commands
  spawn:
    - "tp 0 64 0"
    - "say $1 returned to spawn"
  
  # With arguments
  heal:
    - "effect clear $1"
    - "effect give $1 minecraft:instant_health 1 10"
Reference: docs.papermc.io/paper/reference/bukkit-commands-configuration

​
Paper Configuration Files

Paper introduces its own configuration system with two main files in the config/ directory.

​
config/paper-global.yml

Global settings that apply to the entire server. This file contains extensive configuration options for performance, gameplay mechanics, and server behavior.
The paper-global.yml file is created on first run and contains detailed comments for each setting. The file includes the note:“This is the global configuration file for Paper. As you can see, there’s a lot to configure. Some options may impact gameplay, so use with caution, and make sure you know what each option does before configuring.”

​
config/paper-world-defaults.yml

Default world settings that can be overridden per-world. Individual worlds can have their own paper-world.yml file in the world directory.

​
Common Paper Settings

Some frequently configured Paper settings include: 
# In paper-global.yml or paper-world-defaults.yml

# Chunk loading
chunk-loading:
  max-concurrent-sends: 2
  autoconfig-send-distance: true

# Entity activation range
entity-activation-range:
  animals: 32
  monsters: 32
  raiders: 48
  misc: 16
  water: 16
  villagers: 32
  flying-monsters: 32
Paper configuration files use a versioned format. Do not manually edit the version numbers or structure - let Paper handle migrations automatically.

​
help.yml

Customize help topics and documentation for your server.
help.yml
# Add custom help topics
general-topics:
  Rules:
    shortText: Server rules and guidelines
    fullText: |
      &61. Be respectful to other players
      &62. No griefing or stealing
      &63. No cheating or exploiting
    permission: topics.rules

# Override command help
amended-topics:
  /spawn:
    shortText: Teleport to spawn
    fullText: Returns you to the world spawn point

# Hide plugins from help
ignore-plugins:
  # - PluginName
Reference: docs.papermc.io/paper/reference/bukkit-help-configuration

​
permissions.yml

Define custom permission nodes for use with commands and plugins.
permissions.yml
# Define permission groups
moderator:
  description: Moderator permissions
  children:
    essentials.kick: true
    essentials.ban: true
    essentials.mute: true

builder:
  description: Builder permissions
  children:
    worldedit.selection.*: true
    worldedit.region.*: true
    worldedit.clipboard.*: true

​
Configuration Best Practices

1

Backup before changing

Always backup configuration files before making significant changes:
cp server.properties server.properties.backup
cp -r config config.backup
2

Change one thing at a time

Modify one setting at a time and test the impact. This makes it easier to identify issues.
3

Read the comments

Paper configuration files include detailed comments explaining what each option does. Always read them before changing values.
4

Restart when needed

Most configuration changes require a server restart. Some Paper settings support live reloading, but restarting is safest:
stop
5

Monitor performance

After changing performance settings, use /timings or Spark to monitor the impact.

​
Reloading Configuration

Some configuration files can be reloaded without restarting: 
/reload confirm
The /reload command can cause issues with some plugins and may lead to memory leaks. It’s recommended to restart your server instead of using reload when possible.

​
Per-World Configuration

Paper allows per-world configuration overrides. Create a paper-world.yml file in any world folder to override the defaults for that specific world: 
world/paper-world.yml
world_nether/paper-world.yml
world_the_end/paper-world.yml
Settings in these files override paper-world-defaults.yml for that specific world.

​
Command-Line Configuration

Many settings can be overridden via command-line arguments: 
java -jar server.jar \
  --port 25566 \
  --world my-world \
  --bukkit-settings custom-bukkit.yml \
  --paper-dir /path/to/paper/config

​
Available Options

  • --config <file> - Custom server.properties location
  • --bukkit-settings <file> - Custom bukkit.yml location
  • --spigot-settings <file> - Custom spigot.yml location
  • --paper-dir <directory> - Custom Paper config directory
  • --plugins <directory> - Custom plugins directory
  • --world-dir <directory> - Custom world container directory
  • --port <port> - Override server port
  • --world <name> - Override level-name

​
Getting Help

For detailed configuration documentation:
Each Paper configuration file includes a reference URL at the top pointing to detailed documentation for that specific file.

Build docs developers (and LLMs) love

Get started for freeTalk to us