{"id":28325236,"url":"https://github.com/shravanasati/iris","last_synced_at":"2026-04-26T13:00:26.657Z","repository":{"id":47158909,"uuid":"384062763","full_name":"shravanasati/iris","owner":"shravanasati","description":"An easy-to-use, customizable, cross-platform, and open-source wallpaper manager.","archived":false,"fork":false,"pushed_at":"2026-04-25T20:39:58.000Z","size":356,"stargazers_count":20,"open_issues_count":1,"forks_count":3,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-04-25T21:13:30.185Z","etag":null,"topics":["go","golang","hacktoberfest","linux","macos","wallpaper","wallpaper-changer","wallpaper-manager","windows"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/shravanasati.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2021-07-08T08:57:31.000Z","updated_at":"2026-04-25T20:40:02.000Z","dependencies_parsed_at":"2022-09-04T02:40:37.096Z","dependency_job_id":"f80a8605-7c80-4e16-baf4-b54d4e9537b8","html_url":"https://github.com/shravanasati/iris","commit_stats":{"total_commits":42,"total_committers":1,"mean_commits":42.0,"dds":0.0,"last_synced_commit":"1a34cb16d670f8d20c980c072553a8f17ed30670"},"previous_names":["shravanasati/iris","shravan-1908/iris"],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/shravanasati/iris","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shravanasati%2Firis","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shravanasati%2Firis/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shravanasati%2Firis/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shravanasati%2Firis/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/shravanasati","download_url":"https://codeload.github.com/shravanasati/iris/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shravanasati%2Firis/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32297897,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-26T09:34:17.070Z","status":"ssl_error","status_checked_at":"2026-04-26T09:34:00.993Z","response_time":129,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["go","golang","hacktoberfest","linux","macos","wallpaper","wallpaper-changer","wallpaper-manager","windows"],"created_at":"2025-05-25T20:12:20.201Z","updated_at":"2026-04-26T13:00:26.647Z","avatar_url":"https://github.com/shravanasati.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# iris\n\n\u003cp align=\"center\"\u003e \n\t\u003cimg src=\"assets/icon.png\" height=\"300px\"\u003e\n\u003c/p\u003e\n\niris is an easy to use, cross platform and customizable wallpaper manager.\n\n\u003cbr\u003e\n\n## 🌐 Table of Contents\n\n- [Features](https://github.com/shravanasati/iris#-features)\n\n- [Installation](https://github.com/shravanasati/iris#%EF%B8%8F-installation)\n    * [Package Managers](https://github.com/shravanasati/iris/#package-managers)\n    * [Using Go compiler](https://github.com/shravanasati/iris/#using-go-compiler)\n    * [Build from source](https://github.com/shravanasati/iris/#build-from-source)\n\n- [Motivation](https://github.com/shravanasati/iris#-motivation)\n\n- [Usage](https://github.com/shravanasati/iris#-usage)\n    * [Root command](https://github.com/shravanasati/iris#root-command)\n    * [Cache](https://github.com/shravanasati/iris#cache)\n    * [Customization](https://github.com/shravanasati/iris#customization)\n    * [Shell Completions](https://github.com/shravanasati/iris#shell-completions)\n\n- [Changelog](https://github.com/shravanasati/iris#-changelog)\n\n- [Versioning](https://github.com/shravanasati/iris#-versioning)\n\n- [Licensing](https://github.com/shravanasati/iris#-license)\n\n- [Contribution](https://github.com/shravanasati/iris#-contribution)\n\n\n\u003cbr\u003e\n\n## ✨ Features\n- Cross platform\n- Customizable\n- Easy to use\n- Low memory overhead and CPU usage\n- Support for remote wallpapers as well as local wallpapers\n- Free \u0026 Open Source\n\n\u003cbr\u003e\n\n## ⚡️ Installation\n\n### Installation Scripts\n\n#### Linux and macOS\n\n```bash\ncurl https://raw.githubusercontent.com/shravanasati/iris/main/scripts/install.sh | bash\n```\n\n### Package Managers\n\n#### Windows\n```powershell\nscoop install https://github.com/shravanasati/iris/raw/main/scripts/iris.json\n```\n\n\u003c!-- iris is available on various package managers across different operating systems.\n\niris is present in the AUR. If you're on an Arch based Linux distro,\nexecute:\n\n```\ngit clone https://aur.archlinux.org/iris-bin.git\ncd iris-bin\nmakepkg -si\n```\n\nOr use any AUR helper like yay:\n```\nyay -S iris-bin\n``` --\u003e\n\n\n### GitHub Releases\n\nUse [`eget`](https://github.com/zyedidia/eget) to automatically download and extract the binaries:\n\n```\neget shravanasati/iris\n```\n\niris binaries for all operating systems are available on the [GitHub Releases](https://github.com/shravanasati/iris/releases/latest) tab. You can download them manually and place them on `PATH` in order to use them.\n\n\n\n### Using Go compiler\n\nIf you've Go compiler (v1.18 or above) installed on your system, you can install iris via the following command. \n\n\n```\ngo install github.com/shravanasati/iris@latest\n```\n\n\n### Build from source\n\nYou can alternatively build iris from source via the following commands (again, requires go1.18 or above):\n\n```\ngit clone https://github.com/shravanasati/iris.git\ncd ./iris\ngo build\n```\n\nIf you want to build iris in release mode (stripped binaries, compressed distribution and cross compilation), execute the following command. You can also control the release builds behavior using the [`release.config.json`](./scripts/release.config.json) file.\n\n```\npython ./scripts/build.py\n```\n\n\u003cbr\u003e\n\n## 💫 Motivation\nI wanted a wallpaper manager which gave a bing wallpaper + nitrogen like interface, good wallpapers and customizability with a bunch of features.\n\n\u003cbr\u003e\n\n## 💡 Usage\n\n### Root command\n\nSimply calling `iris` without any flags and arguments from the terminal would launch iris and it will change the desktop wallpaper according to the set configuration.\n\n### Get\n\nThe get command prints path to the currently set wallpaper.\n\n```\niris get\n```\n\n### Set\n\nThe set command accepts a filepath as an argument and sets it as the desktop wallpaper.\n\nExample:\n```\niris set ~/Pictures/my-fav-image.jpg\n```\n\n### Video\n\nThe video wallpaper support is currently experimental and requires ffmpeg to work.\n\nExample:\n```\niris video ~/Videos/path-to-video.mp4\n```\n\nOnly mp4, mkv and gif files are supported at the moment.\n\nThe first time running this command on a single video might take some time since iris first converts the video into frames using ffmpeg and then iterates through the frames and sets each one of them as wallpaper every few milliseconds.\n\n### Cache\n\nThe `cache` command provides access to manage iris storage. This includes video frame caches and the GitHub repository result cache.\n\n#### Video Cache\nSince video wallpapers are implemented by converting videos into frames, iris caches these frames to avoid reconverting them every time you set a video wallpaper.\n\n```bash\n# Print the total cache size used by iris (videos + remote sources)\n$ iris cache size\n\n# List out the paths of all videos iris has cached\n$ iris cache video list\n\n# Remove a specific video from the cache\n$ iris cache video rm \"/path/to/video.mp4\"\n\n# Clear all video caches\n$ iris cache video clear\n```\n\n#### GitHub Cache\niris caches the results of GitHub repository listings to support offline mode and reduce API traffic by checking commit SHAs before fetching updates.\n\n```bash\n# List all GitHub repositories currently cached\n$ iris cache github list\n\n# Force a refresh of the cache for a specific repository on next run\n$ iris cache github sync \"github.com/user/repo/tree/branch\"\n\n# Clear all cached GitHub repository results\n$ iris cache github clear\n```\n\n#### Global Cache Helpers\n```bash\n# Clear the entire cache (deletes everything: video frames, github data, etc.)\n$ iris cache clear\n\n# Total aggregate size of all caches\n$ iris cache size\n```\n\n### Customization\n\niris supports multiple remote sources for fetching wallpapers, including **Windows Spotlight**, **GitHub**, and **Reddit**. You can also use your own local collection of wallpapers.\n\n#### Remote Sources\n\n- **Windows Spotlight**: Fetches images from [windows10spotlight.com](https://windows10spotlight.com).\n  - Use with: `iris config --remote-source spotlight`\n  - Filter with: `iris config --search-terms \"landscape,ocean\"`\n\n- **GitHub**: Fetches wallpapers from a specific folder in a GitHub repository.\n  - Use with: `iris config --remote-source \"https://github.com/owner/repo/tree/branch/path/to/wallpapers\"`\n  - **TIP**: If you reach rate limits, set your token with `iris config --github-token \u003cyour-token\u003e`.\n\n- **Reddit**: Fetches top images from specified subreddits.\n  - Basic: `iris config --remote-source \"r/wallpapers\"`\n  - Specialized: `iris config --remote-source \"r/wallpapers+earthporn\"` (combine subreddits)\n  - Advanced: Use sort and time filters:\n    - `r/wallpapers/top?t=day` (Top of the day)\n    - `r/wallpapers/new` (Newest)\n    - `r/wallpapers/hot` (Hot)\n\nWhen iris is ran for the first time, it automatically configures itself with sensible defaults.\n\nYou can customize iris to work as you wish by using the `config` command.\n\n\n```\n$ iris config --help\n\niris v0.4.0\nThe config command is used to customize iris according to your needs. All configuration options are exposed as flags.\n\t\nExamples:\n\n$ iris config --remote-source spotlight\n$ iris config --search-terms landscape,nature\n$ iris config --save-wallpaper[=false]\n$ iris config --wallpaper-directory /home/user/Pictures/Wallpapers\n$ iris config --change-wallpaper[=false]\n$ iris config list\n\nUsage:\n  iris config [flags]\n  iris config [command]\n\nAvailable Commands:\n  list        List the iris config.\n\nFlags:\n  -c, --change-wallpaper                   Whether to change wallpapers continuosly in the background.\n      --check-for-updates                  Whether to check for updates of iris from github. (default true)\n      --github-token string                The GitHub Personal Access Token (PAT), used to perform authorized requests to fetch wallpapers from GitHub repositories.\n  -h, --help                               help for config\n  --remote-source string               Remote source to select wallpapers from. Valid options are: spotlight, github, reddit.\n  -s, --save-wallpaper                     Whether to save the wallpaper to the local directory.\n  -u, --save-wallpaper-directory string    The local directory to save wallpapers in. (default \"C:\\\\Users\\\\devsh\\\\.iris\\\\wallpapers\")\n  -q, --search-terms strings               The search terms for spotlight remote wallpapers. (default [nature])\n  -t, --selection-type random              The selection type for choosing wallpapers from the local directory, either random or `sorted`. (default \"random\")\n  -d, --wallpaper-change-duration string   The duration between wallpaper changes, if to change them continuosly. (default \"5m\")\n  -w, --wallpaper-directory string         The local directory to get wallpapers from. (default \"C:\\\\Users\\\\devsh\\\\OneDrive\\\\Pictures\\\\favorites\")\n  -f, --wallpaper-file string              Path to the wallpaper file.\n\nUse \"iris config [command] --help\" for more information about a command.\n\n```\n\nAll configuration fields are pretty self explanatory, still I'd like to describe them all in brief.\n\n- Remote Source: Specify where to fetch wallpapers from. Supported sources are `spotlight` (Windows Spotlight) and `github` (GitHub repository).\n\n- Search Terms: The search terms for remote wallpapers. You can have multiple search terms, but its recommended to not to have more than 3 since it narrows down the search results. The search terms are used only when the remote source is set to spotlight.\n\n- Change wallpaper: Boolean value for whether to continuously change wallpapers or not.\n\n- Change wallpaper duration: If to change wallpapers, then after how long. The duration value can be anything in format `30s` `4m5s` `1h` `2h30m8s`.\n\n- Wallpaper file: Specify path to a single wallpaper file.\n\n- Wallpaper directory: Specify your own wallpaper directory if you don't want iris to use a remote source.\n\n- Selection type: If to use wallpapers from the local system, then what should be the selection type: random or sorted.\n\n- Save wallpaper: Boolean value for whether to save the remote wallpapers or delete them after usage. If this is set to true, then the wallpapers will be stored in `~/.iris/wallpapers` directory by default, unless the following option is not altered.\n\n- Save wallpaper directory: Choose a directory to save wallpapers in. Defaults to `~/.iris/wallpapers`.\n\n- GitHub Token: The GitHub Personal Access Token (PAT) used to perform authorized requests when fetching wallpapers from GitHub repositories. You can create one from [here](https://github.com/settings/tokens). You need to grant \"Contents\" repository permission for a fine-grained token or the \"repo\" scope for the classic PAT.\n\n\nYou can also view your iris configuration using `iris config list` command.\n\n```\n$ iris config list\n\niris v0.2.1\n+---------------------------+----------------------------------+\n|          OPTION           |              VALUE               |\n+---------------------------+----------------------------------+\n| Search Terms              | nature                           |\n| Change Wallpaper          | false                            |\n| Change Wallpaper Duration | 5m                               |\n| Wallpaper Directory       |                                  |\n| Selection Type            | random                           |\n| Save Wallpaper            | true                             |\n| Save Wallpaper Directory  |                                  |\n+---------------------------+----------------------------------+\n```\n\n### Shell-Completions\n\niris can generate shell completions for powershell, fish, bash and zsh.\n\n`iris completion shell_name`\n\nIt will output a completion script for your shell. Copy and paste it on your shell profile.\n\n\n## ⏪ Changelog\n\nEntire changelog can be viewed in the [`CHANGELOG.md`](CHANGELOG.md)\n\n\u003cbr\u003e\n\n## 🔖 Versioning\n*iris* releases follow semantic versioning, every release is in the *x.y.z* form, where:\n- *x* is the MAJOR version and is incremented when a backwards incompatible change to iris is made.\n- *y* is the MINOR version and is incremented when a backwards compatible change to iris is made, like changing dependencies or adding a new function, method, struct field, or type.\n- *z* is the PATCH version and is incremented after making minor changes that don't affect iris's public API or dependencies, like fixing a bug.\n\n\u003cbr\u003e\n\n## 📄 License\nLicense\n© 2021-Present Shravan Asati\n\nThis repository is licensed under the MIT license. See [LICENSE](LICENSE) for details.\n\n\u003cbr\u003e\n\n## 👥 Contribution\nPull requests are more than welcome. For more information on how to contribute to *iris*, refer [CONTRIBUTING.md](CONTRIBUTING.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshravanasati%2Firis","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fshravanasati%2Firis","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshravanasati%2Firis/lists"}