XPenguins(1)

📦
version 3.2.4 · 5 versions
, in ubuntu stonking

🐧✨ XPenguins(1) — General Commands Manual ✨🐧

okay bestie, buckle UP, you're reading the xpenguins manual page and honestly? it's giving main character energy already 💅

🥺 NAME 🥺

xpenguins — cute little penguins that walk along the tops of your windows 🐧🫶

📜 SYNOPSIS 📜

xpenguins [-option ...]

🌈 DESCRIPTION 🌈

okay so XPenguins is literally a program that animates cute cartoons/animals in your root window. yes. that's the whole job. 🌸

By default it will be penguins — and the way that they just show up?? they drop in from the top of the screen, walk along the tops of your windows, up the side of your windows, levitate, skateboard, and do other similarly exciting things. no cap, they're iconic. 🐧🔥

⚠️ bestie, be careful when you move windows as the little guys squash easily. 💀 just a heads up. they're small. they're fragile. be gentle.

XPenguins is now themeable ✨, so it is easy to select something else to animate instead of penguins, or even (with a little artistic talent 🎨) define your own; see the THEMES section below. iykyk.

⚙️ OPTIONS ⚙️

In all the following cases a double dash can be replaced by a single dash. (yes fr fr, -- and - are interchangeable here, she's flexible 💅)

  • -a, --no-angels — Do not show any cherubim 👼 flying up to heaven when a toon gets squashed. rip little guy 😭
  • -b, --no-blood — Do not show any gory death sequences. 🩸🚫 keep it PG bestie
  • -c dir, --config-dir dir — Look for config files and themes in this directory. The default is usually /usr/share/xpenguins. 📁
  • -d display, --display display — Send the toons to the specified X display 🖥️. In the absence of this option, the display specified by the DISPLAY environment variable is used.
  • -h, --help — Print out a message describing the available options. 🆘
  • --defaults — Skip reading from ~/.xpenguinrc 🙈 no user config today, we're going factory-fresh
  • --nomenu — Do not show menu 📵
  • --nodoublebuffer — Do not use double buffering 🎞️
  • --hidemenu — Iconify menu at startup 🌫️
  • -i, --theme-info — Print out the auxiliary information about a theme and exit. Use the -t option to select the theme to describe. 🔍
  • --random-theme — Start with a random theme. 🎲 slay but chaotic
  • -l, --list-themes — List the available themes, one on each line, and exit. 📝
  • -m delay, --delay delay — Set the delay between each frame in milliseconds ⏱️. The default is defined by the theme.
  • -n number, --penguins number — The number of toons to start, up to a maximum of 512. The default is defined by the theme. 🐧🐧🐧
  • -p, --ignorepopups — Toons fall through `popup' windows (those with the save-under attribute set), such as tooltips. Note that this also includes the KDE panel. 🪟💨
  • -r, --rectwin — Toons regard all windows as rectangular. This option results in faster calculation of window positions, but if you use one of those fancy new window managers with shaped windows then your toons might sometimes look like they're walking on thin air. 🌬️ highkey cursed but fast
  • -s, --squish — Enable the penguins to be squished using any of the mouse buttons 🖱️. Note that this disables any existing function of the mouse buttons on the root window. 💥
  • --lift number — Lift penguins window number pixels, e.g. to keep above a panel. 🎈
  • -t theme, --theme theme — Use the named theme. The default is Penguins. If the theme has spaces in its name then you can use underscores instead, or alternatively just put the name in double quotes. This option can be called multiple times to run several themes simultaneously. 👯‍♀️👯‍♀️
  • -q, --quiet — Suppress the exit message when an interrupt is received. 🤫
  • -v, --version — Print out the current version number and quit. 🔢
  • --all — Load all available themes and run them simultaneously. 🌈 the whole squad, periodt
  • --id window — Send toons to the window with this ID, instead of the root window or whichever window is appropriate for the current desktop environment. Note that the ID of X clients reported by xwininfo is rarely that of the foremost visible window that should be used here. 🪟⚠️
  • --nice loadaverage1 loadaverage2 — Start killing toons when the 1-min averaged system load exceeds loadaverage1; when it exceeds loadaverage2 kill them all. The toons will reappear when the load average comes down. The load is checked every 5 seconds by looking in /proc/loadavg, so this option only works under unices that implement this particular pseudo file (probably just Linux). When there are no toons on the screen, XPenguins uses only a minuscule amount of CPU time — it just wakes up every 5 seconds to recheck the load. 😴📉
  • --changelog — Show ChangeLog 📃
  • --selfrep — Put source in the form of a gzipped tar file on stdout. 🗜️

to be continued, bestie… 💜

🔮 THEMES 🔮

Okay bestie, this is the part where you get to make it yours. 🎨

The system themes usually live in /usr/share/xpenguins/themes, and you can totally add to those or override them with your own stuff in $HOME/.xpenguins/themes. Every theme gets its own little subdirectory, and to be valid that subdirectory must contain a file called config. The theme's name comes from the directory name — but because so many install scripts absolutely choke on directory names with spaces in them, every space in a theme name is written as an underscore in the directory name instead. And heads up: any directory name that does contain spaces is just straight up inaccessible by xpenguins. Not a vibe. 🚫

On top of the config file, the theme directory also holds the toon images that make up the theme, in the form of xpm image files. Also, there should be an about file giving info on who created the theme, what license it's under, and various other things. That file is mostly for xpenguins_applet, a GNOME applet that lets you pick different themes at the click of a button. 🫶

The config file has a pretty straightforward format, ngl. You can either read this rather terse description, or just go peek at the config file for the default Penguins theme, which is usually installed at /usr/share/xpenguins/themes/Penguins/config and is reasonably well commented. Lowkey the best move. 💅

First, some terminology, because we're gonna need it. Say you've got a Farmyard theme with cows and sheep. The cows and sheep are types of toon, while all the various things they get up to (walking, mooing, etc.) are called activities. Each activity has its own xpm image file, and the frames of the animation are laid out horizontally in it. Some activities (notably walking) use different images depending on which direction the toon is moving — in that case, the frames for the two directions are laid out one above the other in the image. 🐄🐑

As in shell scripts, comments start with the # character and hide the rest of the line. The format is entirely free, except there's an arbitrary limit: a line can't be longer than 512 characters. Spaces, tabs and newlines all count equally as white space. Data comes in as a sequence of key-value pairs, all separated by white space. Neither the keys nor the values are case sensitive — except when the value is a filename, so watch out for that one. 👀

Here are the keys that are understood:

  • delay delay — sets the recommended delay between frames, in milliseconds.
  • toon toon — starts defining a new toon called toon. If there's only one type of toon in the theme, you can leave this key out entirely.
  • number number — sets the default number of toons of the current type to start with.
  • define activity — starts defining an activity for the current toon. The activities understood right now are walker, faller, tumbler, climber, floater, runner, explosion, squashed, zapped, splatted, angel, exit and action?, where ? is a number between 0 and 6. Once you've seen the program in action you should be able to guess which is which. 😉 A valid theme must contain at least walkers and fallers. Also, you can define a default activity (with define default) — any properties (like width and speed) that you set there get adopted by the activities defined from then on, as long as those activities don't explicitly define those properties themselves.

Once an activity has been declared with define, these properties can be assigned:

  • pixmap xpmfile — the file containing the image data for the activity. Note: you may not set a default pixmap.
  • width width — the width of each frame of the animation, in pixels.
  • height height — the height of each frame of the animation, in pixels.
  • frames frames — the number of frames in the animation.
  • directions directions — the number of directions for the activity (can be 1 or 2).
  • speed speed — the initial speed of the toon when engaged in this activity, in pixels per frame.
  • acceleration acceleration — the rate at which the speed increases, in pixels per frame squared. Not every activity actually utilises this property.
  • terminal_velocity terminal_velocity — the maximum speed in pixels per frame; again, not utilised by all activities.
  • loop loop — only understood by the actions; it says how many times to repeat the action. If it's negative, then the probability of stopping the action every time the action is complete is -1/loop.

A few notes on the various activities, bestie. If you design a new theme, feel free to make the splatted, squashed, zapped and exit animations as gory and bloody as you like — but please keep the explosion activity nice and tame, so that those of a nervous disposition can employ the --no-blood option, which replaces all these violent deaths with a tasteful explosion that wouldn't offend your grandmother. 🌸

Xpm image files are a factor of two smaller if you can limit the number of colours in the image such that only one character needs to be used to represent each colour — and this also makes XPenguins start up much more rapidly. Rarely are more than 64 colours required. Slay. ✨

So that's about it for the config file. Now for the about file, which is very simple. Again, comments are initialised by a #. An entry is a key at the start of a line, followed by the corresponding value, which is read up to the next newline. These keys are understood, although none of them are compulsory:

  • artist — used to list the artist(s) who created the original images.
  • maintainer — the person who compiled the images into an XPenguins theme. It's useful if an email address can be provided too.
  • date — the date when the theme was last modified. My preferred format is day of the month, name of the month in english, full year. For example: 24 April 2001.
  • icon — the name of an image file that can be used as an icon for the theme; XPM and PNG are suitable formats.
  • license — the name of the license under which the theme is distributed (e.g. GPL).
  • copyright — the year and holder of the copyright.
  • comment — any other essential information, such as the theme's web site, as brief as possible.
Please test any about files you create by looking at how the information is displayed by the xpenguins_applet program. 💖

👑 AUTHOR 👑

Robin Hogan <R.J.Hogan@reading.ac.uk>.

🌟 CREDITS 🌟

Inspiration provided by Rick Jansen <rick@sara.nl> in the form of the classic xsnow. Most penguin images were taken from Pingus, a free lemmings clone that can be found at <http://pingus.seul.org/>; these images were designed by Joel Fauche <joel.fauche@wanadoo.fr> and Craig Timpany <timpany@es.co.nz>. Additional images in version 2 by Rob Gietema <tycoon@planetdescent.com> and Robin Hogan.

📝 NOTES 📝

XPenguins can load an X server and/or network (although the CPU time used is small), and if a large number of penguins are spawned then they may begin to flicker, depending on the speed of the X server.

The xpenguins homepage is located at:

💀 BUGS 💀

If there are icons drawn on the root window, then the toons will erase them when they walk over them — although an expose event will be sent to the window every second to redraw them. 😭

Since version 3.0, xpenguins uses, if possible, a transparent, click-through window to draw its toons. The --squish flag does not function in this mode.

The behaviour of the menu is not well defined when the same theme name is used more than once.

🗂️ FILES 🗂️

User defined themes: $HOME/.xpenguins/themes/*
System themes: /usr/share/xpenguins/themes/*
Remember used flags: $HOME/.xpenguinsrc
/proc/loadavg

🦋 SEE ALSO 🦋

xsnow(6), xroach(1), xwininfo(1), pingus(6)

And that's the whole page, bestie!! 🎀 This was XPenguins 3.2.4, dated May 2026, and no cap it's iconic. go forth and cover your root window in penguins 🐧💜 ✨

📦 where this page comes from