nekowall 1.0.0

Random anime wallpaper changer for Windows, powered by Nekosia API

NEKOWALL

  ███╗   ██╗███████╗██╗  ██╗ ██████╗ ██╗    ██╗ █████╗ ██╗     ██╗
  ████╗  ██║██╔════╝██║ ██╔╝██╔═══██╗██║    ██║██╔══██╗██║     ██║
  ██╔██╗ ██║█████╗  █████╔╝ ██║   ██║██║ █╗ ██║███████║██║     ██║
  ██║╚██╗██║██╔══╝  ██╔═██╗ ██║   ██║██║███╗██║██╔══██║██║     ██║
  ██║ ╚████║███████╗██║  ██╗╚██████╔╝╚███╔███╔╝██║  ██║███████╗███████╗
  ╚═╝  ╚═══╝╚══════╝╚═╝  ╚═╝ ╚═════╝  ╚══╝╚══╝ ╚═╝  ╚═╝╚══════╝╚══════╝

Random anime wallpaper changer for Windows, powered by the Nekosia API.

Picks a random image from a random category and sets it as your desktop wallpaper instantly. No external dependencies — pure Python 3.8+ standard library.

---

Installation

pip install nekowall

That's it. The nekowall command is available immediately in any terminal.

---

Usage

nekowall                        random category, random image
nekowall -c catgirl             force a specific category
nekowall -c maid --keep         keep the downloaded image file permanently
nekowall --list                 show all available categories with commands
nekowall --no-banner            skip the ASCII banner
nekowall -h                     full help

Examples

# Set a random wallpaper from a random category
nekowall

# Always pick from the foxgirl category
nekowall -c foxgirl

# Pick a random one but save the image to keep it
nekowall --keep

# See every available category and the exact command to use it
nekowall --list

---

How it works

1. Loads categories — starts with 80+ hardcoded categories from the Nekosia documentation and the Booru tag list, then fetches live tags from the API and merges any new ones with count >= 15.
2. Picks a random category (or uses the one you specified with -c).
3. Fetches a random image from GET /api/v1/images/{category}.
4. Downloads the image to %TEMP%\nekowall_{id}.jpg with a live progress bar.
5. Sets the wallpaper via SystemParametersInfoW (Windows API, no admin needed).

---

Available categories

The full list is always up to date — run nekowall --list to see everything. A non-exhaustive sample:

Group	Categories
Animal girls	catgirl foxgirl wolf-girl wolfgirl doggirl animal-ears
Clothes	maid maid-uniform uniform sailor-uniform hoodie gym-uniform
Accessories	ribbon headphones thigh-high-socks knee-high-socks white-tights
Hair	white-hair blue-hair pink-hair long-hair twintails blonde
Eyes	blue-eyes red-eyes purple-eyes heterochromia green-eyes
Poses & vibes	wink w-sitting lying-down cute vtuber blue-archive hololive
Seasonal	valentine halloween winter summer sakura

---

Requirements

• Python 3.8 or higher
• Windows (wallpaper setting uses the Windows API)
• Internet connection

---

Tip: run on startup

To get a new wallpaper every time you log in:

1. Press Win + R, type shell:startup, press Enter
2. Create a shortcut to nekowall.bat (or nekowall) in that folder

---

API credit

Images are provided by the Nekosia API — a free, public anime image API with safety filters. No API key required.

---