awww-img(1)

📦
version 0.12.1 · 4 versions
, in alpine 3.24

🌸 awww-img(1) — General Commands Manual, but make it cute 🌸

okay so this is awww-img, bestie, and it's here to serve you wallpapers ✨ (the manual page header says awww-img(1) and "General Commands Manual", so like, now you know the whole vibe going in 💅)

✨ SYNOPSIS ✨

awww img [OPTIONS] <path/to/img>

that's it. that's the whole entry point. iconic.

🎀 OPTIONS 🎀

  • -a,--all — send this command to all active awww-daemon namespaces. every single one. no output left behind 💖
  • -f, --filter <FILTER> — the filter used when scaling images 🦋

the available options are literally:

Nearest | Bilinear | CatmullRom | Mitchell | Lanczos3

these are offered by the fast_image_resize crate (https://docs.rs/fast_image_resize/2.5.0/fast_image_resize/). Nearest is what I recommend for pixel art stuff, and ONLY for pixel art stuff — it's also the fastest filter, no cap.

for non pixel art stuff, I'd usually recommend one of the last three, though some experimentation will be necessary to see which one you like best 🧚

note you can also pass the flag --no-resize, explained below. in which case the --filter flag will have no effect. (yes, it just sits there. unemployed. 💀)

default is Lanczos3 👑

  • -n, --namespace <namespace> — which wayland namespace to send this command to.

you can specify this option multiple times to send commands to multiple namespaces at once: awww img -n <namespace1> -n <namespace 2>. multitasking queen 🫶

this affects the name of the awww-daemon socket we will use to communicate with. specifically, our socket name is ${WAYLAND_DISPLAY}-awww-daemon.<specified namespace>.socket.

some compositors can have several different wallpapers per output. this allows you to differentiate between them. most users will probably not have to set anything in this option. iykyk 💅

  • --no-resize — do not resize the image. equivalent to --resize no.

if this is set, the image won't be resized, and will be centralized in the middle of the screen instead. if it's smaller than the screen's size, it will be padded with the value of --fill_color, below. little image, big screen, cozy vibes 🎀

  • --resize <RESIZE> — whether to resize the image, and the method by which to resize it.

possible values:

  • no: do not resize the image
  • crop: resize the image to fill the whole screen, cropping out parts that don't fit
  • fit: resize the image to fit inside the screen, preserving the original aspect ratio
  • stretch: resize the image to fit inside the screen, without preserving the original aspect ratio

default is crop.

  • --crop-gravity <CROP_GRAVITY> — specify which portion of the image to anchor when cropping. only used when --resize crop is specified. (so if you didn't pick crop, this whole thing is lowkey just vibing in the void 🙈)

possible values:

  • center: crops top and bottom of image equally, and crops left and right of image equally
  • top-left: crops bottom and right of image
  • top: crops bottom of image, and crops left and right of image equally
  • top-right: crops bottom and left of image
  • left: crops right of image, and crops top and bottom of image equally
  • right: crops left of image, and crops top and bottom of image equally
  • bottom-left: crops top and right of image
  • bottom: crops top of image, and crops left and right of image equally
  • bottom-right: crops top and left of image

default is center.

  • --fill-color <RRGGBB> — which color to fill the padding with when not resizing. hex moment 💜

default is 000000.

  • -o, --outputs — comma separated list of outputs to display the image at. use awww query to know which outputs are currently being used. very "check the guest list before the party" of you ✨

if it isn't set, the image is displayed on all outputs.

  • -t, --transition-type <TRANSITION_TYPE> — [Environment Variable $AWWW_TRANSITION]

sets the type of transition. default is simple, that fades into the new image.

possible transitions are:

none, simple, fade, left, right, top, bottom, wipe, wave, grow, center, any, outer, random

  • none will complete the transition instantly. blink and you'll miss it 💀
  • fade is like simple but uses bezier curves while fading the image, it's a more polished looking version of simple with less artifacts ✨
  • the left, right, top and bottom options make the transition happen from that position to its opposite in the screen.
  • wipe is similar to left but allows you to specify the angle for transition with the --transition-angle flag.
  • wave is similar to wipe but the sweeping line is wavy 🦋 you can control the "waviness" with --transition-wave.
  • grow causes a growing circle to transition across the screen and allows changing the circle's center position with the --transition-pos flag.
  • center is an alias to grow with position set to center of screen.
  • any is an alias to grow with position set to a random point on screen.
  • outer is the same as grow but the circle shrinks instead of growing. shrinking circle era 🌸
  • finally, random will select a transition effect at random 🎲
  • --transition-step <0-255> — [Environment Variable $AWWW_TRANSITION_STEP]

how fast the transition approaches the new image.

the transition logic works by adding or subtracting from the current rgb values until the old image transforms in the new one. this controls by how much we add or subtract.

for example, if pixel A is 000010, and we need it to transition to pixel B, which is 000020, if transition-step is 2, then in one frame pixel A will turn to 000012, in the next frame to 000014, and so on. math ate, fr fr 🔥

larger values will make the transition faster, but more abrupt. a value of 255 will always switch to the new image immediately.

default is 90. if transition-type is simple, default is 2.

  • --transition-duration <seconds (can have decimals)> — [Environment Variable $AWWW_TRANSITION_DURATION]

how long the transition takes to complete, in seconds. ⏳

note this doesn't work with the simple transition. (simple said "i don't do durations" 😭)

default is 3.

  • --transition-fps <frames per second (max 255)> — [Environment Variable: $AWWW_TRANSITION_FPS]

frame rate for the transition effect.

note there is no point in setting this to a value smaller than what your monitor supports. like, why would you 💀

also note this is different from the transition-step. that one controls by how much we approach the new image every frame. two different things, bestie, don't mix them up 💅

default is 30.

  • --transition-angle <angle, in degrees (parsed as a float)> — [Environment Variable: AWWW_TRANSITION_ANGLE]

this is used for the wipe and wave transitions. it controls the angle of the wipe. 🌀

note that the angle is in degrees, where '0' is right to left and '90' is top to bottom, and '270' bottom to top.

default is 45.

  • --transition-pos <x,y> — [Environment Variable: AWWW_TRANSITION_POS]

this is only used for the grow and outer transitions. it controls the center of circle (default is center). ⭕

position values can be given in both percentage values and pixel values: float values are interpreted as percentages and integer values as pixel values. eg.: 0.5,0.5 means 50% of the screen width and 50% of the screen height, while 200,400 means 200 pixels from the left and 400 pixels from the bottom.

the value can also be an alias which will set the position accordingly:

center, top, left, right, bottom, top-left, top-right, bottom-left, bottom-right

default is center.

  • --invert-y <bool> — [Environment Variable: AWWW_INVERT_Y]

inverts the y position sent in transition_pos flag. flip it, reverse it, that's the whole thing 🙃

  • --transition-bezier <f1,f2,f3,f4 (all floats)> — [Environment Variable: AWWW_TRANSITION_BEZIER]

bezier curve to use for the transition animation. https://cubic-bezier.com is a good website to get these values from. 🎀

eg: 0.0,0.0,1.0,1.0 for linear animation

default is .54,0,.34,.99

  • --transition-wave <width,height (both floats)> — [Environment Variable: AWWW_TRANSITION_WAVE]

currently only used for wave transition to control the width and height of each wave. 🌊

default is : 20,20

  • -h, --help — print help (see a summary with '-h'). the classic. the icon. the "help me help you" 🫶

💖 DESCRIPTION 💖

sends an image (or animated gif) for the daemon to display. you can also use - to read from stdin instead. yes, -. literally just a dash. piping queen behavior 👑

🦋 ABOUT THE CACHE 🦋

the images sent will be cached at $XDG_CACHE_HOME/awww or $HOME/.cache/awww if $XDG_CACHE_HOME does not exist. in this directory, we create another directory corresponding to awww's current version number. in there, we have files that cache the last displayed image and animation frames for animated wallpapers. there is one file per output. very organized of her 💅

as mentioned, the cache will keep preprocessed versions of animations. so, if you load a large gif, you would only have to pay the price for its processing the first time. the "pay once, enjoy forever" model ✨ but — if you constantly load large gifs, this could cause the cache to get very big 😭 you can simply run awww clean-cache if this happens. problem solved, bestie.

🌈 SEE ALSO 🌈

awww-clear-cache(1) awww-daemon(1) awww-query(1)

ok that's the whole page, go touch some wallpaper 🫶

and finally, the little sign-off the page came with: this one's dated 2026-05-07 and it's the awww-img(1) page, so yeah — that's the whole manual, periodt 💜🎀✨

📦 where this page comes from