Overview

Rancher Desktop is an excellent local Kubernetes and container development environment for macOS, Windows, and Linux. It provides a lightweight Kubernetes cluster together with container runtimes such as containerd and Docker compatibility.

However, after upgrading Rancher Desktop, changing Kubernetes versions, modifying container runtimes, or uninstalling previous versions, you may encounter problems such as:

The Rancher Desktop won't start
Running is never achieved with Kubernetes
Failures of Lima virtual machines
Kubernetes configuration error
Runtime error for containers
Nerdctl is not working
Kubectl is unable to connect
Failures during virtual machine startup

The simple process of uninstalling and reinstalling Rancher Desktop is often insufficient because configuration files, Kubernetes settings, Lima virtual machines, and cached data remain.

Rancher Desktop can be completely removed from macOS and reinstalled using this guide.

Prerequisites

Make sure you have the following before you begin:

The Mac OS (Apple Silicon or Intel)
Installed Homebrew
Access to the local administrator
An Internet connection is required

Step 1 – Quit Rancher Desktop

Make sure Rancher Desktop is completely closed before uninstalling.

From the menu bar, quit Rancher Desktop.

Open Activity Monitor and verify that none of the following processes are running:

Desktop version of Rancher
Lima
nerdctl
containerd

Manually terminate any that remain.

During removal, no configuration files are locked.

Step 2 – Uninstall Rancher Desktop

Rancher Desktop can be uninstalled by using the following steps:

  
    brew uninstall rancher

Move the application to the Trash and remove it before continuing.

Step 3 – Restart macOS

Restart your Mac after uninstalling.

  
    sudo reboot -q

  
    sudo shutdown -r now

Passwords for local administrators will be prompted.

In addition to unloading any remaining processes, restarting releases any file locks.

Step 4 – Remove Rancher Desktop Configuration

All Rancher Desktop configuration files should be deleted.

  
    rm -rf ~/Library/Application\ Support/rancher-desktop

rm -rf ~/Library/Preferences/io.rancherdesktop.app.plist

rm -rf ~/Library/Caches/rancher-desktop

rm -rf ~/.rd

rm -rf ~/.lima

rm -rf ~/.kube

What these folders contain

Application Support

Information about Rancher Desktop's configuration and runtime.

Preferences

Preferences for the application are contained here.

Cache

Kubernetes images and temporary files are stored here.

  
    ~/.rd

Configuration of Rancher Desktop internally.

  
    ~/.lima

Stores Lima virtual machines.

  
    ~/.kube

Contexts and configurations for Kubernetes are stored here.

By removing these directories, the next installation will start clean.

Step 5 – Remove Lima Virtual Machines

Lima virtual machines may still exist even after deleting configuration files.

The following is a list of all virtual machines:

limactl list

The typical output is:

  
    NAME                 STATUS
rancher-desktop      Running

Rancher Desktop VM should be deleted as follows:

  
    limactl delete rancher-desktop

  
    limactl delete 0

The last step is to remove unused resources:

  
    limactl prune

Cleans up disks, snapshots, and unused images.

Step 6 – Restart macOS Again

Once more, restart the computer.

  
    sudo reboot -q

  
    sudo shutdown -r now

Before reinstalling virtualisation components, a second restart ensures they are completely unloaded.

Step 7 – Install Rancher Desktop

Using Homebrew, install the latest version.

  
    brew install --cask rancher

Once the installation is complete, launch Rancher Desktop.

Step 8 – Configure Rancher Desktop

Configure the following during initial setup.

Kubernetes

Enable Kubernetes.

Locally running Kubernetes allows you to develop and test applications in an environment similar to production.

Container Runtime

This is recommended:

Containerd
What's the reason?
Native Kubernetes runtime
Better Kubernetes compatibility
Uses nerdctl
Lightweight
Production focused

Kubernetes Version

You may choose:

The latest stable version

For production development, do not use preview or experimental versions.

CPU Allocation

Recommended:

4 cores
6 cores for larger projects

Memory

Recommended:

8 GB minimum
12 GB if running databases, Kafka, or multiple services
Disk

This is recommended:

60–100 GB

The following reasons contribute to the rapid consumption of disk space by larger projects:

Docker images
Kubernetes images
Databases
Logs
Build caches

When Rancher Desktop reports:

  
    Kubernetes: Running

Before moving forward.

Step 9 – Verify Kubernetes

The cluster should be verified.

Nodes to check:

  
    kubectl get nodes

What is expected:

Ready

Here is a list of all pods:

  
    kubectl get pods -A

Information about clusters should be verified:

  
    kubectl cluster-info

All commands should execute successfully if Kubernetes is functioning correctly.

Step 10 – Install k9s

k9s provides a powerful Kubernetes terminal interface.

How to install:

  
    brew install k9s

Check the following:

  
    k9s version

We are launching:

k9s

The following functions are now available to you:

Pods
Deployments
Services
ConfigMaps
Secrets
Logs
Events
Namespaces

Kubectl commands can be typed without typing long lines.

Step 11 – Verify the Environment

Check several things.

The current Kubernetes context is as follows:

  
    kubectl config current-context

The namespaces are:

  
    kubectl get ns

The pods are:

  
    kubectl get pods -A

Versions for clients and servers:

  
    kubectl version

Runtime for containers:

  
    nerdctl version

Rancher Desktop, Kubernetes, and the container runtime are correctly installed with these commands.

Optional Next Steps

Install additional development tools once Rancher Desktop is operational.

The following tools are recommended:

Java 21
IntelliJ IDEA
Visual Studio Code
Docker CLI
Helm
Git
Maven
Gradle
PostgreSQL
MongoDB
Redis
Testcontainers
Spring Boot
Spring AI
LangChain4j
Prometheus
Grafana

Cloud-native applications can be developed in this complete enterprise development environment.

Troubleshooting Tips

Rancher Desktop still won't start:

Make sure virtualisation is enabled.
Make sure no old Lima virtual machines remain.
Confirm that no previous Kubernetes contexts conflict with the new installation.
Make sure there is enough disk space available.
A sufficient amount of RAM should be allocated.
Check Rancher Desktop logs for startup errors.

Best Practices

The latest stable Rancher Desktop release should be used.
Unless Docker compatibility is required specifically, use containerd.
For local clusters, allocate sufficient CPU and memory.
Ensure that unused container images are regularly cleaned.
Keep Kubernetes versions reasonably current.
Manifests and Helm charts can be version controlled in Kubernetes.
In addition to kubectl, k9s can be used for day-to-day cluster management.

Summary

Rancher Desktop installations that are cleaned remove lingering configuration files, cached data, Lima virtual machines, and Kubernetes settings that can cause persistent startup problems. In this guide, we provide a predictable, repeatable installation and a stable foundation for Kubernetes development locally.

With Rancher Desktop, you can develop, test, and validate enterprise cloud-native applications locally before deploying them to Linux-based Kubernetes environments using tools such as Java 21, Spring Boot, Docker, Helm, Testcontainers, Prometheus, and Grafana.