Skip to main content

atmos toolchain uninstall

Uninstall specific tool versions or all tools from your local toolchain cache. This frees up disk space while keeping your toolchain configuration intact for future installations.

atmos toolchain uninstall --help

Usage​

Execute the atmos toolchain uninstall command like this:

atmos toolchain uninstall [tool@version]

If no tool is specified, uninstalls all tools from .tool-versions.

Examples​

Uninstall Specific Version​

atmos toolchain uninstall terraform@1.9.8

Example output:

Uninstalling terraform@1.9.8...
  Removed: .tools/bin/hashicorp/terraform/1.9.8/terraform (85.2 MB)

Successfully uninstalled terraform@1.9.8

Uninstall Tool (All Versions)​

atmos toolchain uninstall terraform

Removes all installed versions of terraform.

Uninstall Using Full Path​

atmos toolchain uninstall hashicorp/terraform@1.9.8

Uninstall All Tools​

atmos toolchain uninstall

Uninstalls all tools listed in .tool-versions. Prompts for confirmation.

Force Uninstall​

atmos toolchain uninstall --force terraform@1.9.8

Skips confirmation prompt.

Arguments​

tool[@version] (optional)

Tool to uninstall. Can be a short name (alias) or full owner/repo format. Include @version to uninstall a specific version. If omitted, uninstalls all tools from .tool-versions.

Examples: terraform, terraform@1.9.8, hashicorp/terraform@1.9.8

Flags​

--force (optional)

Skip confirmation prompt and immediately uninstall.

Environment variable: ATMOS_TOOLCHAIN_FORCE

--keep-config (optional)

Keep the tool entry in .tool-versions after uninstalling. Default: true

Use --keep-config=false to also remove from .tool-versions.

Environment variable: ATMOS_TOOLCHAIN_KEEP_CONFIG

--dry-run (optional)

Show what would be uninstalled without actually removing anything.

Environment variable: ATMOS_TOOLCHAIN_DRY_RUN

Use Cases​

Free Up Space for Specific Tool​

Remove old versions to save disk space:

# Check what's installed
atmos toolchain list

# Remove old version
atmos toolchain uninstall terraform@1.8.5

# Keep only current version
atmos toolchain list

Switch Between Versions​

Uninstall before installing a different version:

# Remove current version
atmos toolchain uninstall opentofu@1.9.0

# Install new version
atmos toolchain install opentofu@1.10.3

Clean Up After Testing​

Remove tools installed for testing:

# Uninstall test tools
atmos toolchain uninstall tflint@0.44.0
atmos toolchain uninstall tfsec@1.28.0

# Or remove from config too
atmos toolchain uninstall --keep-config=false tflint

Preview Before Uninstalling​

Check what would be removed:

# Dry run
atmos toolchain uninstall --dry-run terraform@1.8.5

# If satisfied, actually uninstall
atmos toolchain uninstall terraform@1.8.5

CI/CD Cleanup​

Clean up after pipeline runs:

# Uninstall all without prompts
atmos toolchain uninstall --force

Difference from Clean​

CommandPurposeKeeps .tool-versionsSelective
uninstallRemove specific toolsYes (default)Yes
cleanRemove all tools and cacheYesNo
# uninstall - selective removal
atmos toolchain uninstall terraform@1.8.5

# clean - removes everything
atmos toolchain clean

Notes​

  • By default, the tool entry remains in .tool-versions for easy reinstallation
  • Use --keep-config=false to also remove from .tool-versions
  • Running atmos toolchain install will reinstall any tools still in .tool-versions
  • Use atmos toolchain remove to only remove from .tool-versions without uninstalling