Open-source project
hydro-dev/Hydro avatar
hydro-dev/Hydro

Hydro (hydro-dev/Hydro): a self-hosted online judge with a plugin core and stateless judges

Hydro: a next-generation, high-performance online judge platform (a.k.a. vj5).

7,237 stars496 forksTypeScriptAGPL-3.0

At a glance

What is it?
Hydro is an AGPL-3.0 online-judge platform written in TypeScript for schools, universities and contest organisers. It ships a one-line installer, a backup/restore CLI and a judge layer that can be scaled by adding nodes.
Who is it for?
Adopt Hydro if you run programming contests or coursework for a class, a school or a regional contest and you are willing to keep a Linux host, MongoDB and a judge running. Skip it if you only need to grade a handful of submissions a week, or if you cannot accept AGPL-3.0 obligations on a modified public deployment.
Can I use it commercially?
Yes, with strict conditions. AGPL-3.0 is a network copyleft licence: if people use a modified version over a network, for example as a hosted service, you must offer them its source code under the same licence.
Is it still maintained?
Yes. The repository last received commits 4 days ago.
What is it written in?
Mainly TypeScript, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • hydro-dev/Hydro7,237 ★ · +215
Star history
Repository2026-09-232026-11-15
hydro-dev/Hydro7k7.2k

215 Stars in the last 53 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

What Hydro solves, and for whom

Running an online judge is mostly not about judging. It is about accounts, contests, scoreboards, problem imports, permissions and backups, and those are the parts most schools end up building themselves on top of a minimal sandbox. Hydro targets that gap. The repository describes it as a high-performance informatics online-judge system, installable, cross-platform, multi-purpose and extensible, with a problem bank. The stated audience is teachers and contest organisers, including those who are not comfortable with Linux: the README points to a hosted instance at hydro.ac for people who would rather not operate a server.

The feature list reads like a checklist of organisational problems rather than judging problems. Multiple spaces on one installation let a school separate classes, grades or departments, with data isolated by default except for users, and separate administrators per space. Permissions can be granted per contest or homework, or to a group standing in for a class. Problems can be copied across spaces while occupying storage once. Contest formats include ACM/ICPC with scoreboard freeze, OI, IOI, the Ledao format, and homework. If your unit already has a judge and only needs a sandbox, most of this is overhead.

The plugin system and what hot-swapping actually buys you

Hydro is built as a workspace of packages, framework modules, plugins and modules, and the README frames the plugin system as the reason the system stays upgradeable after you change it. That is the real claim: modify behaviour through a plugin rather than by patching core files, so a later upgrade does not collide with your edits. The README states that all historical versions can be upgraded smoothly to the latest.

The cost is a plugin API you have to learn. The README sends readers to the plugins and TypeScript development chapters of the documentation, which is where the actual surface lives. The repository layout supports the description: examples/plugins/ exists as a starting point, and the workspace globs in package.json include packages/*, framework/*, plugins/*, modules/* and examples/plugins/*. A team that wants a small change to a scoreboard or a submission view is expected to write a plugin, not a patch.

The release notes show the same pattern at the top of the project. Version 5.0.0-beta.12 lists breaking API changes: an upgrade to React 19, an upgrade to MongoDB Driver 7, removal of blueprint.js, and replacement of saslprep with @mongodb-js/saslprep. Plugin authors carry that migration work. The plugin system protects you from core edits, not from upstream dependency moves.

Stateless nodes, judge queues and data caching

The scaling story is the most concrete architectural claim in the README. Hydro itself is described as stateless, so service nodes can be added or removed without disrupting the system, and the judge queue is balanced automatically across all online judges. With an elastic scaling group attached, judges can be added or removed based on server load.

The interesting part is test data. The README says Hydro manages the test-data cache across servers and pulls data on demand, so a judge is usable as soon as it comes online, without manual synchronisation. Anyone who has copied gigabytes of test data to a new worker by hand knows what this replaces. The trade-off is that the judge needs network access to the data source, and the first run of a problem on a fresh node pays for the pull.

The judge layer is also where the language story lives. The README states that language settings are not hardcoded but read from configuration: if you can write the compile and run commands for a language, Hydro can judge it. Adding a niche language is a config exercise, not a code change, provided the runtime exists on the judge host.

Installing Hydro and creating the first administrator

The README gives a one-line install for Linux. It recommends Debian 12, states compatibility with mainstream distributions, and notes support for arm64 devices such as Raspberry Pi. The command sets LANG=zh, so the installer runs in Chinese; the hosted documentation at hydro.js.org is the Chinese reference, with README-EN.md for English.

bash
LANG=zh . <(curl https://hydro.ac/setup.sh)

Run it in a console on the target machine. After installation, register the first user: the README says that account automatically receives super-administrator rights. That is the first thing to do, because there is no separate bootstrap step described.

Backups are a CLI concern rather than a database chore. The README gives two commands, one to back up all system data and one to restore from a file, and states the process needs no manual intervention.

bash
hydrooj backup
hydrooj restore 文件名

For problem data, the README describes importing common formats: Hydro's own zip format, FPS (xml) files exported from HUSTOJ, and archives exported from QDUOJ. Free problem banks are downloadable from the project's problem archive, including a zip for a programming-introduction bank and one for a competition-programming book, each with import instructions inside the archive. Remote problem sources listed in the README include UOJ, Codeforces, Luogu (which the README says requires purchasing authorisation from Luogu), HDUOJ, CSGOJ, SPOJ, POJ, YACS and HUSTOJ, with the caveat that HUSTOJ-derived systems usually need manual adaptation because their UIs differ.

Where Hydro is the wrong tool, and what to use instead

Hydro is a platform, and platforms carry operational weight. You need a Linux host, MongoDB, a judge process and somewhere to keep test data. For a single instructor grading thirty submissions a week, that is a poor trade; a hosted instance or a simpler judge will cost less attention. The README itself acknowledges the audience that does not want to run anything, which is why hydro.ac exists.

There is also a version caveat. The most recent release listed is 5.0.0-beta.0 from 2025-04-13, while the changelog in the README documents a long series of 5.0.0-beta.x entries and later 5.0.4 and 5.0.5 entries. Read that as a project moving quickly on master with releases lagging the changelog. If you need a tagged, stable artefact rather than a tracked branch, verify what you are actually deploying. The last push to the repository was on 2026-10-31, so the code is current even though the release list is not.

A real alternative is DOMjudge, the contest system used at ICPC regional and world finals. The difference in approach is instructive: DOMjudge is built around a contest, with a jury interface and a scoreboard as the centre of the product. Hydro is built around a persistent multi-tenant installation where problems, spaces, users and permissions outlive any single contest, and where a plugin system is expected to absorb your customisations. If your unit runs one contest a year and nothing else, DOMjudge's narrower model is less to operate. If you are running a semester of homework, several classes and an internal selection contest on the same accounts, Hydro's model is the one that fits.

Licence and the cost of staying current

Hydro is licensed under AGPL-3.0. The practical consequence, stated plainly and without legal advice: if you modify Hydro and let users interact with it over a network, the licence's network clause is the part your legal team needs to read, because it is stricter than a plain GPL in that scenario. Running an unmodified copy for your own students is the ordinary case and not the one that usually raises questions. The repository also carries a CLA.md and a CONTRIBUTING.md, which matter if you intend to send changes upstream rather than keep them.

Upgrade cost is the other recurring expense. The README claims smooth upgrades across all historical versions, and the changelog supports a project that ships fixes often. The counterweight is the breaking-change section in 5.0.0-beta.12: React 19, MongoDB Driver 7, removed built-in libraries. Those land on plugin authors. Budget for reading release notes before every upgrade, and keep the backup command in your routine.

Editorial conclusion

Adopt Hydro if you run programming contests or coursework for a class, a school or a regional contest and you are willing to keep a Linux host, MongoDB and a judge running. Skip it if you only need to grade a handful of submissions a week, or if you cannot accept AGPL-3.0 obligations on a modified public deployment. Before committing, verify on your own hardware that the languages you teach compile under the default judge image, and check the licence text against how you intend to distribute your changes.

Frequently asked questions

How do I install Hydro on Linux?

The README gives a single command that pipes the setup script from hydro.ac into your shell, run with LANG=zh. It recommends Debian 12 and states compatibility with mainstream Linux distributions and arm64 devices such as Raspberry Pi. After installation, the first registered user automatically becomes super administrator.

Does Hydro support Windows or macOS for the server?

The README describes Linux distribution support and arm64 devices, and states Hydro runs on Raspberry Pi and Apple M1/M2 hardware.

How do I back up and restore a Hydro installation?

The README gives hydrooj backup to back up all system data and hydrooj restore 文件名 to import a backup, and states the process requires no manual intervention. A later changelog entry mentions restic-based incremental backup support.

Can Hydro import problems from other online judges?

Yes. The README lists Hydro's own zip format, HUSTOJ FPS (xml) exports and QDUOJ archives for file import, plus remote sources including UOJ, Codeforces, Luogu, HDUOJ, CSGOJ, SPOJ, POJ, YACS and HUSTOJ. It notes that Luogu requires purchasing authorisation and that HUSTOJ-derived systems usually need manual adaptation.

What contest formats does Hydro support?

The README lists ACM/ICPC with scoreboard freeze, OI, IOI, the Ledao format, and homework. Under IOI and OI it also describes post-contest correction submissions and flexible-time participation within a set window.

Official sources

  1. hydro-dev/Hydro on GitHub
  2. License: AGPL-3.0
  3. Project website
  4. README
  5. Releases
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/hydro-dev-hydro.svg)](https://hysenlabs.com/projects/hydro-dev-hydro)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/hydro-dev-hydro.svg)](https://hysenlabs.com/projects/hydro-dev-hydro)

Was this useful?