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:
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
or
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
or
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
or
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:
Kubernetes Version
You may choose:
The latest stable version
For production development, do not use preview or experimental versions.
CPU Allocation
Recommended:
Memory
Recommended:
This is recommended:
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.