wallflow

Elegant wallpaper management with smooth transitions

A modern, Rust-based wallpaper manager that brings fluidity to your Linux desktop with multiple sources, smooth transitions, and dynamic color schemes.

About This Project

This is my first Rust project. I decided to learn Rust by building something I'd actually use daily. wallflow started as a learning exercise and evolved into a reasonably decent wallpaper manager. While toying around with hyprland, I used awww for smooth transitions and loved it. So I decided to do something like variety, but powered by aww so you have smooth transitions. KWin in KDE support wlr-layer-shell, and awww works perfectly. Sorry, GNOME.

Thus, wallflow was born.

The codebase reflects this journey and that means, it is not perfect. Use it at your own risk. But hey, it's open source! Feel free to contribute and help me improve it.

Features

• Multiple Wallpaper Sources

  • Local collections
  • Wallhaven - Search-based wallpapers
  • Unsplash - High-resolution photos
  • Reddit - Subreddit-based (earthporn, wallpapers, etc.)
  • NASA APOD - Astronomy Picture of the Day
  • Bing - Daily photo
  • Google Earth View - Satellite imagery
  • Picsum - Random photos

• Smart Features

  • Built-in daemon for automatic wallpaper rotation
  • Smooth animated transitions (via awww)
  • Auto-resolution detection (xrandr, sway, wlr-randr)
  • Optional pywal integration for dynamic color schemes
  • Self-update capability

• Desktop Support

  • Hyprland, Sway, and other wlroots compositors
  • KDE Plasma (KWin supports wlr-layer-shell)
  • X11 (feh, nitrogen)

Installation

From crates.io

cargo install wallflow

Pre-built Binaries

Download from GitHub Releases:

# Download and install
chmod +x wallflow-x86_64-unknown-linux-gnu
mv wallflow-x86_64-unknown-linux-gnu ~/.local/bin/wallflow

Fedora (COPR)

sudo dnf copr enable uproar9991/wallflow
sudo dnf install wallflow

From Source

git clone https://github.com/MKSG-MugunthKumar/wallflow
cd wallflow
cargo build --release
cp target/release/wallflow ~/.local/bin/

Quick Start

# Set wallpaper from local collection
wallflow local

# Download from online sources
wallflow wallhaven nature mountains
wallflow reddit earthporn
wallflow unsplash architecture
wallflow bing
wallflow apod
wallflow earthview

# Run as daemon (auto-rotate)
wallflow daemon

# Run daemon in foreground (for testing)
wallflow daemon --foreground

# Check for updates
wallflow update --check

Running as a Service (Linux)

wallflow can run as a background service that automatically rotates your wallpaper.

Option 1: systemd (recommended)

# Install binary and service
make install
make install-service
make enable-service

# Management commands
make status              # Check service status
make logs                # Follow service logs
make disable-service     # Stop and disable
make uninstall-service   # Remove service file

Option 2: XDG Autostart

Simpler alternative that starts wallflow on login:

make install
make install-autostart   # Starts on next login

make uninstall-autostart # Remove

Configuration

Configuration file location:

• Linux: ~/.config/mksg/wallflow/config.yml
• macOS: ~/Library/Application Support/mksg/wallflow/config.yml

Create it by copying the example:

# Linux
mkdir -p ~/.config/mksg/wallflow
cp config.example.yml ~/.config/mksg/wallflow/config.yml

# macOS
mkdir -p ~/Library/Application\ Support/mksg/wallflow
cp config.example.yml ~/Library/Application\ Support/mksg/wallflow/config.yml

See config.example.yml for all options.

Updating

wallflow can update itself:

# Check for updates
wallflow update --check

# Download and install update
wallflow update

Note: Self-update is disabled for package manager installations (dnf, apt). Use your package manager instead.

Contributing

Contributions are welcome! This is a learning project, so:

• Beginners: Your PRs are welcome. We all start somewhere.
• Experts: Help improve the code quality and teach better patterns.

See CONTRIBUTING.md for guidelines.

Roadmap

See TODO.md for planned features including:

• Interactive TUI wallpaper browser
• Vim-style keybindings
• Collection management and tagging
• Multi-monitor support
• Plugin system

License

MIT - See LICENSE

Trademark

"wallflow" is a trademark of Mind Kraft Studios Group (MKSG). See TRADEMARK.md for usage guidelines.

Acknowledgments

• awww - Smooth wallpaper transitions
• pywal - Color scheme generation
• ratatui - TUI framework (not yet)
• The Rust community for excellent documentation and crates