How to Uninstall mise Tools: Complete Command Reference

Use mise uninstall to selectively remove installed tool versions while preserving your mise.toml configuration and automatically refreshing shims.

The mise uninstall command in the jdx/mise repository provides a structured way to delete tool binaries and clean up runtime environments. Unlike manual file deletion, this command ensures consistency across backends, updates shell shims, and supports dry-run validation for automation workflows.

Three Modes for Uninstalling Tools

The implementation in src/cli/uninstall.rs supports three distinct operational modes depending on your cleanup requirements.

Single Version Removal

Specify a tool and optional version to remove a specific installation. If you omit the version and only one version exists, mise automatically selects that version.

This mode parses the tool argument through ToolArg (lines 20–34), resolves the appropriate backend, and matches installed versions using get_requested_tool_versions.

# Remove specific Node.js version

mise uninstall node@18.0.0

# Remove the only installed Python version (no version argument needed)

mise uninstall python

Remove All Versions

Use the --all flag to delete every installed version of a specific tool, or omit the tool name to purge all managed tools entirely.

This triggers get_all_tool_versions (lines 104–115), which gathers every installed version from the toolset via src/toolset/toolset_builder.rs.

# Delete all Go versions

mise uninstall --all go

# Delete every tool managed by mise

mise uninstall --all

Dry-Run Mode

Simulate uninstallation without making changes using --dry-run (or -n). For CI pipelines, --dry-run-code exits with status 1 if any removals would occur.

The is_dry_run check combines both flags (lines 40–42). During execution, the loop reports "uninstalled (dry-run)" instead of calling the actual delete operation (lines 76–80).

# Simulate removing all Ruby versions

mise uninstall --all ruby --dry-run

# CI check: exit 1 if Rust versions need uninstalling

mise uninstall --all rust --dry-run-code

The mise uninstall Workflow

According to the source code in src/cli/uninstall.rs, the uninstallation process follows a five-step pipeline:

1. Collect target versions — The command invokes either get_all_tool_versions (for --all) or get_requested_tool_versions (for specific requests) to build the removal list.

2. Deduplicate entries — The unique_by function ensures each version processes only once (line 53), preventing redundant backend calls.

3. Validate requests — If you omit --all but specify multiple tools, the command aborts with an error (lines 55–57), forcing explicit --all for batch operations.

4. Perform removal — For each (backend, ToolVersion) pair, the system calls backend.uninstall_version defined in src/backend/mod.rs (lines 70–72).

5. Refresh shims — After successful removal (non-dry-run), mise rebuilds shims and runtime symlinks to reflect the new state (lines 90–99), ensuring your shell environment stays synchronized.

Practical Command Examples

# Uninstall a specific version

mise uninstall node@18.0.0

# Uninstall the default/only version

mise uninstall python

# Remove all versions of a tool

mise uninstall --all go

# Preview changes without applying

mise uninstall --all ruby --dry-run

# CI-friendly exit codes

mise uninstall --all rust --dry-run-code

Key Implementation Files

The uninstall functionality spans several core modules:

• src/cli/uninstall.rs — Implements command parsing, version resolution, validation logic, and the shim refresh orchestration.
• src/backend/mod.rs — Defines the Backend trait; each tool backend provides the uninstall_version method called during removal.
• src/toolset/toolset_builder.rs — Builds the Toolset structure used by get_all_tool_versions to enumerate installed versions.
• src/ui/multi_progress_report.rs — Handles progress reporting during batch uninstall operations.
• src/config/config.rs — Manages global configuration loading and reset operations post-uninstall.
• src/cli/prune.rs — Contains similar uninstall logic for removing unused tool versions automatically.

Summary

• mise uninstall removes binaries without modifying mise.toml configuration files.
• Three modes handle specific versions, all versions of a tool, or system-wide cleanup.
• Dry-run options (--dry-run, --dry-run-code) enable safe testing and CI integration.
• Automatic shim refresh ensures shell environments update immediately after removal.
• Backend abstraction in src/backend/mod.rs ensures consistent cleanup across different tool types.

Frequently Asked Questions

Will mise uninstall remove entries from my mise.toml?

No. The command only deletes installed tool binaries and runtime files from your system. It does not modify configuration files, .tool-versions, or mise.toml entries. You must manually remove version specifications from configuration files if you no longer want mise to install those tools.

What happens if I don't specify a version when uninstalling?

If you omit the version argument and exactly one version is currently installed, mise automatically selects that version for removal. If multiple versions exist, the command requires you to specify which version or use --all to remove every installed version of that tool.

How does --dry-run-code differ from --dry-run?

Both options simulate the uninstallation without deleting files. However, --dry-run-code exits with status code 1 if any tools would have been removed, while --dry-run exits with status 0. This makes --dry-run-code useful for CI scripts that need to detect whether cleanup actions are pending.

Where does mise perform the actual file deletion?

The actual removal happens in the uninstall_version method of the specific backend implementation (defined in src/backend/mod.rs). Each backend (e.g., npm, cargo, asdf plugins) implements its own cleanup logic, ensuring proper removal of binaries, shims, and cached data specific to that tool type.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}