Skip to main content
The upgrade command upgrades chezmoi to the latest released version from GitHub.

​
Usage

chezmoi upgrade

​
Description

The upgrade command automatically downloads and installs the latest stable version of chezmoi from the official GitHub releases. The upgrade method is automatically detected based on how chezmoi was installed. After upgrading, the new chezmoi version is executed with the --version flag to verify the upgrade was successful.

​
Upgrade Methods

chezmoi automatically detects the appropriate upgrade method:
  • replace-executable: Direct binary replacement (most common)
  • brew-upgrade: Homebrew on macOS/Linux
  • snap-refresh: Snap on Linux
  • winget-upgrade: Windows Package Manager
  • upgrade-package: Package manager on Linux (APT, DNF, etc.)
Use chezmoi doctor to see which upgrade method will be used.

​
Flags

​
--executable
string
Path to the executable to replace. By default, uses the currently running chezmoi executable.
​
--method
string
Force a specific upgrade method. Options: replace-executable, brew-upgrade, snap-refresh, winget-upgrade, upgrade-package. If not specified, the method is automatically detected.

​
Examples

​
Upgrade to latest version

chezmoi upgrade

​
Force upgrade even if already on latest version

chezmoi upgrade --force
Useful for reinstalling or fixing a broken installation.

​
Upgrade with specific method

chezmoi upgrade --method=replace-executable

​
Check what method will be used

chezmoi doctor | grep upgrade-method

​
Terminal Output

​
Successful upgrade

$ chezmoi upgrade
Downloading chezmoi v2.47.0...
Installing...
chezmoi version v2.47.0, commit abc1234def5678, built at 2024-01-20T10:30:00Z

​
Already on latest version

$ chezmoi upgrade  
chezmoi: already at the latest version (v2.47.0)

​
Forced upgrade

$ chezmoi upgrade --force
Downloading chezmoi v2.47.0...
Installing...
chezmoi version v2.47.0, commit abc1234def5678, built at 2024-01-20T10:30:00Z

​
Platform-Specific Behavior

​
Linux

On Linux, chezmoi determines whether to use:
  • glibc or musl builds (for x86_64)
  • Package managers (if installed via APT, DNF, etc.)
  • Snap (if installed via Snap)
  • Direct binary replacement

​
macOS

On macOS:
  • Uses Homebrew if chezmoi was installed via brew
  • Otherwise replaces the binary directly

​
Windows

On Windows:
  • Uses WinGet if available
  • Otherwise downloads and replaces the .exe file
  • The old executable is renamed to chezmoi.exe.old

​
Automation

​
Automatic updates with cron

# Check for updates daily
0 0 * * * /usr/local/bin/chezmoi upgrade

​
Systemd timer

# /etc/systemd/system/chezmoi-upgrade.service
[Unit]
Description=Upgrade chezmoi

[Service]
Type=oneshot
User=username
ExecStart=/usr/local/bin/chezmoi upgrade

# /etc/systemd/system/chezmoi-upgrade.timer  
[Unit]
Description=Weekly chezmoi upgrade

[Timer]
OnCalendar=weekly
Persistent=true

[Install]
WantedBy=timers.target
Enable: 
systemctl enable --now chezmoi-upgrade.timer

​
Upgrade notification script

#!/bin/bash
current_version=$(chezmoi --version | awk '{print $3}' | cut -d'v' -f2)
latest_version=$(curl -s https://api.github.com/repos/twpayne/chezmoi/releases/latest | \
                 grep '"tag_name":' | cut -d'"' -f4 | cut -d'v' -f2)

if [ "$current_version" != "$latest_version" ]; then
    echo "Chezmoi update available: v$current_version -> v$latest_version"
    echo "Run 'chezmoi upgrade' to update"
fi

​
Troubleshooting

​
Permission denied

If you get a permission error: 
# Make sure you have write permission
ls -l $(which chezmoi)

# If installed system-wide, use sudo
sudo chezmoi upgrade

# Or install to user directory
chezmoi upgrade --executable ~/.local/bin/chezmoi

​
Cannot determine upgrade method

$ chezmoi upgrade
error: linux/amd64: cannot determine upgrade method for /usr/local/bin/chezmoi
Specify the method explicitly: 
chezmoi upgrade --method=replace-executable

​
Network errors

If GitHub is unreachable: 
# Check network connectivity
curl -I https://api.github.com

# Use a proxy if needed
export HTTPS_PROXY=http://proxy.example.com:8080
chezmoi upgrade

​
Dev version warning

$ chezmoi upgrade
error: cannot upgrade dev version to latest released version unless --force is set
If you’re running a development build, use --force: 
chezmoi upgrade --force

​
Manual Upgrade

If automatic upgrade fails, manually download from GitHub: 
# Linux x86_64
curl -sfL https://github.com/twpayne/chezmoi/releases/latest/download/chezmoi-linux-amd64.tar.gz | \
  tar -xz -C ~/.local/bin

# macOS ARM64
curl -sfL https://github.com/twpayne/chezmoi/releases/latest/download/chezmoi-darwin-arm64.tar.gz | \
  tar -xz -C ~/.local/bin

# Verify
chezmoi --version

​
Upgrade via Package Managers

​
Homebrew

brew update
brew upgrade chezmoi

​
Snap

sudo snap refresh chezmoi

​
APT (Ubuntu/Debian)

If installed from PPA: 
sudo apt update
sudo apt upgrade chezmoi

​
Pacman (Arch Linux)

sudo pacman -Syu chezmoi

​
Scoop (Windows)

scoop update chezmoi

​
Downgrading

If you need to downgrade: 
# Find the version you want
chown +x install.sh

# Install specific version
sh -c "$(curl -fsLS get.chezmoi.io)" -- -b ~/.local/bin v2.46.0

​
Checking for Updates

​
Check current version

chezmoi --version

​
Check latest version

curl -s https://api.github.com/repos/twpayne/chezmoi/releases/latest | \
  grep '"tag_name":' | cut -d'"' -f4

​
Compare versions

chezm doctor | grep -E "(version|latest-version)"
  • doctor - Check upgrade method and version

Build docs developers (and LLMs) love

Get started for freeTalk to us