asciiquarium: Install and Run the ASCII Aquarium
asciiquarium is an animated aquarium drawn in ASCII art that runs in your terminal. Fish swim past, sharks eat them, a whale spouts at the surface, and seaweed sways along the bottom. Kirk Baucom wrote the original Asciiquarium in Perl. The quickest way to run it on a Mac or Linux box is Homebrew:
brew install asciiquarium
asciiquarium
If you already live in npm, my package bundles Kirk's original Perl program behind one command:
npx asciiquarium
Below is how to install either one, the controls, how the original and my Node version differ, and fixes for the errors you're most likely to see.
What's in the Tank
Every creature and all the art are Kirk's. The simulation has 11 entity types:
- Fish — 18 variants, each facing left or right, with random colors, white eyes, and bubbles
- Sharks — hunt smaller fish, with a blood splat when they catch one
- Whales — a 7-frame animated water spout at the surface
- Sea monsters — fast, multi-frame, with new and classic designs
- Big fish — two large variants cruising through
- Ships — sailing along the water surface
- Bubbles — rising from fish and popping at the surface
- A castle, seaweed that waves and regrows, and a layered water surface
Leave it running for a few minutes and you'll see all of them.
How to Install asciiquarium
macOS and Linux: Homebrew
Homebrew packages the original as the asciiquarium formula (version 1.1). It ships prebuilt bottles for Apple Silicon Macs, Intel Macs on Sonoma, and x86_64 and arm64 Linux, so the same two commands work on both:
brew install asciiquarium
asciiquarium
Homebrew installs the formula's dependencies for you. This is the route I'd recommend if you just want fish.
Debian and Ubuntu
I'm not listing an apt command here, because Debian's package search returns no asciiquarium package. On Linux, Homebrew is the path I can vouch for. If your distro carries its own package, its package manager is the authority on the name.
npm: npx or a Global Install
Run it once without installing anything:
npx asciiquarium
Or install it globally so asciiquarium is always on your path:
npm install -g asciiquarium
asciiquarium
Know what the npm release needs before you reach for it. The current published version, 1.1.3, is a small bash wrapper around the original Perl program. That means it needs:
- Perl 5.40 or later (the Perl that ships with macOS is older, so
brew install perlfirst) - The
Term::Animationmodule from CPAN
It also declares macOS and Linux as its only supported platforms, so it won't install on native Windows. If Term::Animation is missing, the wrapper stops and tells you to run:
cpan Term::Animation
Controls and Options
| Key | Action |
|---|---|
q | Quit |
Ctrl+C | Quit |
r | Redraw the screen |
p | Pause and unpause |
| Option | What it does |
|---|---|
-c | Classic mode: the original fish and monster art |
Classic mode with npx looks like this:
npx asciiquarium -c
Original vs Node Version
There are three ways to get asciiquarium onto your screen, and they don't all run the same code.
| Original (Homebrew) | npm 1.1.3 | Node rewrite (beta) | |
|---|---|---|---|
| Runs on | Perl | Perl, via a bash wrapper | Node.js |
| You need | Homebrew | Perl 5.40+ and Term::Animation | Node.js 18+ |
| Platforms | macOS, Linux | macOS, Linux | macOS, Linux |
| How to run | brew install asciiquarium | npx asciiquarium | ASCIIQUARIUM_IMPL=node npx asciiquarium@beta |
Why I Rewrote It
The original depends on Perl and Term::Animation. Getting a CPAN module installed on a modern machine is exactly the kind of friction that stops someone who just wanted to watch fish. The whole point of npx asciiquarium was one command that works, and with Perl underneath, it only works if your Perl setup already does.
So I ported Kirk's program to Node.js. The rewrite is a close port rather than a reimagining, and it reuses his art, so it stays under his GPL license:
- All 11 entity types, including blood splats and the classic art behind
-c - A 10 FPS animation loop, matching the original Perl timing
- Z-depth sorting across a 0–22 range so entities layer correctly
- AABB collision detection for sharks eating fish and bubbles popping at the surface
- The original color masking: random body colors with white eyes
- Terminal resize handling, plus pause and redraw
It renders with the blessed library, which npm will install automatically, so the only thing you need is Node.js 18 or later.
Where the Node Version Stands
The rewrite is on npm as a beta (v2.0.0-beta.2). It is opt-in, so plain npx asciiquarium still runs the Perl version. To try the Node version, with no Perl needed:
ASCIIQUARIUM_IMPL=node npx asciiquarium@beta
The plan from here:
- v2.0.0 — finish visual regression testing against the Perl version, then make Node the default
- v3.0.0 — remove Perl entirely
What's left before v2.0.0 is automated screenshot comparison, benchmarking against the Perl version, and a real test suite. Manual side-by-side testing looks close, though details like the water surface still differ.
Troubleshooting
"install perl v5.40 or later" — The npm wrapper checks your Perl version before it starts. Upgrade Perl, or use the Homebrew formula instead.
"Term::Animation module not found" — Install the module the wrapper names:
cpan Term::Animation
npm won't install it on Windows — The package declares macOS and Linux only, and its launcher is a bash script. Use WSL.
You can't quit — Open a second terminal and kill it by name:
pkill -f asciiquarium
Check It Out
Find it on npm or contribute on GitHub. And if you just want to watch some fish swim, run npx asciiquarium and enjoy.