WhitelistCleanup - Automatic Whitelist Maintenance
Keep your Minecraft server whitelist tidy and up-to-date — automatically!
WhitelistCleanup is a lightweight utility plugin for Spigot and Paper servers that scans your whitelist on startup or command and removes players who haven't logged in within a configurable number of days. It also keeps a safe backup of all removed entries so you can restore them if needed.
✅ Features
Installation
Configuration
Commands
/whitelist cleanup - Manually trigger the whitelist cleanup
Requirements
Keep your Minecraft server whitelist tidy and up-to-date — automatically!
WhitelistCleanup is a lightweight utility plugin for Spigot and Paper servers that scans your whitelist on startup or command and removes players who haven't logged in within a configurable number of days. It also keeps a safe backup of all removed entries so you can restore them if needed.
✅ Features
- Automatic cleanup on server startup
- Manual cleanup via /whitelist cleanup command
- Removes players inactive for X days (configurable)
- Optionally remove players who have never joined
- Saves removed players to removals.json in the same format as whitelist.json
- Exclude specific players by username or UUID
- ️ Exclude players based on Vault permission groups (e.g., Admins, Moderators)
- ️ Optional broadcast to ops with summary after cleanup
- Highly configurable via config.yml
Installation
- Download the plugin JAR and drop it into your /plugins folder.
- Restart or reload your server.
- Configure the config.yml to your needs.
- Done!
Configuration
Spoiler: Config yml
inactive-days-before-removal: 90
remove-players-who-never-joined: true
broadcast-cleanup-to-ops: true
exclude-by-players-enabled: true
excluded-players:
- Notch
- 069a79f4-44e9-4726-a5be-fca90e38aaf5
exclude-by-vault-groups-enabled: true
excluded-vault-groups:
- admin
- moderator
remove-players-who-never-joined: true
broadcast-cleanup-to-ops: true
exclude-by-players-enabled: true
excluded-players:
- Notch
- 069a79f4-44e9-4726-a5be-fca90e38aaf5
exclude-by-vault-groups-enabled: true
excluded-vault-groups:
- admin
- moderator
Commands
/whitelist cleanup - Manually trigger the whitelist cleanup
Requirements
- Java 17+
- Spigot, Paper, or forked servers
- (Optional) Vault + a supported permissions plugin for rank-based exclusions
- whitelist.cleanup — Allows manual execution of the cleanup command
Quick facts
- Edition: Minecraft Java
- File type: .jar
- Minecraft version listed: 1.21
- How to install: Install the matching mod loader (Forge, Fabric or NeoForge) for your Minecraft version. → Download the .jar. → Put it in the .minecraft/mods folder and launch that loader profile.
- Where to get it: Opens on Spigot — not every file is mirrored on our own servers.
Install steps are the general flow for this file type — How to install Minecraft Java mods & modpacks walks through it step by step.
Auto Whitelist Cleanup - Remove inactive players from your whitelist! is a free Minecraft Java mod. Compatible with Minecraft 1.21. Downloaded 48 times (via Spigot). Download it and open it directly in the game.