Kubeconfig Location on Windows, macOS and Linux

On every platform, kubectl reads the file named config inside a .kube folder in your home directory. On Windows that means the .kube\config file under your user profile, typically C:\Users\<your-name>\.kube\config. On macOS and Linux it is ~/.kube/config. If the KUBECONFIG environment variable or the --kubeconfig flag is set, kubectl uses those instead. This guide shows how to confirm which file your machine is really using, how to point kubectl somewhere else, and what to check when it cannot find anything.

TL;DR

• The default is $HOME/.kube/config, the same relative path on Windows, macOS and Linux. On Windows, "home" is your user profile folder.
• KUBECONFIG overrides the default. It holds one or more paths, separated by semicolons on Windows and colons on macOS and Linux.
• --kubeconfig loads exactly one file and never merges. KUBECONFIG with several paths does merge.
• Run kubectl config view to see the effective configuration, and kubectl cluster-info to test that it works.
• Treat the file like a credential store: keep it local, and do not paste it into tickets or chats.

Table of Contents

• Default kubeconfig location by operating system
• Finding your kubeconfig on Windows
• How to set a custom kubeconfig path
• Merging several kubeconfig files
• Check which kubeconfig kubectl is actually using
• When kubectl cannot find or use the file
• Keeping the file safe
• Our view: the file is simple, the sprawl is the problem
• One place for every cluster on Windows, macOS and Linux
• Quick reference for the commands in this guide
• FAQ
• Sources

Default kubeconfig location by operating system

The Kubernetes documentation on kubeconfig files states that by default kubectl looks for a file named config in the $HOME/.kube directory. There is no separate rule for each operating system. What changes is only how "home" and path separators look.

The Kubernetes page on installing kubectl on Windows says the default configuration is ~/.kube/config and tells Windows users to create the .kube directory under their home directory. In other words, the folder is not guaranteed to exist. A fresh machine that has never talked to a cluster may have no .kube folder at all, and that is normal.

Two details trip people up:

• The file has no extension. It is called config, not config.yaml or kubeconfig. The contents are YAML, but the name is plain. Windows Explorer hides known extensions by default, so check that you are not looking at a config.txt someone saved by accident.
• "kubeconfig" is a generic term. The Kubernetes docs explain that it means any file that configures cluster access, and does not imply a file literally named kubeconfig. Files you download from a cloud console or a cluster admin can have any name, such as prod-cluster.yaml.

Finding your kubeconfig on Windows

Windows is where most of the confusion lives, because there are three common shells (PowerShell, Command Prompt and WSL) and each sees a different home directory.

PowerShell

Check whether the default file exists:

Test-Path $HOME\.kube\config

True means the file is there. To open the folder in Explorer:

explorer $HOME\.kube

If the folder is missing, create it and then place or generate the file:

mkdir $HOME\.kube

Command Prompt

dir %USERPROFILE%\.kube

This lists the folder contents. If you see config, that is your default file.

WSL is a different machine for kubectl

If you run kubectl inside WSL, it is a Linux process. It looks at ~/.kube/config in the Linux home (for example /home/<your-name>/.kube/config), not at the Windows user profile. Installing kubectl in both places gives you two independent configurations. A cluster added from PowerShell will not appear in WSL, and the reverse is also true. Pick one place as your source of truth, or point both at the same file with KUBECONFIG, as described next.

How to set a custom kubeconfig path

You have two official ways to tell kubectl to use a file other than the default. According to the kubeconfig documentation, you can use the --kubeconfig flag or set the KUBECONFIG environment variable.

The --kubeconfig flag

The flag applies to a single command:

kubectl --kubeconfig C:\work\prod.yaml get pods

The kubectl config reference states that when the flag is supplied, only that file is loaded, the flag may be specified only once, and no merging occurs. That makes it the safest option when you want certainty about which cluster a command touches.

The KUBECONFIG environment variable

In PowerShell, set it for the current session:

$Env:KUBECONFIG = "C:\work\prod.yaml"

In Command Prompt:

set KUBECONFIG=C:\work\prod.yaml

Both last only until you close the window. To make the setting survive restarts, use setx KUBECONFIG "C:\work\prod.yaml" in Command Prompt, or add the variable under Windows' environment variable settings. Note that setx affects new windows, not the one you typed it in.

On macOS and Linux the equivalent is:

export KUBECONFIG=$HOME/work/prod.yaml

Add that line to ~/.zshrc or ~/.bashrc to keep it.

Which one wins?

Per the Kubernetes docs, if KUBECONFIG is unset, kubectl uses $HOME/.kube/config. If it is set, kubectl treats it as a list of paths and works from the merged result. The --kubeconfig flag, being explicit for one command, loads just the file you name.

Merging several kubeconfig files

Most engineers end up with more than one file: one per cloud account, one per customer, one for a local test cluster. You can keep them separate and let kubectl combine them.

The documentation explains that KUBECONFIG is a system-delimited list: colons on Linux and macOS, semicolons on Windows. The multiple clusters guide gives the PowerShell form like this:

$Env:KUBECONFIG = "config-demo;config-demo-2"

A real example with absolute paths:

$Env:KUBECONFIG = "$HOME\.kube\config;$HOME\.kube\staging.yaml;C:\work\prod.yaml"

The most common Windows mistake is typing a colon because that is what the Linux tutorial used. A colon is part of a drive letter such as C:, so a colon-separated list produces broken paths.

How the merge behaves

The kubeconfig documentation states that the first file to define a value or map key wins. Practical consequences:

• If two files both define a context called prod, the one listed earlier is used.
• Order your list deliberately. Put the file you trust most first.
• Run kubectl config view to inspect the merged result before you run anything destructive.

Where changes get written

The kubectl config reference adds an important detail. When you modify an existing value, kubectl edits the file that defines that stanza. Newly created values go into the first existing file in the list, or the last listed file if none exists. So kubectl config set-context on a merged setup can write into a file you did not expect. If you are unsure, use --kubeconfig to target one file explicitly while you make edits.

For a deeper look at switching and merging safely, see our guide to kubeconfig context management.

Check which kubeconfig kubectl is actually using

When the path is in doubt, work through these steps in order.

1. Is KUBECONFIG set? In PowerShell run $Env:KUBECONFIG. In Command Prompt run echo %KUBECONFIG%. On macOS and Linux run echo $KUBECONFIG. An empty answer means the default file is in play.
2. Does the default file exist? Use the Test-Path or dir commands above.
3. What does kubectl see? Run kubectl config view. The Kubernetes docs name this as the way to inspect the effective, merged configuration.
4. Does it connect? Run kubectl cluster-info. The Windows install guide says that a URL response means kubectl is correctly configured to reach the cluster, while a connection-refused response points to a configuration or connectivity problem.

One caveat: kubectl config view shows you the result of the merge, not the file names behind it. If you need to know which file a given context came from, open the files in your editor and search for the context name.

When kubectl cannot find or use the file

The kubectl troubleshooting guide tells you to verify that a valid kubeconfig exists, check KUBECONFIG or use --kubeconfig to point kubectl at it, and, if the file is missing, get one from your cluster administrator or regenerate it with your cloud provider's tools.

Translated into a Windows checklist:

When the file is right and the connection still fails, the same troubleshooting guide lists what to check: VPN connectivity, authentication tokens and server addresses, authorization credentials and permissions, API server reachability, network connectivity, firewalls and load balancer health. Work through them from the outside in: can your machine reach the server address at all, and only then, are your credentials accepted.

If your cluster sits behind a jump host, the file may be fine and the route is the problem. Our walkthrough of SSH tunnels for Kubernetes covers the usual certificate errors that show up when the server address in the kubeconfig no longer matches what you connect to.

Keeping the file safe

A kubeconfig is more than a list of addresses. It holds the information kubectl needs to connect to your clusters, and depending on how you authenticate, that can include certificates, tokens or commands that fetch them. Treat a copy of it the way you would treat a password file.

Some habits that cost nothing:

• Keep the working copy under your own user profile, not in a shared folder, a synced drive or a repository.
• Share the minimum. If a colleague needs access to one cluster, ask your administrator for a file scoped to that cluster rather than sending your merged configuration.
• Keep separate files per environment and merge them with KUBECONFIG only when needed, so production credentials are not loaded in every terminal.
• Before you paste output into a ticket or chat, check it. kubectl config view hides secrets by default in many setups, but a raw file copy does not.

Our view: the file is simple, the sprawl is the problem

We build Kubezilla Desktop, so we see how people actually handle this. The default path is not what causes trouble. People know ~/.kube/config. The trouble starts a few months in, when there are eight files across three folders, two shells that disagree, and an environment variable someone set a year ago and forgot.

Our position is that credentials for your clusters should live locally, on your machine, under your control. That is why Kubezilla Desktop stores kubeconfigs securely on your device, with no cloud sync and no telemetry. It is also why the app lets you connect to several clusters at once and reach remote ones through SSH tunnels, without asking you to export a variable before every session or to remember which window has which merge order.

If you stay with the command line, the advice is plain. Pick one place for your files. Name them after the environment. Use --kubeconfig when you want certainty and KUBECONFIG when you want a deliberate merge. And whenever you are about to run something you cannot undo, run kubectl config view first.

— Margus

One place for every cluster on Windows, macOS and Linux

If you are tired of juggling paths, Kubezilla Desktop is a native app for Linux, macOS and Windows that keeps your kubeconfigs in secure local storage. You get multi-cluster access, SSH tunneling, live logs and metrics, pod terminals, YAML editing, workload scaling, Helm and ArgoCD operations, and PVC file browsing in one window. It is built in Rust, so it is light on memory and starts fast. Kubezilla Desktop costs €5 per month, and you can see the details on the pricing page.

If you want to see how it compares with working from the terminal, our overview of the Kubernetes desktop app explains the workflow, and our piece on multi-cloud Kubernetes management shows how teams handle accounts spread across providers.

Quick reference for the commands in this guide

FAQ

Where is the kubeconfig file on Windows?

By default it is the config file in the .kube folder of your home directory, which is usually C:\Users\<your-name>\.kube\config. The folder may not exist until you create it or until a tool generates a config. If KUBECONFIG is set, kubectl uses the paths in that variable instead.

Where is the kubeconfig on a Mac?

It is ~/.kube/config, which expands to /Users/<your-name>/.kube/config. The folder begins with a dot, so Finder hides it. In Finder, press Command, Shift and period to show hidden items, or open it from Terminal with open ~/.kube.

Where is the kubeconfig on Linux?

It is ~/.kube/config, for example /home/<your-name>/.kube/config. Kubernetes documents $HOME/.kube/config as the default for kubectl. Some distributions and cluster installers write their own file elsewhere and expect you to point KUBECONFIG at it.

Can I use more than one kubeconfig file at once?

Yes. List the paths in KUBECONFIG, separated by semicolons on Windows and colons on macOS and Linux. kubectl merges them, and the first file that defines a value wins. The --kubeconfig flag is different: it loads only the file you name.

Why does kubectl work in one terminal but not another?

Usually the environment differs. The variable may have been set only for one session, or you may be mixing PowerShell and WSL, which have separate home directories. Print KUBECONFIG in both places and run kubectl config view to compare what each one sees.

Sources

• Organizing Cluster Access Using kubeconfig Files, Kubernetes documentation
• Install and Set Up kubectl on Windows, Kubernetes documentation
• kubectl config reference, Kubernetes documentation
• Configure Access to Multiple Clusters, Kubernetes documentation
• Troubleshooting kubectl, Kubernetes documentation

Recommended

• Kubezilla - Official Kubernetes Desktop App
• Kubezilla Desktop - Kubernetes Desktop App
• Kubezilla Desktop Pricing