Skip to content

About

Sets a random, free high-resolution wallpaper on Windows, once or on a schedule. SHA-256 verified, auto-update, multiple free image sources.

Resources

Contributing

Security policy

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

🇬🇧 English | 🇵🇱 Polski | 🇩🇪 Deutsch | 🇫🇷 Français | 🇪🇸 Español | 🇧🇷 Português | 🇳🇱 Nederlands
🇨🇳 中文 | 🇯🇵 日本語 | 🇰🇷 한국어 | 🇮🇹 Italiano | 🇹🇷 Türkçe | 🇸🇦 العربية | 🇮🇳 हिन्दी | 🇷🇺 Русский

🖼️ Universal Windows Wallpaper Changer

VersionWindowsPowerShellDotNETDownloadsGitHub Stars
LicensePS Gallery VersionIssues

🔧 Free High-Resolution Wallpapers for Windows You can Schedule

Universal Windows Wallpaper Changer downloads a random, free high-resolution wallpaper (4K by default) from a free image service (or picks one from your own folder) and applies it as the Windows desktop wallpaper. Runs once, or keeps changing in the background with a tray icon.

This project was built through a pragmatic collaboration between human expertise and AI-assisted tooling.

Why This Tool Exists

Windows has no built-in way to rotate wallpapers from multiple free sources without third-party bloatware. This tool gives you a zero-config way to keep your desktop fresh — with no API keys required for the default sources and no administrator rights.

Wallpapers in 4K from FirstEverTech

In addition to free wallpapers selected with a filter from various online services, my tool now also includes my own wallpapers. I’m pleased to announce the first series of 30 photos in 4K quality and PNG format, taken on the island of Santorini. You can also use the filter to search for photos by phrase (1-3 words), e.g. Sunset, Architecture, Ship. I will add more photos from other locations in the future.

Santorini - new 4K wallpapers


SourcesFree Without KeyBackground ModeSelf-HashAdmin Rights

For detailed documentation and guides, see:
→ How the image filter pipeline works (coming soon)
→ Deploying via MDM / silent mode (coming soon)
→ Security and verification (coming soon)

👉 Share your feedback!


💖 Support This Project

Universal Windows Wallpaper Changer is free and open-source — maintained by a single developer.
The provider integrations, background mode and image filtering pipeline are maintained in my free time.

PatreonGitHub SponsorsPayPalBuy Me a CoffeeKo-fi

If this tool saved you time or made your desktop a little nicer — consider supporting development. 🎯 Follow on Patreon for free — stay updated on new releases and development progress.

🏢 Sponsors

No sponsors yet — be the first and add your company ad!

❤️ Supporters

A huge thank you to all our supporters – your contributions make a real difference.
Your name could be here too. Every bit helps cover development costs and ensures these tools continue to improve.

  • Sqania, jadeanemail, westor7, J. A. Dean, Bartechr, tsantaliki, PegHorse

⭐ Stars

If this project helped you, please click the "Star" button at the top of this page on GitHub.

Star History

🌐 Community & Distribution

  • Official threads on forums:
    🔗 TechPowerUp, Guru3D, WinClub, ElevenForum, Win-Raid, and Station-Drivers.

💼 Career Opportunity

Tip

I specialize in Windows deployment, driver automation, hardware compatibility, Microsoft technologies, infrastructure analysis, and custom IT tooling. If your organization faces automation, deployment, device management, or unsupported hardware environments, let's discuss how I can help.

🔗 Business Contact: firstever.tech/contact 🔗 LinkedIn Profile: linkedin.com/in/marcin-grygiel


📑 1. Table of Contents

  1. Table of Contents
  2. Release Highlights
    2.1 Latest Version
    2.2 Previous Release
  3. Application Overview
  4. Key Features
    4.1 Multiple Free Sources
    4.2 Background Mode
    4.3 Security & Verification
    4.4 Customization
    4.5 Setup Wizard & Profiles
    4.6 API Key Management
  5. System Requirements
    5.1 System Requirements Table
    5.2 Windows Version Support
    5.3 Legacy System Notes
  6. Quick Start
    6.1 Method 1: Interactive Start Screen
    6.2 Method 2: One Random Wallpaper
    6.3 Method 3: Background Changer
    6.4 Method 4: PowerShell Gallery
    6.5 Command-Line Options
  7. How It Works
    7.1 Self-Verification & Update Check
    7.2 Image Source Selection
    7.3 Download & Filter Pipeline
    7.4 Wallpaper Application
    7.5 JPEG Import Quality (Windows 11)
    7.6 Files & Locations
  8. Security First Approach
    8.1 Verified Security Layers
  9. Usage Scenarios
    9.1 Home Users
    9.2 IT Professionals
    9.3 System Builders
  10. Download Options
    10.1 Option 1: SFX Executable (Recommended)
    10.2 Option 2: Direct PS1
    10.3 Option 3: PowerShell Gallery
    10.4 Option 4: Source Code
  11. Project Structure
  12. Release Structure
    12.1 Primary Files
    12.2 Verification Files
    12.3 Data Files
  13. Frequently Asked Questions (FAQ)
  14. Image Source Comparison
  15. Performance Metrics
    15.1 Typical Execution Time Breakdown
    15.2 Disk Space Usage
  16. Known Issues
  17. Ready to Use?
    17.1 Quick Start Guide
    17.2 Verification Steps (Optional)
    17.3 Need Help?
  18. Contributing
  19. License
  20. Acknowledgments
  21. Important Links
  22. Author & Contact

↑ Back to top


🎉 2. Release Highlights

2.1 Latest Version

v2026.11.0002 → Release Notes

🆕 What's New

  • Tray menu: "Current wallpaper" shows a readable title for FirstEverTech photos, built from the tags in the file name (e.g. FirstEverTech - Nature Forest).
  • Random run info: when the source is Random, the run summary shows which source was actually picked.

↑ Back to top

2.2 Previous Release

v2026.11.0001 → Release Notes

🆕 Initial Release

  • One random 4K wallpaper from free sources that need no API key: FirstEverTech, Bing, Picsum, Wallhaven (or a random mix of them).
  • FirstEverTech source: the author's own 4K photos, published in the wallpapers release, filterable by tags (nature, wood, city, ...).
  • Background mode with tray icon and start at sign-in — changes the wallpaper every 1–1440 minutes.
  • Multiple sources: free services, your own folders (used in place, never copied or deleted), your own image links or .txt lists, and optional API-key services (Flickr, Immich, Pexels, Pixabay, Unsplash).
  • Security: SHA-256 self-hash verification against GitHub Releases, one-click update from the SFX package (or PowerShell Gallery) with hash check.
  • Dynamic credits: support links loaded from data/universal-windows-wallpaper-changer-credits.txt on GitHub RAW, with an embedded fallback.
  • API keys stored encrypted with DPAPI for the current Windows user; environment variables override stored keys.

↑ Back to top

🖼️ 3. Application Overview

Phase 1 Phase 2 Phase 3 Phase 4 Phase 5
Security Menu Source Filter Taskbar
Security check and update check Menu (wizard, random image, profiles, changer service, API keys) Image sources (online service with/without API key, local, URL) Image filter (phrase, quality, size, format, orientation, run mode) Settings are available via the tray icon in the Windows taskbar

After an interactive run a credits screen follows: keys 1–5 (and A–E for current promotional links) open the support links, any other key exits. Support and ad links are loaded from GitHub RAW with an embedded fallback. It is not shown with -Quiet.

↑ Back to top

✨ 4. Key Features

🖼️ 4.1 Multiple Free Sources

Source API key Query Notes
FirstEverTech No Yes (tags) Author's own 4K photos (JPG), default source in the wizard
Bing No No Landscape only, max 3840 px
Picsum No No Random photos, server-side crop available
Wallhaven Optional Yes SFW only, higher rate limits with a key
Photos No No Windows Pictures folder, used in place
Folder No No Any folder, used in place, never copied/deleted
URL No No Image link or .txt list of links
Flickr Yes Yes EXPERIMENTAL
Immich Yes No EXPERIMENTAL, own server
Pexels Yes Yes New keys currently paused
Pixabay Yes Yes Free API: max 1280 px
Unsplash Yes Yes 50 requests per hour

If a service supports a query and you give none, a random one of Nature, Abstract, Minimalist, Anime, Cyberpunk is used. FirstEverTech is the exception: no query means any photo from the collection.

FirstEverTech photos

The photos are attached to the GitHub release tagged wallpapers, together with wallpapers.json (the list of photos with sizes and tags). File names follow FirstEverTech_<tag>_<tag>_<tag>_<NNN>.jpg (1-3 tags), e.g. FirstEverTech_nature_wood_forest_001.jpg. A query is a list of tags; every word must match a tag of the photo:

.\universal-windows-wallpaper-changer.ps1 -Source FirstEverTech -Query "nature forest" -Once

The photos are the author's own work (3840x2160, JPG, quality 100%). They are free to use through this tool and as your own wallpaper; redistribution and removing metadata or watermarks are not allowed. See the wallpapers release for the full terms. The list is cached locally and refreshed on use.

In the tray menu a FirstEverTech photo is shown by a title built from its tags: the first and the third tag (with fewer tags, all of them), each word capitalised — FirstEverTech_nature_wood_forest_001.jpg becomes Nature Forest.

For best quality with JPG wallpapers, set the Windows JPEG import quality to 100% (see 7.5).

⚡ 4.2 Background Mode

  • Hidden PowerShell process with tray icon (one instance at a time)
  • Start at sign-in via HKCU\Software\Microsoft\Windows\CurrentVersion\Run
  • Runs from a stable copy of the script in %LOCALAPPDATA%\UniversalWindowsWallpaperChanger\, so moving or deleting the downloaded file does not break it
  • The first change happens within seconds, then every 1–1440 minutes; after a failed change it retries in at most 5 minutes (longer if the source is rate limited)
  • Pause / Resume / Change now from the tray menu, or with -Background Pause | Resume | Start | Stop | Status
  • -Background Stop also removes start at sign-in and the saved background settings
  • Daily update check in the tray: a balloon notification appears when a newer version exists
  • The start screen has a Manage the background changer entry (status, change now, pause / resume, stop, start again, remove settings)
  • State persisted in %LOCALAPPDATA%\UniversalWindowsWallpaperChanger\state.json

Tray menu:

Item What it shows / does
Universal Windows Wallpaper Changer Opens the project page
Version x Opens the release notes of the running version
Current wallpaper Source and title or author, e.g. FirstEverTech - Nature Forest | Photo: 12 (the number is the _N of the saved file name; not shown for files used in place)
Resolution / Size / Format e.g. Resolution: 3840x2160 | Size: 6.7MB | Format: JPG (85%); JPG shows the Windows JPEG import quality (see 7.5). Shown only while the current wallpaper is the one set by the tool
Last change Outcome and attempt (e.g. Successful (1/5)), then the next change time and interval, or Paused
Change now Changes the wallpaper immediately (also resumes if paused)
Pause / Resume Stops or continues the schedule
Last used wallpapers Opens the wallpapers folder (with the number of stored images)
Open Wallpaper Setup Wizard Opens the wizard in a new window
Startup with Windows (ON/OFF) Toggles start at sign-in
Exit Closes the tray process; start at sign-in stays as it was

🛡️ 4.3 Security & Verification

  • SHA-256 self-hash verified against GitHub Releases on every interactive start
  • Auto-update checks src/universal-windows-wallpaper-changer.ver on GitHub RAW; the new version is installed from the SFX package (or PowerShell Gallery) and verified by SHA-256
  • DPAPI-encrypted API keys (never shown, never logged, never accepted on command line)
  • No admin rights required — everything runs in HKCU

🎨 4.4 Customization

  • Minimum width, minimum pixels, minimum file size filters
  • Orientation: landscape, portrait, squarish
  • Output format (JPG/PNG) and quality for services that convert (currently Unsplash; other services deliver files as they are)
  • -Keep <n> (default 20, 0 = keep all) or -KeepCurrentOnly for stored downloads — only the tool's own <service>_img_… files in -Dir are ever deleted, never the current wallpaper and never files used in place
  • -MaxAttempts (1–20, default 5) and -Dir (where downloads are stored)
  • API keys overridable via environment variables

📸 SCREENSHOT PLACEHOLDER 2:
Insert here: assets/tray-menu.png — tray icon context menu showing "Current wallpaper", "Pause", "Change now".
Action: Skel w tej sekcji, wstaw obrazek po zrobieniu screenshota.

🧙 4.5 Setup Wizard & Profiles

  • -Wizard (or the first entry of the start screen) asks, step by step: source → folder / link / server address (when the source needs it) → search phrase or tags → minimum width → minimum pixels → minimum file size → quality and format (Unsplash only) → orientation → how many images to keep → maximum attempts → run mode (once, or repeat every n minutes)
  • Steps that do not apply to the chosen source are skipped. A source that needs a key opens the key screen first
  • Wizard defaults: FirstEverTech, 3840 px, minimum file size 2.5M (the command-line default is off), landscape, keep 20, 5 attempts, once
  • The summary screen offers: [1] Run now, [2] Print the command only (ready to paste; keys are never part of it), [3] Save as the default profile, [4] Save as a custom profile, [5] Start again
  • Profiles are JSON files in %APPDATA%\UniversalWindowsWallpaperChanger\profiles\. Run the default one with -Profile, a named one with -Profile <name> (letters, digits, _ and -, up to 40 characters). The start screen lists saved profiles
  • Settings are merged in this order: built-in defaults < profile < command line
  • At any wizard prompt S returns to the start screen and X exits (with the credits screen)

🔑 4.6 API Key Management

  • -Keys shows which keys are set (never the keys themselves); -SetKey <service> asks for a key with hidden input; -RemoveKey <service|All> removes the stored key and the user environment variable
  • The same is available interactively: start screen → Manage API keys, and the key screen the wizard opens for services that need one
  • Services: Flickr, Immich, Pexels, Pixabay, Unsplash (key required), Wallhaven (key optional)
  • Environment variables, which override stored keys: FLICKR_API_KEY, IMMICH_API_KEY, PEXELS_API_KEY, PIXABAY_API_KEY, UNSPLASH_ACCESS_KEY, WALLHAVEN_API_KEY
  • Stored keys are DPAPI-encrypted for the current Windows user in HKCU\Software\FirstEverTech\UniversalWindowsWallpaperChanger\Keys. The Immich server address is stored there too (-ImmichUrl)
  • A system-wide environment variable cannot be removed by the tool; it tells you where to remove it

↑ Back to top

📋 5. System Requirements

5.1 System Requirements Table

Component Minimum Recommended Notes
Windows Version 10 1809 (17763) 11 22H2+ 1809 requires .NET 4.7.2+
.NET Framework 4.7.2 4.8+ Required for TLS 1.2 support
PowerShell 5.1 5.1+ Windows PowerShell 5.1 included
Administrator Not required Not required HKCU only
Internet Required for online sources Required For hash verification and updates
RAM 2 GB 4 GB+ For image processing
Disk Space 100 MB 500 MB+ Depends on -Keep setting

5.2 Windows Version Support

Version Build Status Notes
Windows 11 All builds ✅ Full Optimized support
Windows 10 22H2+ ✅ Full Recommended
Windows 10 21H2 ✅ Full Stable
Windows 10 21H1 (19043) ✅ Full Legacy
Windows 10 20H2 (19042) ✅ Full Legacy
Windows 10 2004 (19041) ✅ Full Legacy
Windows 10 1909 (18363) ✅ Full Legacy
Windows 10 1903 (18362) ✅ Full Legacy
Windows 10 1809 (17763) ✅ Limited Requires .NET 4.7.2+ for TLS 1.2 support
Windows 10 LTSB 2016 (1607) ⚠️ Limited Manual updates required for TLS 1.2
Windows 10 LTSB 2015 (1507) ⚠️ Limited Manual updates required for TLS 1.2

5.3 Legacy System Notes

  • Windows 10 1809 (17763) and newer: Full TLS 1.2 support out-of-the-box
  • Windows 10 LTSB 2015/2016: May require manual installation of:
  • The tool automatically:
    • Detects Windows version limitations
    • Warns about potential connectivity issues
    • Provides fallback options for offline operation
  • Local sources (Photos, Folder) work even without internet connectivity

↑ Back to top

🚦 6. Quick Start

6.1 Method 1: Interactive Start Screen

.\universal-windows-wallpaper-changer.ps1

Opens the start screen with these entries (optional ones appear only when they apply, and numbers shift accordingly):

  1. Wallpaper Changer Wizard
  2. Set one random 4K wallpaper now
  3. Run your saved profile (default or custom; you pick one when several exist)
  4. Manage the background changer (when configured; shows running / stopped)
  5. Manage API keys

Press X to exit (credits screen).

6.2 Method 2: One Random Wallpaper

.\universal-windows-wallpaper-changer.ps1 -Once

Sets one random 4K wallpaper from FirstEverTech, Bing, Picsum, or Wallhaven. The run summary shows which source was picked; if it has no suitable image, the next one is used.

An interactive one-time change replaces a configured background changer: it is stopped and removed from start at sign-in. -Quiet -Once leaves it alone.

6.3 Method 3: Background Changer

.\universal-windows-wallpaper-changer.ps1 -Source Wallhaven -Query "forest" -IntervalMinutes 30

Changes the wallpaper every 30 minutes in the background with a tray icon.

Check status:

.\universal-windows-wallpaper-changer.ps1 -Background Status

Pause / Resume / Stop:

.\universal-windows-wallpaper-changer.ps1 -Background Pause
.\universal-windows-wallpaper-changer.ps1 -Background Resume
.\universal-windows-wallpaper-changer.ps1 -Background Stop

6.4 Method 4: PowerShell Gallery

Install from PowerShell Gallery:

Install-Script -Name universal-windows-wallpaper-changer

Update:

Update-Script -Name universal-windows-wallpaper-changer

Run:

universal-windows-wallpaper-changer

📸 SCREENSHOT PLACEHOLDER 3:
Insert here: assets/start-screen.png — start screen with options [1] Wizard, [2] One random 4K wallpaper, etc.
Action: Skel w tej sekcji, wstaw obrazek po zrobieniu screenshota.

6.5 Command-Line Options

Option Description
-help, -h, -? Display help and exit
-version, -v Display version and exit
-wizard Step-by-step setup wizard
-source <name> Image source (Random, FirstEverTech, Bing, Picsum, Wallhaven, Photos, Folder, Flickr, Immich, Pexels, Pixabay, Unsplash, URL)
-query <text> Search phrase, e.g. "nature winter"
-folder <path> Folder for -Source Folder
-url <link|file> Image link, or .txt list
-minwidth <px> Minimum width. Default: 3840
-minpixels <n> Minimum width×height. Default: 0 (off)
-minsize <size> Minimum file size, e.g. 500K, 1M. Default: 0 (off)
-quality <1-100> JPEG quality for services that convert (Unsplash). Default: 95
-format <jpg|png> Output format for services that convert (Unsplash). Default: jpg
-orientation <o> landscape / portrait / squarish
-maxattempts <n> Images to try before failing (1-20). Default: 5
-dir <path> Where downloaded wallpapers are stored. Default: Pictures\Universal Windows Wallpapers
-keep <n> Keep last n downloaded files. Default: 20 (0 = all)
-keepcurrentonly Keep only current wallpaper
-once Change once and exit
-intervalminutes <n> Change every n min (1-1440) in background
-profile [name] Run a saved profile (default name: default)
-fresh Discard stored queue
-immichurl <url> Immich server address
-background <cmd> Status / Start / Stop / Pause / Resume
-keys Show which keys are set
-setkey <service> Enter a key (hidden input)
-removekey <svc> Remove API key
-jpegimportquality <Max|Default> Set Windows JPEG import quality and exit
-noprompt Do not ask about the JPEG import quality
-quiet, -q No screens, no prompts, no credits; also skips self-hash verification and the update check
-noupdate Skip update check
-skipverify, -s Skip self-hash verification
-debug, -d Print diagnostic messages

↑ Back to top

🔧 7. How It Works

🔒 7.1 Self-Verification & Update Check

  • Integrity Verification — Validates script SHA-256 against GitHub Release
  • Update Detection — Compares current version with src/universal-windows-wallpaper-changer.ver
  • Update from the SFX package — the new WindowsWallpaperChanger-<version>-Win10-Win11.exe is downloaded from the release, its SHA-256 is checked, it is run silently and the installed script is verified again; the previous copy is restored if anything fails. If the package is unavailable, the .ps1 asset of the release is used instead (also hash-checked)
  • PSGallery Path — If installed via Install-Script, updates go through Update-Script

🖼️ 7.2 Image Source Selection

  • Random picks FirstEverTech, Bing, Picsum, and Wallhaven in random order and falls back to the next one when a source has no suitable image
  • Local sources (Photos, Folder) scan files in place (jpg, jpeg, png, bmp, subfolders included) — never copy or delete. Photos skips the tool's own download folder. They try at least 30 images before giving up
  • URL accepts a single link or a .txt list (local file or remote link): up to 2000 unique links, only http(s):// lines are used, links must point to the image file itself. Dropbox dl=0 links are rewritten to dl=1. Downloads are sent with a Referer and a browser-like user agent; if a site blocks the download (bot check), the tool says so — download the file in a browser and use -Source Folder

📊 7.3 Download & Filter Pipeline

  • Metadata pre-filter (width, height, orientation) before download
  • Download to temp, then verify real dimensions via System.Drawing
  • File type detected from magic bytes (not extension)
  • Accepted files renamed to <provider>_img_<date>_<N>.<ext>
  • Minimum file size is checked on the downloaded file (FirstEverTech also from the photo list, before download)
  • Queue: images fetched but not yet used are kept per source, query, minimum width and orientation in %LOCALAPPDATA%\UniversalWindowsWallpaperChanger\queue and used first next time (not for Photos, Folder, Immich, URL). -Fresh discards the queue
  • Rate limits: after HTTP 429 (and 403 for Unsplash) a source is paused — Unsplash and Pexels 55 min, Flickr 30 min, Pixabay and Wallhaven 2 min, others 5 min. The pause survives restarts; in background mode the next change waits for it
  • Unsplash: the image is requested at your minimum width in the chosen format and quality, and every used photo is reported to Unsplash as its API guidelines require

⚡ 7.4 Wallpaper Application

  • SystemParametersInfo with SPI_SETDESKWALLPAPER
  • WallpaperStyle = 10 (Fill), TileWallpaper = 0
  • Attribution logged to %LOCALAPPDATA%\UniversalWindowsWallpaperChanger\attribution.log — one tab-separated line per image: time, source, id, author, page link, author link, file name
  • Old files cleaned up according to -Keep / -KeepCurrentOnly: only files named <service>_img_… in -Dir are counted (newest by creation time kept); the current wallpaper and local sources are never touched

🎚️ 7.5 JPEG Import Quality (Windows 11)

When a wallpaper is set, Windows stores its own copy in %APPDATA%\Microsoft\Windows\Themes\TranscodedWallpaper. How much quality is kept depends on the source format and on the registry value HKCU\Control Panel\Desktop\JPEGImportQuality.

Measured on Windows 11, build 29704.100 (4K source images, one wallpaper change per test; other builds were not tested):

Test Source JPEGImportQuality Windows copy Size of Windows copy
1 PNG, 15.0 MB not set PNG 15.33 MB
2 PNG, 15.0 MB 100 PNG 15.33 MB
3 JPG, 6.74 MB not set PNG 2.14 MB
4 JPG, 6.74 MB 100 PNG 7.18 MB

What the numbers show:

  • PNG is not changed by Windows, with or without the setting (15.0 MB → 15.33 MB in tests 1 and 2).
  • JPG without the setting is reduced from 6.74 MB to 2.14 MB (about -68%). The resolution of the Windows copy is the same as the source in all four tests, so the reduction comes from lossy recompression, not from scaling.
  • JPG with the setting at 100 gives 7.18 MB (about +6%), so the recompression loss is avoided.
  • The Windows copy is always a PNG, never a JPG, in all four tests.

Not measured: the quality value Windows uses when the setting is not present. The tool's pre-check assumes 85% in that case; this is an assumption, not a measurement.

What this means for the FirstEverTech photos: they are published as JPG (quality 100%) to save space and transfer. To keep their full quality on your desktop, set the value to 100:

.\universal-windows-wallpaper-changer.ps1 -JpegImportQuality Max

Restore the Windows default with -JpegImportQuality Default. The change is per-user (HKCU), needs no administrator rights, and takes effect after you sign out and in (or restart) and set the wallpaper again. Interactive runs show this as a pre-check after the startup checks, every time until the value is 100; -NoPrompt hides the question. It is also skipped with -Quiet, -Format png or redirected input.

📂 7.6 Files & Locations

Location Content
%LOCALAPPDATA%\UniversalWindowsWallpaperChanger\ wallpaper.log (trimmed at 512 KB), attribution.log, state.json, background.json, command.txt, queue\, ratelimit_<source>.txt, firstevertech-wallpapers.json (cached photo list), the installed script copy used by background mode
%APPDATA%\UniversalWindowsWallpaperChanger\profiles\ Saved profiles (<name>.json)
%USERPROFILE%\Pictures\Universal Windows Wallpapers\ Downloaded wallpapers (default -Dir)
HKCU\Software\FirstEverTech\UniversalWindowsWallpaperChanger DPAPI-encrypted API keys (Keys), Immich server address
HKCU\Software\Microsoft\Windows\CurrentVersion\Run Start at sign-in (UniversalWindowsWallpaperChanger)
HKCU\Control Panel\Desktop WallPaper, WallpaperStyle, TileWallpaper; JPEGImportQuality only if you set it

Data from earlier folders (...\FirstEverTech\UniversalWindowsWallpaperChanger) is migrated automatically on start.

↑ Back to top

🛡 8. Security First Approach

🔒 8.1 Verified Security Layers

1. Self-Integrity   → Script Hash Verification against GitHub Releases
2. API Key Safety   → DPAPI encryption (current Windows user), never logged
3. Command Line     → Keys never accepted on the command line
4. Log Safety       → Secrets masked with Hide-Secret
5. Update Safety    → SHA-256 check of the update; previous copy restored on mismatch
6. PSGallery        → Verified by PowerShellGet (self-check skipped)

Self-hash verification and the update check run in interactive mode only. -Quiet and the background tray process skip them.

🏷️ 8.2 Why is the certificate "not trusted"?

The FirstEver.tech certificate is self-signed. The PowerShell script (universal-windows-wallpaper-changer.ps1) is the authoritative source of the tool. Its SHA-256 hash is published on GitHub and verified automatically on every interactive run. The SFX executable is a convenience wrapper — it installs the same PS1, whose hash is verified on every interactive run.

🛡️ 8.3 Why does VirusTotal show detections for the SFX executable?

Once the SFX is released: The SFX package may show a small number of detections — known false positives from SFX+PowerShell combinations. The PS1 script itself scores clean. Always verify the hashes published in the Release.

📸 SCREENSHOT PLACEHOLDER 4:
Insert here: assets/virustotal-ps1.png — VirusTotal scan of the PS1 showing 0 detections.
Action: Skel w tej sekcji, wstaw obrazek po zrobieniu screenshota.

↑ Back to top

🎯 9. Usage Scenarios

🏠 9.1 Home Users

  • Fresh wallpaper daily without third-party apps
  • No API keys for default sources
  • One-click operation via wizard

💼 9.2 IT Professionals

  • Silent deployment via -quiet — no screens, prompts or credits; exit code 0 on success, 1 on failure; details in wallpaper.log. Self-hash verification and the update check are skipped in this mode
  • Silent background setup — -quiet -IntervalMinutes 60 -Source Bing installs the background changer and start at sign-in without any UI
  • Per-user — no admin rights, runs in HKCU
  • Profile-based — save settings with -wizard (default or custom profile), copy the JSON from %APPDATA%\UniversalWindowsWallpaperChanger\profiles\, run with -Profile [name]
  • Keys for unattended setups — -SetKey asks interactively; use the environment variables from 4.6 instead

🛠 9.3 System Builders

  • Pre-configured profiles for customer machines
  • Folder source — use curated wallpapers without downloading
  • Background mode — set once, runs at sign-in

↑ Back to top

📥 10. Download Options

10.1 Option 1: SFX Executable (Recommended)

  • File: WindowsWallpaperChanger-<version>-Win10-Win11.exe
  • Features: One-click install and start, installs the script to a fixed per-user folder, also used by the built-in updater
  • Security: Self-verifying SHA-256 hash check on every interactive run
  • For: Most users, easiest method

10.2 Option 2: Direct PS1

  • File: universal-windows-wallpaper-changer.ps1

  • Features: Full control, modifiable code, transparency

  • Security: Self-verifying SHA-256 hash check on every interactive run

  • For: Advanced users, administrators, customization

    powershell -ExecutionPolicy Bypass -File .\universal-windows-wallpaper-changer.ps1

10.3 Option 3: PowerShell Gallery

  • Method: Install-Script universal-windows-wallpaper-changer - PowerShell command
  • Features: Versioned distribution via PSGallery, one-line install/update (Update-Script)
  • Security: Self-verifying SHA-256 hash check on every interactive run
  • For: Advanced users, administrators

10.4 Option 4: Source Code

  • Method: git clone the repository
  • Features: Latest development version, full customization
  • For: Developers, contributors

↑ Back to top

📁 11. Project Structure

Key Files and Directories:

src/ - Main scripts directory

data/ - Data files

assets/ - Screenshots and branding

ISSUE_TEMPLATE/ - Issue templates

/ - Root directory files

↑ Back to top

📦 12. Release Structure

Each version (v202x.xx.xxxx) includes:

12.1 Primary Files

  • WindowsWallpaperChanger-202x.xx.xxxx-Win10-Win11.exe - Main executable (SFX package, also used for updates)
  • universal-windows-wallpaper-changer.ps1 - PowerShell script (inside the SFX and attached separately for direct use)

12.2 Verification Files

  • WindowsWallpaperChanger-202x.xx.xxxx-Win10-Win11.sha256 - EXE hash
  • universal-windows-wallpaper-changer-202x.xx.xxxx-ps1.sha256 - PS1 script hash (used by self-check)

12.3 Data Files (loaded from main branch, not Release)

  • src/universal-windows-wallpaper-changer.ver - Latest version string for auto-update
  • data/universal-windows-wallpaper-changer-credits.txt - Credits screen content
  • data/universal-windows-wallpaper-changer-ads.txt - Promotional links (keys A–E)

These are fetched with a cache-buster, so updates are visible immediately after commit to main.

Photo release (separate): the release tagged wallpapers is not a version release. It holds the FirstEverTech photos and wallpapers.json and must not be marked as Latest.

↑ Back to top

❓ 13. Frequently Asked Questions (FAQ)

🤔 13.1 Is this tool safe to use?

Yes. The tool:

  • Verifies its own SHA-256 hash against GitHub Releases
  • Never requires administrator rights
  • Stores API keys encrypted with DPAPI
  • Never writes keys to logs or accepts them on the command line

🔄 13.2 Do I need an API key?

No, for the default sources: FirstEverTech, Bing, Picsum, Wallhaven work without a key. Wallhaven has higher rate limits with a free key.

🖼️ 13.3 Where are wallpapers saved?

By default: %USERPROFILE%\Pictures\Universal Windows Wallpapers\.
Change with -Dir <path>.

⚠️ 13.4 Are Bing images copyrighted?

Yes. Bing images are copyrighted and meant for personal use. The tool does not claim ownership or redistribute images. For commercial use, stick to Picsum, your own folders, or sources with explicit licenses.

🔧 13.5 What if a download fails?

The tool tries up to -MaxAttempts images (default 5). If all fail, it reports the reasons. For Random, it falls back through the other free sources (FirstEverTech, Bing, Picsum, Wallhaven).

🔄 13.6 How does the automatic update check work?

The tool compares $ScriptVersion with src/universal-windows-wallpaper-changer.ver on GitHub RAW. If a newer version exists, it downloads the SFX package of that release, verifies its SHA-256, installs it and restarts (PowerShell Gallery installs use Update-Script).

🔒 13.7 What does self-hash verification do?

Before running interactively, the tool calculates its own SHA-256 hash and compares it with the reference hash published in the GitHub Release. This ensures the script hasn't been modified or corrupted.

🏷️ 13.8 Why is the certificate "not trusted"?

The FirstEver.tech certificate is self-signed. The PS1 script is the authoritative source, verified by SHA-256 on every interactive run. The SFX is a convenience wrapper.

🛡️ 13.9 Why does VirusTotal show detections for the SFX?

Once released: Known false positives from SFX + PowerShell execution. The PS1 itself scores clean. See Section 8.3.

💾 13.10 Where is the log file?

%LOCALAPPDATA%\UniversalWindowsWallpaperChanger\wallpaper.log

🖥️ 13.11 Can I use this on a server?

Yes, but wallpaper changing is per-user. On Server Core (no desktop), it has no visible effect.

🎚️ 13.12 Why do my JPG wallpapers look worse than PNG?

Windows recompresses JPG wallpapers with loss unless JPEGImportQuality is set to 100; PNG wallpapers are left as they are. In our test a 6.74 MB JPG became a 2.14 MB copy without the setting and a 7.18 MB copy with it. Fix: -JpegImportQuality Max, then sign out and in. Details: 7.5.

🛑 13.13 How do I stop the background changer?

-Background Stop (or start screen → Manage the background changer → Stop) ends the process and removes start at sign-in and the saved settings. The tray menu Exit only closes the tray process; start at sign-in stays as it was. To pause without stopping, use Pause or -Background Pause.

🔀 13.14 Does a one-time change affect the background changer?

Yes, when run interactively: -Once (or the "Set one random 4K wallpaper now" entry) stops the background changer and removes it from start at sign-in, so it does not overwrite your wallpaper. -Quiet -Once does not.

🗂️ 13.15 Can I use my own images?

Yes: -Source Photos (your Pictures folder), -Source Folder -Folder <path> (subfolders included) or -Source URL -URL <link or .txt list>. Files in folders are used in place and never copied or deleted.

💾 13.16 Can I save my settings?

Yes. The wizard saves a default profile (-Profile) or a named one (-Profile <name>), see 4.5. Command-line options override profile values.

↑ Back to top

🖼️ 14. Image Source Comparison

Feature FirstEverTech Bing Picsum Wallhaven Photos/Folder API-key services
API key No No No Optional No Yes
Query Tags No No Yes No Yes
4K native Yes (3840x2160 JPG) Yes (UHD) Yes (server crop) Yes (filter) Depends Varies
Orientation filter Yes (list data) Landscape only Yes (server) Yes Local scan Yes
Used in place No No No No Yes No
Rate limit GitHub None None Higher with key None Varies
Experimental No No No No No Flickr, Immich

↑ Back to top

📊 15. Performance Metrics

15.1 Typical Execution Time Breakdown

Phase Time Description
Compatibility Pre-Check 5–10 seconds OS build, .NET Framework, TLS 1.2 availability, GitHub connectivity verification
Verification & Update Check 5–10 seconds Self-integrity hash verification and updater version check
Image Fetch & Download 2–15 seconds Depends on source and image size
Filter & Verify 1–3 seconds System.Drawing dimension and orientation check
Wallpaper Apply < 1 second SystemParametersInfo call

Note: Times above are measured on typical SSD-equipped systems with a standard broadband connection. On slower HDD systems or limited internet connections, individual phases (especially image download) may take significantly longer.

15.2 Disk Space Usage

Stage Estimated Usage Notes
Script ~200 KB Single PS1 file
Log file < 512 KB Auto-trimmed at 512 KB
Downloaded wallpapers 2–10 MB each Depends on source resolution
State & queue files < 1 MB JSON and CliXML
Persistent disk usage Depends on -Keep 20 images ≈ 40–200 MB

Important notes:

  • The current wallpaper is never deleted, even if -Keep is exceeded.
  • With -Keep 0, nothing is deleted automatically.
  • With -KeepCurrentOnly, only the current wallpaper is kept.

↑ Back to top

🐛 16. Known Issues

For current limitations and workarounds, please see: KNOWN_ISSUES.md

Summary of known limitations:

  • Bing images are copyrighted and meant for personal use
  • Flickr and Immich support is experimental — not verified against live accounts/servers
  • Pixabay free API delivers at most 1280 px regardless of -MinWidth
  • Unsplash allows 50 requests per hour — intervals under 5 minutes can hit the limit
  • Background mode runs for the current user only (per-user registry HKCU)
  • JPG wallpapers are recompressed with loss by Windows unless JPEGImportQuality is 100 (-JpegImportQuality Max); PNG is not affected, see 7.5
  • Windows 10 LTSB 2015/2016 may need manual TLS 1.2 updates

↑ Back to top

🚀 17. Ready to Use?

17.1 Quick Start Guide

  1. Download latest release from Releases page
  2. Verify SHA-256 hashes (optional but recommended)
  3. Run the tool — no administrator rights required
  4. Follow prompts — the wizard handles everything automatically
  5. Enjoy your new wallpaper

17.2 Verification Steps (Optional)

17.3 Need Help?

↑ Back to top

🤝 18. Contributing

We welcome contributions! Please feel free to submit pull requests, report bugs, or suggest new features.

Areas for Contribution:

  • Additional free image source integrations
  • Translation improvements
  • Documentation enhancements
  • Testing on various Windows versions

Please open an Issue before submitting a PR.

↑ Back to top

📄 19. License

This project is licensed under the MIT License - see the LICENSE file for details.

↑ Back to top

🙏 20. Acknowledgments

  • Bing, Picsum, Wallhaven for free image APIs; FirstEverTech photos by the author
  • Flickr, Immich, Pexels, Pixabay, Unsplash for optional provider APIs
  • AI audits
  • Open source community for continuous improvement
  • Beta testers for real-world validation

↑ Back to top

🔗 21. Important Links

↑ Back to top

🧑‍💻 22. Author & Contact

Author Photo

Marcin Grygiel aka FirstEver


Note: This tool is provided as-is for convenience purposes. Always respect the license of every image you keep. Bing images are copyrighted and meant for personal use.

↑ Back to top

About

Sets a random, free high-resolution wallpaper on Windows, once or on a schedule. SHA-256 verified, auto-update, multiple free image sources.

Resources

Contributing

Security policy

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages