Dependency and Platform Compatibility for Installation
Use this page to choose the Meshery installation path that matches your environment. Meshery itself runs on Docker or Kubernetes. mesheryctl is the common control point for installing, configuring, and operating Meshery across those targets.
Docker is enough to run Meshery locally and use many of its features. A Kubernetes cluster is required for most infrastructure lifecycle management features, including deploying and operating Cloud-based resources through Meshery. See the Feature dependency matrix below for specifics.
Installation Path Matrix
| Installation path | Runs on | Required dependencies | Kubernetes required | Best for |
|---|---|---|---|---|
mesheryctl only | macOS, Linux, Windows | mesheryctl installed via Bash, Homebrew, Scoop, or direct download | No | Installing, upgrading, and managing Meshery deployments |
Docker deployment (mesheryctl system start -p docker) | macOS, Linux, Windows | mesheryctl, Docker Engine or Docker Desktop, Docker Compose | No, to start Meshery. Yes, to manage Kubernetes infrastructure through Meshery. | Local evaluation and single-host deployments |
Kubernetes deployment (mesheryctl system start) | Any environment that can reach a cluster | mesheryctl, kubectl, access to an active Kubernetes cluster | Yes | Full Meshery management workflows on Kubernetes |
| Helm deployment | Any environment that can reach a cluster | Helm v3, kubectl, access to an active Kubernetes cluster | Yes | Teams standardizing on Helm-based installation |
| Docker Extension | Docker Desktop | Docker Desktop, Kubernetes enabled in Docker Desktop, Docker Extension support | Yes | Docker Desktop users who want the shortest local setup |
| GitHub Codespaces | GitHub Codespaces | mesheryctl, Minikube, kubectl, enough Codespaces CPU and memory to run Minikube | Yes | Browser-based evaluation and contributor environments |
Environment Matrix
| Environment | Supported installation paths | Hard dependencies | Recommended additions | Notes |
|---|---|---|---|---|
| Linux or macOS | mesheryctl, Docker, Kubernetes, Helm | mesheryctl for standard installs | Docker Desktop or Docker Engine, kubectl, Helm | This is the most direct path for local Docker and Kubernetes workflows. |
| Windows | mesheryctl, Docker, Docker Extension, Kubernetes | mesheryctl; Docker Desktop for container-based installs | WSL2, Kubernetes enabled in Docker Desktop, kubectl | Meshery supports Windows workflows, but Docker-backed paths are generally the smoothest option. |
| Docker Desktop | Docker deployment, Docker Extension | Docker Desktop with Compose support | Kubernetes enabled when you want cluster-backed features | Best fit for local development and evaluation on laptops. |
| Remote or managed Kubernetes cluster | Kubernetes deployment, Helm | Reachable cluster, valid kubeconfig, kubectl | LoadBalancer, Ingress, or port-forward access to Meshery | Good fit for shared team environments and production-style installs. See also Upgrading Meshery. |
| GitHub Codespaces | Kubernetes deployment in Minikube | Codespace with enough resources, Minikube, kubectl, mesheryctl | VS Code desktop or browser-based Codespaces access | Useful when you do not want to manage a local cluster. |
Feature Dependency Matrix
| Capability | Docker host only | Reachable Kubernetes cluster |
|---|---|---|
| Start Meshery locally and open the UI | Yes | Optional |
Run mesheryctl system check --preflight | Yes | Optional |
| Use performance management features | Yes | Yes |
| Deploy and manage Kubernetes infrastructure | No | Yes |
| Use Meshery Operator and MeshSync and cluster-backed adapters | No | Yes |
| Use the Docker Extension workflow | No | Yes, through Docker Desktop Kubernetes |
Compatibility Stipulations
- Meshery should be installed onto platform versions that are still maintained by their upstream project or vendor.
- For Kubernetes-based installs, use a Kubernetes release that is still within the Kubernetes project’s supported maintenance window and follow the operational guidance in Install Meshery on Kubernetes.
- Match
kubectlto the lifecycle of the cluster you target and keep it within the Kubernetes version skew policy. - For Docker-based installs, use a current Docker Engine or Docker Desktop release that includes Compose support and can run the Meshery container set reliably. See Install Meshery on Docker.
- The Docker Extension path applies when Docker Desktop supports extensions and Kubernetes is enabled in Docker Desktop. See Install Docker Extension for Meshery.
- Standard Meshery installation does not require local Go or Node.js runtimes. Those are contributor dependencies for building Meshery from source.
- If you plan to run Meshery out-of-cluster against Kubernetes, ensure the host running Meshery can reach the Kubernetes API and any broker endpoints exposed by your cluster. If connectivity fails, start with Troubleshooting Meshery Installations.
Release Channel Guidance
Meshery publishes stable and edge release channels. Use the release channel that matches how quickly your environment adopts new Kubernetes minors. See Build & Release (CI) for how these channels are produced and Upgrading Meshery for changing deployed components over time.
| Release channel | Intended use | Kubernetes guidance |
|---|---|---|
stable | Production environments and conservative upgrades | Use for environments that stay on maintained platform releases and adopt Kubernetes upgrades through planned release management. |
edge | Early validation, development, and upcoming-platform testing | Use when validating Meshery against newly introduced platform releases before they become part of your normal stable rollout. |
Stable and edge artifacts are published separately in Meshery’s build and release process, so cluster compatibility validation should be considered together with your selected release channel, your upgrade path, and the current test status.
Validation Checks
Validate your environment before installing Meshery:
mesheryctl system check --preflight
For a deeper walkthrough of what these checks validate, see Running system checks using Meshery CLI and the mesheryctl system check reference.
If you plan to use Docker, verify that the Docker Engine and Compose plugin are available:
docker version && docker compose version
If you plan to use Kubernetes, verify that your current context points to the target cluster:
kubectl config current-context
Choosing the Right Path
- Choose the Docker Extension when you already standardize on Docker Desktop and want a guided local workflow.
- Choose Docker when you want to get Meshery running quickly on a single machine.
- Choose Kubernetes or Helm when Meshery needs to manage Kubernetes-backed infrastructure and team environments.
- Choose the Meshery Playground when you want to try Meshery without installing anything locally. See Try Meshery Playground.
For rollout planning after initial installation, continue with Upgrading Meshery.
Related Reading
- Install mesheryctl
- Install Meshery on Docker
- Install Meshery on Kubernetes
- Install Docker Extension for Meshery
- Build & Release (CI)
- Upgrading Meshery
- Running system checks using Meshery CLI
- Troubleshooting Meshery Installations
- Old Compatibility Matrix - An installation compatibility matrix and project test status dashboard.