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 Worker fills the gap
It checks its 24-hour cache, tries the configured providers, then uses the VPS's local database if they are all unavailable.
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 plugin-cache miss sends the connecting IP to your Worker. A Worker-cache miss goes to the first provider that answers; if none do, the protected VPS reads local Country and ASN files instead. GeoRestrict does not run player analytics. Local fallback data is supplied by DB-IP Lite under CC BY 4.0.
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.