Manage your dotfiles with mise

Manage your dotfiles with mise

Mise (“meez”) has become my favorite way to define developer tools required by a project in a declarative way (like a Dev Container, without the overhead). Think of it as a package-manager-manager, like what nvm does for Node.js, along with a dependency manager, like npm. Mise can also be used to configure your environment (like direnv), and define tasks, like a Makefile. It is by far the best tool I’ve used to make developer on-boarding as smooth as possible.

Today, mise has released version v2026.6.6, titled “Declarative machine bootstrap”. The release is focused on tooling meant to configure your whole machine in a declarative way, rather than a single project. This article focuses on the dotfiles side of the update.

Dotfiles with mise

See the full documentation: https://mise.jdx.dev/dotfiles.html

TL;DR

  • Track your dotfiles in a dedicated git repo
  • Declare your dotfiles inside mise.toml
  • Configure the dotfile deployment strategy per component
  • Use variables for machine-specific configs
[settings]
dotfiles.root = "~/.dotfiles"

[dotfiles]
"~/.zshrc" = {} # Links to ~/.dotfiles/.zshrc
"~/.config/nvim" = "nvim" # Links to ~/.dotfiles/nvim/
"~/.config/starship.toml" = { source = "starship/starship.toml" }

Commands

Here are the two main commands:

  • mise dotfiles status - lists all the dotfiles that you are tracking, and whether they have been deployed or not.

  • mise dotfiles apply - Apply dotfiles. You will need to use --force if there are conflicts. Can be run in --dry-run mode to see what would be applied.

There are more commands and options. Run mise dotfiles --help for details.

Modes

mise currently offers 4 modes to manage the files:

  • symlink: Creates a symlink from the source to the target. This can link a folder or a file.
  • symlink-each: Symlinks individual files inside a folder. This is great for dotfiles where you want to add custom files, but don’t want to track the whole folder. I use this option for zsh-custom with oh-my-zsh.
  • copy: copies the file instead of creating a symbolic link.
  • template: Uses mise template engine to inject machine-specific values. This gets mise closer to the richer features advanced dotfiles tools offer.

Thoughts

While there are many ways to manage your dotfiles, managing your configuration files in a git repo is generally the best way to make your environment consistent across machines. See awesome-dotfiles for all the crazy ways you can manage your config files.

I currently use a very lean setup with GNU Stow, similar to this setup from Dreams of Autonomy. It only requires stow as a dependency, which is available on most Linux distributions, making the setup very portable. However, I have been unhappy with a few limitations of Stow that have forced me to use hacky workarounds.

mise offers a very compelling solution that’s fully declarative, git-friendly, and works across major OSes. It strikes a good balance between the simplicity of a lean setup (custom scripts, stow), and the flexibility of a more advanced dotfiles tool (like chezmoi, or even setups using Ansible or Nix).

I’ve made the switch, and while my dotfiles setup is now slightly more complex than just using Stow (extra step to configure mise, extra configuration for mise.toml), I’m happy with the trade-off.

Other features

I’m still exploring other recent mise features for machine management, and will likely adopt them too:

  • mise bootstrap: install machine-global system packages. It supports major package managers like apt, brew, dnf, and pacman.
  • macOS defaults: declarative configuration for your macOS settings, like disabling auto-correction.

How do you currently manage your dotfiles?

Do you use mise for your projects, or something else?

Feel free to share your recommendations in the comments.