undesktop 1.0.0

downloads a random wallpapers from unsplash and sets it as your desktop background.
undesktop-1.0.0 is not a library.

undesktop

crates.io forgejo actions

undesktop is a simple command-line tool written in Rust that downloads a random wallpaper from unsplash and optionally sets it as your desktop background.

features

  • downloads random wallpapers from unsplash based on a search query
  • automatically picks orientation based on your desired resolution
  • optionally sets the downloaded image as your desktop background
  • dry run mode to preview what would happen without downloading anything
  • configurable image format and resolution
  • API key via flag or UNSPLASH_ACCESS_KEY environment variable

installation

you can build and install the latest version of undesktop from crates.io by running:

cargo install undesktop
# or
cargo install undesktop@VERSION # for a specific version

or to build and install from source:

git clone https://codeberg.org/hasibix/undesktop
cd undesktop
cargo install --path .
# or
cargo build --release # for just building the executable

(make sure you have Rust installed to use the commands mentioned above)

alternatively, you can download the latest release from the releases page and add it to your PATH.

usage

you need an Unsplash API access key. provide it using -k or the UNSPLASH_ACCESS_KEY environment variable.

undesktop --path <PATH> --key <KEY> --query <QUERY> [OPTIONS]

required:

  • -p, --path <PATH> — directory to save the wallpaper to.
  • -k, --key <KEY> — your unsplash api key (or use UNSPLASH_ACCESS_KEY).
  • -q, --query <QUERY> — search query (e.g. "nature", "minimalist mountains").

options:

  • -f, --fmt <FMT> — image format (e.g. png, jpg). default: png.
  • -s, --size <WxH> — wallpaper size (e.g. 1920x1080). used as fallback if --width/--height aren't provided.
  • -W, --width <WIDTH> — wallpaper width in pixels. takes priority over --size.
  • -H, --height <HEIGHT> — wallpaper height in pixels. takes priority over --size.
  • -w, --wall — set the downloaded image as the desktop background.
  • -d, --dry / --dry-run — show what would happen without saving or setting the wallpaper.

example:

export UNSPLASH_ACCESS_KEY=your_access_key
undesktop -p ./wallpapers -q "city lights" -s 1920x1080 -w

contributing

undesktop is a small open source project and any feedback or fixes are appreciated.
if you want to help, check out contributing.md for info on how to report bugs, request features, or open a pull request.

if you're unsure about something, feel free to open an issue to discuss it.

attribution

wallpapers are sourced from Unsplash under the Unsplash license. please credit photographers when sharing downloaded wallpapers.

license

Copyright 2026 Hasibix Hasi

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

for more details, consult the license file.