Welcome to the Hangar Open Beta. Please report any issue you encounter on GitHub!
Avatar for A248

Obedience is liberating

Report LibertyBans?

LibertyBans is the sparkling, extraordinary and brilliant weapon of punishment administration.

https://raw.githubusercontent.com/A248/LibertyBans/fb285f13b89285c985ac11dae9d440a3f1a1e953/.github/banner.png https://img.shields.io/badge/-Home_Page-blueviolet.svg?logo=StarTrek&style=for-the-badge&logoColor=white https://img.shields.io/badge/-Documentation-blue.svg?logo=Wikipedia&style=for-the-badge&logoColor=black https://img.shields.io/badge/-Discord-5865F2.svg?logo=discord&style=for-the-badge&logoColor=white https://www.gnu.org/graphics/agplv3-155x51.png


The existing punishment plugins all have their flaws. Either they are plagued with bugs and concurrency issues, or they are closed-source and pay-walled, or both.

None of the existing punishment plugins have a test framework which can compare to LibertyBans' extensive automated testing. This means that many bugs are caught automatically and never make it into stable releases.

LibertyBans features a full-suite of punishment-related tools. It is a general-purpose punishment plugin with a focus on effective design, quality of experience, and unbeatable code quality.

LibertyBans is the best designed plugin to punish players. It can efficiently scale to large networks and operate on single servers with minimal resources.


  • Add and remove punishments:
    • /ban, /ipban, /unban, /unbanip - bans or unbans a player or IP address
    • /mute, /ipmute, /unmute, /unmuteip - mutes or unmutes a player or IP address
    • /warn, /ipwarn, /unwarn, /unwarnip - warns or unwarns a player or IP address
    • /kick, /ipkick - kicks a player or IP address
  • Temporary versions of bans, mutes, and warns
  • All player data is stored using UUIDs.
  • List punishments:
    • /banlist - shows all bans
    • /mutelist - shows all mutes
    • /history - shows all punishments for a player
    • /warns - shows all warns for a player
    • /blame - shows all the punishments a staff member has enacted
  • Multiple means to block alt accounts:
    • Automatic enforcement to block alt accounts. By default, when using IP-bans, alts are automatically banned from joining if the main account is banned. This behavior is configurable, and you can even increase the strictness of alt-checking.
    • Manual /alts command - shows suspected alt accounts for a player.
    • Alts notification on join - tells staff members when a player whose suspected alt is banned or muted.
    • Connection limit per IP address.
  • Exemption. For example, trainees cannot ban admins; admins cannot ban owners.
  • Layouts & punishment templates. For example, the first mute for swearing lasts 10 days, the next is for 30 days, and the third mute is permanent. Supports calculating the reason, time, and even punishment type.
  • Options and behavior are fully configurable. You can even tweak your connection pool and statement cache settings to fine-tune performance.
  • The plugin is carefully designed to be performant and lightweight. It uses an efficient SQL schema which stores the raw bytes of UUIDs and IP addresses, rather than storing them as strings/text.
  • Full multi-proxy and multi-instance support. You can place LibertyBans on the proxy if you use a single proxy, or on multiple backend servers.

Commands, Permissions, Configuration

Everything is explained on the wiki: Wiki Link

The wiki has a lot of information, including about the configuration.

  • The configuration files are extensively commented and the options are explained in detail.
  • If you update LibertyBans, your old configuration will be updated automatically if there are new options.



  • /libertybans usage

to show all commands. When typing this into your console, leave off the slash.

When creating temporary punishments, the same command is used for permanent punishments. Simply add the time after the username:

  • /ban Player1 30d This is a temporary ban

For an extended guide, see this wiki page.


  • Effective and lightweight. No complicated installation and avoids unnecessary features.
  • Option to use local file-based database (HyperSQL), or remote database (MariaDB, MySQL, PostgreSQL).
  • Enhanced database-oriented performance emphasising calculations in SQL. Low memory usage because punishments are stored almost completely in the database. Data is stored in minimal form as raw bytes instead of strings.
  • Best practices for asynchronous calculations are followed. The performance cost of context switching is understood and avoided; the plugin does not blindly fire async tasks.
  • Designed for high availability and concurrency. Minimal locking is employed while keeping state consistent; this is mostly realized through the fact that most plugin state is maintained in the database itself.
  • Well-structured API providing a framework for other plugins to work with.


  • Java 17

Supported platforms:

  • Bukkit / Spigot / Paper (+Folia)
  • BungeeCord / Waterfall
  • Sponge
  • Velocity

Compatibility with Geyser/Floodgate usernames.


LibertyBans will work out-of-the-box for most users.

  • When using a single proxy, it is recommended, but not required, to install LibertyBans on the proxy itself.
  • LibertyBans can also be installed on the backend servers if you are willing to configure multi-instance synchronization.

For installing on the backend servers and synchronizing punishments, see the wiki for additional information.

External Connections

When the plugin first starts, it downloads its internal dependencies. This is normal, and can take a couple of seconds the first time. Afterward, the plugin should start faster. The method used to download dependencies is just as secure as if the dependencies were shaded – the expected hashes of the dependencies are hard-coded, so if the downloaded dependency's hash differs, it is not saved to the filesystem.

Fun Facts

  • LibertyBans was first released on 4 July 2020, Independence Day in the United States of America.
  • Updates are typically released on or shortly after major holidays or days of significance:
    • 0.8.0 was released 11 September 2021.
    • 0.8.1 was released 3 days after Thanksgiving.
    • 1.0.0 was released 2 days after New Year's.
    • 1.0.1 was released 2 days after Valentine's Day.
    • 1.0.2 was released 4 July 2022, exactly 2 years after the first release.
    • 1.0.4 was released 11 September 2022.
    • 1.1.0-M1 was released on Christmas Day, 2022.
    • 1.1.0-M2 was released 2 days after St. Patrick's Day.
    • 1.1.0-M3 was released 5 days after July 4.
    • 1.1.0-RC1 was released 11 September 2023.
    • 1.1.0-RC2 was released 29 February 2024.

Development Builds


Reporting Bugs

Please use Github issues: https://github.com/A248/LibertyBans/issues


CategoryAdmin Tools
Published onMarch 19, 2023


Avatar for A248