Country rules
Use a blocklist for a few problem regions or an allowlist for a private community. Standard two-letter country codes keep the file readable.
A calmer way to manage where joins come from.
GeoRestrict gives Minecraft admins country, network and VPN rules without turning setup into a second job. Put one jar on your server or proxy, choose the access policy that fits your network, and let the local cache handle repeat lookups.
New here? Start with country rules and leave ASN/VPN checks alone until you know you need them. A small, understandable policy is much easier to support than a wall of copied settings.
Network rules
Block a hosting company or ISP by ASN without closing the door on an entire country.
VPN signals
Combine the provider's proxy flag with an editable ISP keyword list. You stay in control when a legitimate player gets caught.
Local cache
Recent results live in geo_cache.json, with atomic saves, a size cap and a 30-day default lifetime.
Useful notifications
Send block events to Discord, choose the fields you care about, and mask player IPs by default.
One friendly jar
Bukkit, Paper, Spigot, Purpur, Folia, BungeeCord, Waterfall and Velocity all use the same build.
What happens when someone joins?
A connection arrives
The platform adapter hands the address to GeoRestrict before the player is admitted.
The cache gets first look
A fresh local result avoids a network request entirely.
The gateway fills the gap
On a cache miss, the Worker or your own VPS gateway asks an upstream geolocation provider.
Rules run in order
Country, ASN and VPN rules are evaluated consistently. The first blocking rule wins.
The result is remembered
Valid lookup data goes into the bounded local cache for the next connection.
The player gets a clear answer
They join, or receive the message you wrote in config.yml.
Privacy, plainly: a cache miss sends the connecting IP to your configured gateway, and the gateway sends it to a lookup provider. GeoRestrict itself does not run player analytics. If that boundary matters to you, deploy the included Worker and VPS gateway under accounts you control.
A five-minute first setup
- Download
georestrict-2.0.0.jarfrom the GitHub releases page. - Place it in the server or proxy
plugins/folder and restart once. - Open
plugins/GeoRestrict/config.ymland chooseBLOCKLISTorALLOWLIST. - Run
/georestrict reload, then test with an address you know.
The installation guide covers every platform. If a real server behaves differently from the happy path, go straight to troubleshooting; it is written around symptoms, not guesswork.