chezmoi.io

What is chezmoi?

chezmoi is a command-line tool for managing "dotfiles"—the configuration files that define your shell, editor, Git, and other personal settings—across multiple machines. Its focus is doing this securely and consistently, so the same setup can follow you from a laptop to a desktop to a server without manual copying.

What it actually does

• Tracks your dotfiles in a single source directory and applies them to a target home directory.
• Handles machine-to-machine differences, so one machine can get a slightly different version of a file without you maintaining separate copies.
• Supports templating, letting files adapt to variables like hostname, OS, or environment.
• Can pull in files from elsewhere and run scripts as part of applying changes.
• Integrates with password managers and encryption tools for secrets that shouldn't sit in plain text.

Who it's for

It suits people who work on more than one machine and are tired of drift between them: developers with a laptop and a work desktop, sysadmins managing several servers, or anyone who wants their environment reproducible after a reinstall. If you only ever use one computer and rarely change settings, a simpler approach may be enough.

How it compares

According to the project's own documentation, it also provides a comparison table and a migration path from other dotfile managers, which is useful if you're already using one.

Next step

Start with the quick start guide at chezmoi, then run chezmoi init on a second machine to see how the same source state lands differently there. That single test will tell you quickly whether its templating and per-machine model match how you actually work.

How do I install and set up chezmoi on a new machine?

You install chezmoi as a single binary, then point it at your existing dotfiles repository and let it apply them. On a brand-new machine the usual flow is: install the binary, run chezmoi init with your repo URL, inspect what it wants to change with a dry run, then apply.

Typical first-run sequence

1. Install chezmoi using your platform's package manager, a downloaded binary, or the install script from chezmoi.
2. Run chezmoi init <your-repo-url> (or chezmoi init if you already have a local source directory). This clones your dotfiles repo into chezmoi's source directory.
3. Run chezmoi diff to see exactly what would change in your home directory before anything is written.
4. Run chezmoi apply to write the files.
5. Run chezmoi doctor to check for missing tools, permissions or environment problems.

What "setup" actually involves

chezmoi separates the source state (your repo) from the target state (your home directory). Files are stored with naming conventions rather than raw paths, so a file like dot_bashrc in the source becomes ~/.bashrc on the target. This is why you shouldn't edit managed files directly — running chezmoi apply will overwrite those edits. To change a managed file, use chezmoi edit <file> or chezmoi add <file> so the change lands in the source and can be committed.

Handling machine-to-machine differences

The reason chezmoi init matters more than a plain git clone is templating and per-machine data. Your repo can contain templates that branch on hostname, OS or a data file, so the same source produces a work laptop config and a personal desktop config. If you have machine-specific settings, put them in a local config file (chezmoi edit-config) or a data file rather than hard-coding them.

A practical decision criterion

Next step

After the first successful chezmoi apply, commit and push from the source directory so the new machine's state is reproducible, then test on a second machine or container before trusting it. If something looks wrong, chezmoi diff and chezmoi status are the fastest ways to see what differs without changing anything.

How does chezmoi keep my dotfiles secure when syncing across multiple machines?

chezmoi keeps dotfiles secure by storing your source state in a Git repository (or another version control system you choose), so the sensitive files themselves are never sent to a chezmoi server. The tool is designed around a source directory that you control, and it supports encryption of individual files before they are committed. For files you mark as encrypted, chezmoi uses external encryption tools such as age, GPG, or rage, so the encrypted version is what lives in your repository and what gets synced between machines. On a new machine, chezmoi decrypts those files locally during apply using your private key or passphrase, which means the plaintext never leaves your machine.

For secrets that should not be stored even in encrypted form, chezmoi can pull values at apply time from password managers and secret stores, including 1Password, Bitwarden, KeePassXC, AWS Secrets Manager, Azure Key Vault, and others. It also supports templating, so you can keep a single dotfile template that references a secret and let chezmoi resolve it per machine. This keeps the repository free of long-lived credentials while still letting each machine produce a complete config.

A practical example: you keep ~/.gitconfig as a chezmoi template that reads your work email from a password manager and your personal email from a different source, so the same repository works on both a work laptop and a home machine without either seeing the other's secrets. The trade-off is that you must manage your encryption keys and password-manager access separately; chezmoi does not provide its own key storage or cloud vault.

To decide whether this fits you, ask: do you already use Git and an encryption tool or password manager? If yes, chezmoi's model adds little new risk. If you want a single tool that handles both syncing and secret storage, you will need to pair chezmoi with one of the supported backends. Start by reading the encryption and password-manager sections of the official documentation at chezmoi.

How do I manage machine-specific differences in dotfiles with chezmoi?

chezmoi handles machine-specific differences through templates and conditional data, so one source of truth can produce different files on each machine. The core idea: your dotfiles live in a source directory, and chezmoi renders them per machine before applying.

The main mechanisms

• Templates: Files with the .tmpl extension are rendered with Go templates. You can wrap machine-specific blocks in conditionals so they only appear where relevant.
• Data sources: Template variables come from chezmoi's built-in data (hostname, OS, architecture, username, environment) and from your own data files (.chezmoidata files and .chezmoidata/ directory), which you can vary per machine.
• .chezmoiignore: Controls which files are applied on which machines, useful when a file should exist only on some hosts.
• Scripts: .chezmoiscripts/ runs actions at defined points, handy for machine-specific setup steps rather than file content.

A practical pattern

Put shared content in a template, then branch on a variable you control:

{{ if eq .chezmoi.hostname "work-laptop" }}
export WORK_MODE=1
{{ end }}

For larger differences, define per-machine values in a data file and reference them, rather than scattering hostname checks everywhere. That keeps templates readable and makes it obvious what varies.

Deciding between approaches

Next step

Start small: pick one file that differs between two machines, convert it to a .tmpl, and replace the differing line with a conditional based on .chezmoi.hostname. Verify with chezmoi diff before applying, then expand to data files once you have more than a couple of variables. Full details are in the project's templating and machine-to-machine documentation at chezmoi.

Can I migrate my existing dotfiles from another dotfile manager to chezmoi?

Yes. chezmoi is designed to manage dotfiles across multiple machines, and its documentation includes a dedicated "Migrating from another dotfile manager" section, so moving an existing setup is an expected path rather than a workaround.

What migration typically involves

You usually keep your existing dotfiles where they are and let chezmoi take over management of them, rather than rewriting everything by hand. In practice the steps look like:

1. Install chezmoi and run its init step to create a source directory.
2. Add your existing files to chezmoi's management, either one at a time or by importing a directory.
3. Check the diff before applying anything, so you can confirm chezmoi will produce the files you expect.
4. Apply and verify that your shell, editor and other tools still behave as before.
5. Retire the old manager once you are confident — the docs even cover how to migrate away from chezmoi later, which is a useful safety signal.

Practical things to watch

• Templating differences. chezmoi uses templates for machine-to-machine variation. If your old manager used a different syntax or a separate host-specific file scheme, those conditionals need translating.
• Secrets handling. chezmoi integrates with password managers and encryption tools rather than storing secrets in plain text. If your current setup keeps secrets in the repo, plan how they move.
• File types. Dotfiles are not only plain files: symlinks, permissions, directories and executables all have their own handling, and mismatches here are the usual source of surprise.
• Scripts and hooks. Anything your old manager ran on apply or update needs an equivalent, or it silently stops happening.

A concrete scenario

Suppose you manage a laptop and a work desktop with a host-specific branch in your current tool. You would add the shared files to chezmoi once, then express the differences as templates or per-machine data. On the work machine you run a diff first, confirm only the intended files change, then apply. That ordering is what keeps a migration boring.

Where to start

Read the migration guide alongside the quick start on chezmoi, then do the move on one machine before touching the rest. If you want a comparison point for the wider ecosystem, GitHub hosts many dotfile repositories you can inspect for structure ideas, though you should treat them as examples rather than recommendations.

How do I upgrade chezmoi to the latest version?

Upgrade chezmoi with its built-in command:

chezmoi upgrade

This is the intended path per the project's own reference, which lists a dedicated upgrade command. It replaces the running binary rather than touching your dotfiles, so your source directory and managed files are unaffected.

The practical catch is how you installed it. If you used a package manager — Homebrew, apt, dnf, Scoop, Chocolatey — that manager owns the binary, and you should upgrade through it instead (brew upgrade chezmoi, sudo apt upgrade chezmoi, and so on). Running chezmoi upgrade on a package-managed install can leave the package database disagreeing with what is actually on disk. If you installed from a release archive or script, chezmoi upgrade is the clean route.

A concrete scenario: you manage dotfiles on a laptop and a work server. On the laptop, Homebrew handles it; on the server, you unpacked a tarball, so you run chezmoi upgrade there. After either, confirm with chezmoi --version and chezmoi doctor, which flags version and environment problems in one pass.

If you are pinning versions deliberately across machines, skip the upgrade entirely and stay consistent — mixed versions are a more common source of confusion than old ones. See chezmoi for the command reference and install options.