diff --git a/platform/_partials/install/upgrade-v3-v4.mdx b/platform/_partials/install/upgrade-v3-v4.mdx
new file mode 100644
index 000000000..2dfeea45c
--- /dev/null
+++ b/platform/_partials/install/upgrade-v3-v4.mdx
@@ -0,0 +1,48 @@
+import Tabs from "@theme/Tabs";
+import TabItem from "@theme/TabItem";
+
+Upgrade vCluster Platform from v3 to v4 via:
+
+<Tabs
+  defaultValue="cli"
+  values={[
+    { label: 'CLI', value: 'cli', },
+    { label: 'helm', value: 'helm', },
+  ]
+}>
+<TabItem value="cli">
+
+To upgrade vCluster Platform from v3 to v4 via vCluster CLI, run:
+
+
+```bash
+# First set the project namespace prefix to use the v3 format
+cat > /tmp/vcluster-platform.yaml <<EOF
+config:
+  projectNamespacePrefix: loft-p-
+EOF
+
+vcluster platform start --upgrade --version=$VERSION --values=/tmp/vcluster-platform.yaml
+```
+
+</TabItem>
+<TabItem value="helm">
+
+To upgrade vCluster Platform from v3 to v4 via `helm`, run:
+
+```bash
+# First set the project namespace prefix to use the v3 format
+cat > /tmp/vcluster-platform.yaml <<EOF
+config:
+  projectNamespacePrefix: loft-p-
+EOF
+
+helm upgrade loft vcluster-platform -n vcluster-platform --repository-config '' --repo https://charts.loft.sh \
+  --version $VERSION \
+  --reuse-values \
+  -f /tmp/vcluster-platform.yaml
+```
+
+</TabItem>
+</Tabs>
+
diff --git a/platform/_partials/install/upgrade.mdx b/platform/_partials/install/upgrade.mdx
index 74eeef1ee..38c52d214 100644
--- a/platform/_partials/install/upgrade.mdx
+++ b/platform/_partials/install/upgrade.mdx
@@ -24,7 +24,7 @@ vcluster platform start --upgrade --version=$VERSION --values=vcluster-platform.
 To upgrade vCluster Platform via `helm`, run:
 
 ```bash
-helm upgrade loft vcluster-control-plane -n vcluster-platform --repository-config '' --repo https://charts.loft.sh \
+helm upgrade loft vcluster-platform -n vcluster-platform --repository-config '' --repo https://charts.loft.sh \
   --version $VERSION \
   --reuse-values \
   -f vcluster-platform.yaml
diff --git a/platform/manage/upgrade-platform.mdx b/platform/manage/upgrade-platform.mdx
index 52f0cbeb1..46cf9d13a 100644
--- a/platform/manage/upgrade-platform.mdx
+++ b/platform/manage/upgrade-platform.mdx
@@ -1,10 +1,11 @@
 ---
 title: Upgrade vCluster Platform
-sidebar_label: Upgrade 
+sidebar_label: Upgrade
 sidebar_position: 2
 ---
 
 import PartialAdminUpgrade from "../_partials/install/upgrade.mdx";
+import PartialAdminUpgradeV3V4 from "../_partials/install/upgrade-v3-v4.mdx";
 
 Upgrading vCluster Platform is easy! vCluster Platform can be upgraded either via the vCluster CLI, or with Helm.
 
@@ -15,3 +16,14 @@ The `$VERSION` variable above is an environment variable set to your desired vCl
 deploy. The `vcluster-platform.yaml` file is an optional YAML file that contains Helm values you would like
 to use when upgrading your vCluster Platform deployment.
 :::
+
+## Upgrading from v3.x to v4.0
+
+:::info Upgrade to latest v3 first
+Before attempting to perform this major upgrade please ensure that you have upgraded to the latest v3 release first. E.g. by running the steps above.
+:::
+
+With v4.0 the project namespace prefix can now be configured and the default has been changed from `loft-p` (which is used by v3) to `p-`.
+In order for the upgrade from v3 to v4 to succeed you must set this explicitly regardless of updating via the vCluster CLI or via Helm.
+
+<PartialAdminUpgradeV3V4 />