---
title: "PaperMC Config Files Explained: Global and Per-World | ZCS"
description: "Understand where Paper stores configuration, how global and per-world files differ, and how to test settings safely without overwriting plugin data."
url: "https://www.zcraftstudios.com/blog/minecraft-paper-configuration-files-explained"
updated: "2026-10-20T07:16:50.972429+00:00"
source: "ZCraft Studios"
---

> Site index for AI agents: https://www.zcraftstudios.com/llms.txt (full reference: https://www.zcraftstudios.com/llms-full.txt). Every page is available as Markdown by adding `.md` to its URL or sending `Accept: text/markdown`.

1. [Home](https://www.zcraftstudios.com/)
2. [Blog](https://www.zcraftstudios.com/blog)
3. PaperMC Config Files Explained: Global and Per-World

[ All posts](https://www.zcraftstudios.com/blog)

# PaperMC Config Files Explained: Global and Per-World

ZCraft StudiosOct 15, 2026Updated Oct 20, 2026

Understand where Paper stores configuration, how global and per-world files differ, and how to test settings safely without overwriting plugin data.

## In this guide

- [The directory structure](#the-directory-structure)
- [Which file should you edit?](#which-file-should-you-edit)
- [Global versus world-level behavior](#global-versus-world-level-behavior)
- [First step: create a clean backup](#first-step-create-a-clean-backup)
- [Editing YAML without syntax mistakes](#editing-yaml-without-syntax-mistakes)
- [Plugin configurations are separate](#plugin-configurations-are-separate)
- [Mistakes worth avoiding](#mistakes-worth-avoiding)
- [Verification checklist](#verification-checklist)
- [References and next steps](#references-and-next-steps)

## PaperMC Configuration Files Explained

Paper exposes configuration at different levels. A setting that belongs to one world may not be defined in the same place as a server-wide setting, and a plugin's own configuration is a separate system again.

This guide explains how to locate the right file and test configuration changes safely. The precise set of settings can change by Paper and Minecraft release.

## The directory structure

![PaperMC project logo, the server software covered by this configuration guide](https://assets.papermc.io/brand/papermc_logo.512.png)

_Official [PaperMC brand asset](https://docs.papermc.io/misc/assets/), used to identify the software being discussed. PaperMC does not endorse this article._

A typical contemporary Paper installation includes files such as:

```
server.properties
config/
  paper-global.yml
  paper-world-defaults.yml
plugins/
  ExamplePlugin/
    config.yml
world/
  paper-world.yml (location may vary with world and version)
```

Actual per-world configuration paths may differ based on namespaced dimensions. See [Paper's official configuration reference](https://docs.papermc.io/paper/reference/configuration/) for your release.

## Which file should you edit?

| File | Typical role |

| --- | --- |

| `server.properties` | Vanilla-compatible server settings |

| `paper-global.yml` | Settings that apply across the Paper server |

| `paper-world-defaults.yml` | Defaults for Paper-managed worlds |

| Per-world Paper settings | Overrides for an individual world or dimension |

| Plugin-specific YAML | Settings owned by that plugin |

Do not change every file when one setting appears wrong. First find the documented owner of that setting.

## Global versus world-level behavior

A global setting affects the server as a whole. A world default can apply broadly until a more specific world override replaces it. This model is useful when an SMP has resource worlds and event arenas requiring different behavior.

Before copying an override between worlds, verify that the feature is supported by that specific game release and that the plugin or dimension has no separate policy.

## First step: create a clean backup

Stop the server when required by the setting's documentation and preserve a copy of the current configuration. Make a note of the filename, original value and intended behavior.

A configuration backup is not the same as a full server backup. If a change might affect entity data, world generation or persistence, ensure you can restore the relevant world and database state as well.

## Editing YAML without syntax mistakes

YAML structure depends on indentation and data types. Avoid tabs where spaces are required, don't duplicate keys, and preserve the nesting from official examples. A syntactically valid file can still contain unsupported setting names.

If the console reports a parsing error, inspect the exact line and nearby indentation. Revert one change at a time rather than deleting entire directories.

## Plugin configurations are separate

A plugin may have its own data files and databases within or outside `plugins/`. Paper's global configuration does not replace them. If a plugin command behaves differently from vanilla behavior, inspect the plugin's documentation and events before changing Paper-wide settings.

See [Plugin Configuration Review](https://www.zcraftstudios.com/blog/minecraft-plugin-config-review-checklist).

## Mistakes worth avoiding

**Using settings from an old tutorial:** Paper may rename, remove or move options between versions.

**Editing while the server is saving:** Follow documented restart or reload instructions; avoid broad server reloads for plugin changes.

**Applying a world override globally:** An event-world policy might unintentionally affect the survival world.

**Assuming successful startup proves success:** Test the actual player behavior and persistence.

## Verification checklist

- \[ \] Current Paper and Java versions recorded
- \[ \] Target setting identified in official release documentation
- \[ \] Original file backed up
- \[ \] Only intended values modified
- \[ \] Startup log reviewed for errors
- \[ \] Behavior checked in the relevant world
- \[ \] Restart persistence confirmed

## References and next steps

- [Official PaperMC Configuration Documentation](https://docs.papermc.io/paper/reference/configuration/)
- [PaperMC server.properties Reference](https://docs.papermc.io/paper/reference/server-properties/)
- [Minecraft Server Files Explained](https://www.zcraftstudios.com/blog/minecraft-server-files-folders-explained)
- [Safe Plugin Updates](https://www.zcraftstudios.com/blog/minecraft-server-plugin-update-checklist)

**Bottom line:** Know which configuration layer owns each behavior, make minimal changes, and test in the exact world where the setting matters.

## Continue reading

- [Minecraft Server Files Explained: Properties and Logs](https://www.zcraftstudios.com/blog/minecraft-server-files-folders-explained)
- [LuckPerms Config, Placeholders and Verbose Guide](https://www.zcraftstudios.com/blog/luckperms-config-placeholders-verbose-guide)
- [EssentialsX Config Guide: Messages, Chat and Modules](https://www.zcraftstudios.com/blog/essentialsx-config-guide-messages-chat)
- [Minecraft Plugin Config Review: Avoid YAML Mistakes](https://www.zcraftstudios.com/blog/minecraft-plugin-config-review-checklist)

[ Previous guide How to Read a Spark Profiler Report for Minecraft](https://www.zcraftstudios.com/blog/how-to-read-spark-profiler-minecraft)[ Next guide Velocity Modern Forwarding Setup and Security Checklist](https://www.zcraftstudios.com/blog/velocity-modern-forwarding-setup-checklist)