Guide · Open source
How to use chezmoi: manage dotfiles across machines
Updated · written with AI from the project's own documentation and checked against our catalogue data
chezmoi is an open-source command-line tool for keeping personal configuration files, such as shell and editor settings, in sync across several computers. This guide explains the basic model: you keep the desired versions in a source directory, and chezmoi applies them to each machine. It is written for people who use more than one computer and want their settings to match.
chezmoitwpayne/chezmoi · ★ 22.1k · MIT Install options & downloads Quick start
- 1Confirm you need it. Check that you use more than one computer and want shared config files. A single machine with few dotfiles may not justify the setup.
- 2Install with your package manager. Install chezmoi using a package manager on macOS, Linux or Windows. Follow the instructions at https://www.chezmoi.io/ for your system.
- 3Read the documentation. The README points to the documentation site for details. Read it before you start, since the README gives little beyond the tagline.
- 4Set up your source directory. Keep the desired versions of your dotfiles in the source directory, as described in the documentation.
- 5Apply to each machine. Use chezmoi to apply the source files to each computer, letting it adapt them where machines differ.
- 6Check secrets handling. Confirm in the documentation how secrets are handled before storing any sensitive values.
What chezmoi does and who it is for
chezmoi manages dotfiles, the configuration files in your home directory such as shell and editor settings. You store the desired versions in a source directory, and chezmoi applies them to each machine, adapting them where machines differ.
The project describes its purpose as managing dotfiles across multiple diverse machines, securely. The README says little beyond that tagline and points to the documentation site for details.
- Best for people who use more than one computer and want their settings to match
- Useful for developers who keep shell, editor and git configs under version control
- Runs on macOS, Linux or Windows, which the project topics list as supported platforms
- Not a good fit if you use a single machine with few config files, since setup may not pay off
- Not a point-and-click settings app; it is a command-line tool
Install chezmoi with a package manager
The source gives the install method as a package manager. The README does not list install commands or prerequisites, so check the official documentation at https://www.chezmoi.io/ for the exact steps for your operating system.
Understand the source directory and apply step
The core idea is a source directory that holds the desired state of your configuration files. chezmoi reads that directory and applies the files to each machine, adapting where they differ.
The source describes this model only at a high level. For the directory layout and the exact commands, use the documentation site.
Check the secrets handling before you rely on it
The project describes chezmoi as a way to manage dotfiles securely. The README does not explain how secrets are handled, so do not assume any particular behaviour from the tagline.
Read the documentation on secrets before you store any credentials or private values with chezmoi.
Compare chezmoi with similar tools
Comparable projects include GNU Stow, yadm, rcm and Dotbot. All of them help manage dotfiles, so choose based on how each one fits your workflow and the documentation for each.
What people use it for
- Keep shell settings matching across a laptop and a desktop
- Version control editor and git configuration for a developer
- Apply one set of dotfiles to several machines that differ slightly
Frequently asked questions
Is chezmoi free?
Yes. chezmoi is released under the MIT licence, which is a permissive open-source licence. Check the LICENSE file in the repository for the full terms.
What operating systems does chezmoi support?
The project topics list macOS, Linux and Windows as supported platforms. The README itself does not give more detail, so check the documentation for specifics.
What language is chezmoi written in?
chezmoi is written in Go. Go is a common language for command-line tools.
How do I install chezmoi?
The source lists a package manager as the install method. The README does not give install commands, so follow the instructions on https://www.chezmoi.io/.
How does chezmoi handle secrets?
The README describes chezmoi as a way to manage dotfiles securely but does not explain how secrets work. Read the documentation before storing sensitive values.
What are alternatives to chezmoi?
Comparable projects include GNU Stow, yadm, rcm and Dotbot. Each takes a different approach to managing dotfiles, so compare them against your needs.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
chezmoi suits people who work across several computers and want their dotfiles to match, especially developers who already version control their configs. If you use one machine with few config files, or want a graphical settings app, pick something simpler or a different tool. The README is thin, so read the documentation at chezmoi.io before deciding.
Install options & downloads