https://github.com/l1asis/winspot
A CLI utility to export and reset Windows Spotlight images.
https://github.com/l1asis/winspot
background-images cli desktop-customization lockscreen python python3 spotlight-images wallpaper-downloader windows-10 windows-11 windows-spotlight winspot
Last synced: about 2 months ago
JSON representation
A CLI utility to export and reset Windows Spotlight images.
- Host: GitHub
- URL: https://github.com/l1asis/winspot
- Owner: l1asis
- License: mit
- Created: 2025-12-28T19:30:18.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2026-01-18T11:12:47.000Z (3 months ago)
- Last Synced: 2026-01-18T18:42:42.472Z (3 months ago)
- Topics: background-images, cli, desktop-customization, lockscreen, python, python3, spotlight-images, wallpaper-downloader, windows-10, windows-11, windows-spotlight, winspot
- Language: Python
- Homepage:
- Size: 107 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# winspot
winspot is a Python utility and command-line tool to export, reset, and download Windows Spotlight images.
Additionally, it can download Bing's daily images.
## Installation
Install directly from PyPI using [pip](https://pip.pypa.io/en/stable/) or [pipx](https://pipx.pypa.io/stable/):
```bash
pip install winspot
# or
pipx install winspot
```
Or install the latest version from source:
```bash
git clone https://github.com/l1asis/winspot.git
cd winspot
pip install .
```
If you want to _download_ Bing/Spotlight images, make sure to install the optional dependencies:
```bash
pip install winspot[dl]
# or from source
pip install .[dl]
```
## Usage
### CLI
winspot uses subcommands to organize different operations:
#### Extract Windows Spotlight
```bash
# Save all images (cached, desktop, lockscreen)
winspot extract
# Save only cached images
winspot extract --cached
# Save only desktop image
winspot extract --desktop
# Save only lock screen image
winspot extract --lockscreen
# Save only landscape images with duplicate prevention
winspot extract --orientation landscape --prevent-duplicates
```
#### Download Spotlight Images
```bash
# Download images from Spotlight API
winspot download
# Download from both API versions (v3 and v4)
winspot download --api-version both
# Download and organize by orientation or resolution
winspot download --orientation both --organize-by orientation
winspot download --orientation both --organize-by resolution
```
#### Download Bing Daily Images
```bash
# Download today's Bing image in 4K
winspot bing
# Download the last 7 days of images
winspot bing --count 7
# Download in 1080p with specific locale
winspot bing --resolution 1920x1080 --locale de-DE
```
#### Reset Windows Spotlight
```bash
# Reset with confirmation prompt
winspot --reset
# Force reset without confirmation
winspot --reset --force
```
For complete help:
```bash
winspot --help
winspot extract --help
winspot bing --help
```
### As a Library
```python
import winspot
# Save with default settings (all sources)
winspot.extract_images()
# Save only cached images
winspot.extract_images(desktop=False, lockscreen=False)
# Save only landscape images with duplicate prevention
winspot.extract_images(
orientation="landscape",
prevent_duplicates=True
)
# Save with conflict resolution
winspot.extract_images(
on_conflict="skip", # or "overwrite", "rename"
)
# Download Spotlight API images
winspot.download_images(
orientation="landscape",
organize_by="resolution",
prevent_duplicates=True
)
# Download Bing daily images
winspot.download_bing_daily_images(
count=7,
resolution="3840x2160",
locale="en-US",
prevent_duplicates=True
)
# Reset Windows Spotlight settings
winspot.reset_windows_spotlight()
```
## Contributing
Pull requests are welcome. For major changes, please open an issue first
to discuss what you would like to change.
## Acknowledgments
* Thanks to Paulo Scardine for the `get_image_size.py` script used in this project.
## License
Distributed under the MIT License. See [`LICENSE`](https://github.com/l1asis/winspot/blob/main/LICENSE) for more information.