created_at2023-08-06 20:40:24.562685
updated_at2024-02-17 04:47:00.701112
descriptionA theme mangager for LeftWM




A theme manager for LeftWM

build status


Currently, LeftWM-theme is only available by Git and AUR.

To install by AUR (Arch-based distributions only), use package leftwm-theme-git.

To install manually, clone this repository:

git clone https://github.com/leftwm/leftwm-theme

Then enter the repository:

cd leftwm-theme

Then build with Cargo:

cargo build --release

You can then install LeftWM-theme:

# for production installations (does not update when recompiled)
sudo install -s -Dm755 ./target/release/leftwm-theme -t /usr/bin
#-- or --
# for developer installations (updates when recompiled)
sudo ln -s "$(pwd)"/target/release/leftwm-theme /usr/bin/leftwm-theme


First use

The first time you start up LeftWM-theme, it will generate a file called themes.toml in your ~/.config/leftwm/ folder from the themes located in the Community Themes repo. To do so, run:

leftwm-theme update

Install a theme

LeftWM-theme differentiates between installing a theme and applying a theme. Installing a theme is akin to downloading it; behind the scenes LeftWM-theme runs git clone {theme}. No dependency checks are performed at installation time, but instead at application time. To install a theme, for example the fabulous Orange Forest theme, run (quotation marks needed for names with spaces):

leftwm-theme install "Orange Forest"

Note: LeftWM-theme is CaSe SeNsItIvE, so be careful!

Apply a theme

LeftWM-theme will check for dependencies, LeftWM-version, and the like during the application process. Now that you've installed Orange Forest (or whatever theme you like), to set it as your current theme, run:

leftwm-theme apply "Orange Forest"

Note: LeftWM should automatically restart with the new theme

List installed themes

To list all installed themes that LeftWM-theme knows about, run:

leftwm-theme list

See current theme

Although multiple commands list the installed theme, using the following can provide additional context:

leftwm-theme status

Update theme list

To update your copy of the themes, use the following:

leftwm-theme update

Note: this does not also update the themes, just the repository listings! To update themes see upgrade

Updating themes

To update themes, use the following:

leftwm-theme upgrade

Note: this command also updates repositories

Adding a repository

Leftwm-theme allows multiple known.toml repositories to be used. To add another repository, it must have a known.toml file which you can add to themes.toml in your LeftWM config folder.

Note: It is wise to backup your themes.toml file PRIOR to adding a new repostitory

To add a repository, add the following to the BOTTOM of your themes.toml file, located at ~/.config/leftwm/themes.toml:

# To add additional repos, you MUST specify a url, a UNIQUE ALPHANUMERIC name, and an empty array of themes
# e.g.:
# [[repos]]
# url = "https://raw.githubusercontant.com/mautamu/leftwm-community-themes/master/known.toml"
# name = "mautamu"
# themes = []
url = ""
name = ""
themes = []

Note: be sure that the url points to a file called known.toml, such as https://raw.githubusercontent.com/leftwm/leftwm-community-themes/master/known.toml

Then fill in the url with the url of that repo and add a descriptive name that consists of only letters and numbers [A-z0-9]. To load themes from the repository, use the following:

leftwm-theme -vvv update

Note: the -vvv flag is not necessary, but will provide additional output in case your new repo goes wrong


Themes.toml is nearly empty, and/or LeftWM won't update my themes:

Try removing themes.toml and running the update command, add any repositories that were removed, and then run autofind to repopulate your installed themes.

I can't get a theme to install

Double check your name. Although update may say mautam/theme, you just need to type theme, not mautam/theme. Pay attention to capital letters and spelling.


Version 0.1.0

  • Allow users to install themes
  • Allow users to remove themes
  • Allow a theme to be applied as current
    • Check dependencies for a theme
    • Allow dependency override with -n
    • Offer suggestions for dependency installation
    • Check whether a theme's theme.toml file is valid
  • Allow themes to specify compatible LeftWM versions
  • Find themes located in ~/.config/leftwm/themes/ automatically
  • Allow users to add more theme repositories
    • Allow users to choose from which repository to install themes
  • Allow users to create new themes
    • Provide basic themes for users to fork into their own
    • Generate appropriate known.toml pull requests and theme.toml files
    • Make sure themes don't include / or other OS-specific marks. Partially complete
  • Allow users to update their repository theme lists with update as in apt-get form
  • Allow users to update their themes with upgrade command, as in apt-get form
    • Allow users to skip repo update
    • Perform dependency checks prior to updating the current theme
  • Allow users to search for themes by name

Version 0.2.0

  • Extend theme.toml to allow for up/down specifications within theme.toml

  • Integrate themes.toml and known.toml better

  • Reduce the number of dependencies

    • Replace Reqwest with a crate with fewer dependencies
    • Examine other areas of overlapping features
  • Provision for name aliases for dependencies in different distros

  • Improve documentation

  • Better, more consistent error handling

  • Remove nightly Rust requirement by replacing ? on Options

  • Add a testing suite

Commit count: 99

cargo fmt