🎨 (Neo)pywal for (Neo)vim

Neopywal.nvim is a Neovim colorscheme plugin that automatically fetches and applies the colors that are auto generated by Pywal, featuring plenty of configuration options and support for various plugins within the Neovim ecosystem.

Important

Neopywal is under the process of a documentation update, so until v3.0.0 is released, expected slightly outdated documentation, or even slightly broken vim :h neopywal pages.

✨ Features

• Highly configurable with ability to change color definitions and highlight groups.
• True color support for terminals.
• Importable and customizable color palette.
• Fail safe fallback theme if required palette files can't be loaded.
• Supports Pywal and Wallust.
• Automatic reloading of colorscheme with Pywal theme changes.
• Support for LSP, treesitter and a bunch of plugins.
• Enhanced syntax highlighting for fileformats (without treesitter).
• Compiled user's configuration for fast startup times.
• Interactive mode for live config re-loading.

📦 Installation

lazy.nvim

{
    "RedsXDD/neopywal.nvim",
    name = "neopywal",
    lazy = false,
    priority = 1000,
    opts = {},
}

packer.nvim

use { "RedsXDD/neopywal.nvim", as = "neopywal" }

mini.deps

now(function()
    add({
        source = "RedsXDD/neopywal.nvim",
        name = "neopywal",
    })
end)

vim-plug

Plug "RedsXDD/neopywal.nvim", { "as": "neopywal" }

🚀 Usage

To activate the theme, add the following to your Neovim config:

local neopywal = require("neopywal")
neopywal.setup()
vim.cmd.colorscheme("neopywal")

Or call the colorscheme with vim script:

colorscheme neopywal

Note

Make sure to run :colorscheme neopywal or vim.cmd.colorscheme("neopywal"), otherwise the colorscheme won't be loaded.

Alternative Variants

Neopywal can also take advantage of Neovim's vim.o.background option (see :h background) to dynamically adjust the color palette on the fly. This allows you to switch between a light and dark colorscheme, even when Pywal generates a dark palette.

colorscheme neopywal-dark
" or
colorscheme neopywal-light

Note that, by default, when loading the colorscheme with the standard :colorscheme neopywal command, Neopywal will automatically detect and load the corresponding colorscheme variant based on the current value of vim.o.background.

Note on Light Theme

When loading the "light" theme variant, Neopywal won't generate any new colorscheme palette. Instead, it loads the existing palette (used by the neopywal-dark variant) and inverts the background and foreground color variables (check here for more information those variables). This may not produce the best results when comparing to an actual auto generated light theme variant, but it's generally good enough.

To use a genuine light theme with Neopywal, generate a new colorscheme with Pywal while using the -l flag.

wal -l -i /path/to/your/image

📖 Documentation

Starting from Neopywal v3.0.0, all the customization options and their explanations can be found in the docs/ directory. This allows for a cleaner and easier way to read all of Neopywal's documentation.
You can also look at the documentation within Neovim itself, by running commands such as:

:help neopywal

If you just want some quick links to a certain documentation file, here they are:

• Neopywal's Configuration Options
• Enabling Fileformat Highlights
• List/Usage of Supported Plugins
• Palette Variants/Configuration
• Customizing Colors
• Customizing Highlight Groups
• Additional Utility Functions

💾 Compilation

Neopywal can pre-compute your configuration and store the results in a compiled lua file stored into the system's cache directory, which then gets loaded when the colorscheme is applied. This approach greatly improves performance and reduces the total execution time.

Note that you can always manually recompile Neopywal with the :NeopywalCompile command. But that shouldn't be needed since Neopywal is capable of automatically recompiling the colorscheme when any change is detected on the user configuration or when a new theme is generated by Pywal.

🪄 Interactive Mode

Neopywal allows for an easy way to make changes to it's config and see the results live by exposing the command :NeopywalInteractive.

This command will attach an autocmd to the current buffer that executes on BufferWritePost. The autocmd will clear Neopywal's internal state and re-compute it's config from the newly saved file. Which in turn will update the colorscheme accordingly.

There are a few things to note:

• This requires executing luafile on the current file. Any syntax errors will throw errors.
• If you are using packer and have Neopywal's config in a config = function() end block, this will not work as packer would require to be re-compiled and the compiled file sourced.

🔥 Acknowledgments

• Pywal.nvim (The original project from where Neopywal started and was built on top of).
• Catppuccin (Inspiration of code base structure).
• Nightfox (For the interactive mode).
• Dylanaraps (For creating pywal itself).
• Eylles (For maintaining Pywal16, a fork of Pywal that can generate 16 colors instead of 8).
• Explosion Mental (For creating/maintaining Wallust, a modern replacement for Pywal written in Rust).

📜 Notes

Important

Neopywal has changed some of it's configuration options starting from v3.0.0, which may lead to some breakages. Please take a look at the changed options below and how to fix any issues related to them.

custom_colors and custom_highlights

🎨 Custom_colors and Custom_highlights

Starting from v3.0.0, the custom_colors and custom_highlights have been changed so that they can support individual configuration options for each of Neopywal's theme variants. Before this update, you could just change whichever values you wanted within the config tables themselves similar to how it is shown below:

require("neopywal").setup({
    custom_colors = {
        mycustomcolor = "#ff0000",
    },
    custom_highlights = {
        mycustomhighlight = { bg = "#000000", fg = "#ff0000" },
    }
})

These options have been changed so that they can support individual configuration tables for each of Neopywal's theme variants as shown below:

require("neopywal").setup({
    -- In this configuration,
    -- `myglobalcolor` will be available globally to both theme variants,
    -- `mydarkcolor` will only be available on the dark theme variant,
    -- `mylightcolor` will only be available on the light theme variant.
    custom_colors = function (C)
        return {
            all = { myglobalcolor = C.color1 },
            dark = { mydarkcolor = C.color2 },
            light = { mylightcolor = C.color3 },
        }
    end,

    -- The same kinds of options are available to `custom_highlights`
    -- custom_highlights can also be set to a function itself just like custom_colors.
    custom_highlights = {
        all = function(C) return { myglobalhighlight = { bg = C.color1 } } end,
        dark = { mydarkhighlight = { bg = "#00ff00" } },
        light = { mylighthighlight = { bg = "#ffff00" } },
    },
})

That basically means that, if you want your old highlights and colors configurations to work without doing much work, you can just warp them around an all table and/or be able to do a finer control of them using the added dark and light table options.

require("neopywal").setup({
    custom_colors = {
        all = {
            mycustomcolor = "#ff0000",
        },
        dark = {}, -- Custom colors for dark theme variant ...
        light = {}, -- Custom colors for light theme variant ...
    },
    custom_highlights = {
        all = {
            mycustomhighlight = { bg = "#000000", fg = "#ff0000" },
        },
        dark = {}, -- Custom highlights for dark theme variant ...
        light = {}, -- Custom highlights for light theme variant ...
    },
})

For more information on how to use these options, take a look at their respective docs/ files:

• Customizing Colors
• Customizing Highlight Groups

Colorscheme_file and use_wallust

🎨 Colorscheme_file and use_wallust

Starting from v3.0.0, the colorscheme_file and the use_wallust options have been entirely replaced by the use_palette option.
If you want to use the Wallust generated colorscheme palette file, here's how you do it:

require("neopywal").setup({
    use_palette = "wallust",
})

Likewise, here's how you would use this option if you wanted to use a custom builtin palette from Neopywal itself:

require("neopywal").setup({
    use_palette = "doomone",
})

The use_palette option supports some additional configuration that you can check out here.

Important

Officially deprecated Pywal.

As of April 26, 2024, Pywal's repository has been archived, making the project officially deprecated. Meaning it's not recommended to use it.
You can look for alternatives that will work with Neopywal in the following section.

😍 Enjoy

Neopywal is a solo developed hobby project, however if you do like this work you can give this project a star ⭐
And if you really like the project and would like to help it grow, you can always send a PR modifying any part of the source code to your heart's content, any contributions are welcomed and are greatly appreciated ;D