Which HubSpot platform version should I be on in 2026?

TL;DR — The current platform version is 2026.03 (released March 30, 2026); use it for every new project. 2023.x and 2025.1 are closed to uploads, so an app on either must run hs project migrate before it can ship a change. 2025.2 stays supported through March 2027, but cannot express serverless functions.

What is the current HubSpot platform version?

2026.03, released March 30, 2026. If you're already running an app on the developer platform, the version you should target depends on three things: whether HubSpot has closed your current version to uploads, whether you use serverless functions, and how much time you have to do the work.

Two versions are already closed: 2023.2 (sunset October 1, 2025) and 2025.1 (sunset August 1, 2026). Everything else is a preference, not a deadline. Every version HubSpot lists in its versioning docs, with the support status, the Node.js floor, the serverless-function story, and the date by which you must move off it:

Source of truth: HubSpot's Developer platform and API versioning page. HubSpot ships a new platform version every six months (March and September) and runs a three-stage lifecycle: Current for 6 months, then Supported until 18 months after GA, then Unsupported (uploads fail).

Which dates have passed, and which are next?

Pin this in whatever planning doc you use. Every date is a hard date; HubSpot sets the cutover and does not grant extensions.

The next forced move is March 2027 for 2025.2. Everything before it has already happened: if you're on 2023.x or 2025.1, you're not facing a deadline, you're past one.

Which version should a new project use?

Use 2026.03. It's the current version, it's the only version that supports both the modern file-based project framework and serverless functions inside the same project (subject to HubSpot's Enterprise install requirement, and, per HubSpot's migration guide, for static-auth apps), and it's the version every HubSpot doc and CLI command now defaults to. There is no good reason to scaffold a new project on an older platform version.

The one historical reason people pinned 2025.1 instead of 2025.2, needing serverless functions, went away when 2026.03 shipped. The one reason people pinned 2025.2, wanting the modern projects framework without serverless, also no longer applies, because 2026.03 is a strict superset of 2025.2.

{
  "name": "my_project",
  "srcDir": "src",
  "platformVersion": "2026.03"
}

I'm on 2023.2 or 2025.1. What do I do now?

Both versions are closed. Any hs project upload attempt against a 2023.2 or 2025.1 project now fails server-side, regardless of CLI version. The project still runs in production until you redeploy, but you cannot ship a code change until you migrate.

Your migration target is 2026.03. The path:

1. Audit whether the project uses serverless functions (src/app/app.functions/ exists, and appFunctions is non-empty in your config).
2. Note any legacy CRM cards attached to the app. They are not project source, so hs project migrate neither converts nor refuses them: the card keeps serving until HubSpot's October 31, 2026 sunset, and replacing it is a separate step covered in the legacy CRM cards answer.
3. Run hs project migrate to convert the project shape to 2026.03. The CLI rewrites hsproject.json, splits any legacy serverless.json into per-function *-hsmeta.json files, and updates the directory layout.
4. Re-upload with hs project upload and validate the build.

A common failure mode here is the “create empty project, copy modules” escape hatch. If hs project migrate fails on a specific file (the CLI's error messages can be cryptic), scaffold a fresh 2026.03 project with hs project create --platform-version 2026.03 and move modules in by hand. The migrate command is fancier; the hand-copy is more reliable. Only do this for private apps or apps you are re-issuing: a fresh project is a new app with a new app ID, so installs, OAuth grants, and listings do not follow it.

The 2025.1 → 2026.03 step is the gentlest of the three, because 2025.1 already uses the projects framework. The two real changes:

• Node.js version bumps from v20 to v22. Update your local Node, your CI image, and any per-function runtime declarations.
• Serverless function configuration moves from serverless.json to per-function *-hsmeta.json files. hs project migrate does this rewrite for you, but read the diff before committing: the new shape exposes a secretKeys array instead of the old secrets array, and the entrypoint path is now absolute from the project root.

If you do not use serverless functions, the migration is mostly a platformVersion bump and a hs project upload. If you do, give it a half-day and budget a re-test of every function endpoint. hs-x migrate inspect classifies the project first, so you know which of these applies before running the one-way command, and hs-x migrate cutover . --execute runs steps 3 and 4 for you behind a type-to-confirm gate (it hands off to hs project migrate for 2023.2 and 2025.1, and does the bump-and-upload for 2025.2); the troubleshooting answer covers what goes wrong.

I'm on 2025.2. Should I move to 2026.03?

Yes, unless you have no serverless functions and no near-term need for them. 2025.2 is supported through March 2027, so there's no immediate forcing function. But the migration is the cheapest of any version jump (bump platformVersion in hsproject.json and re-upload), and it unlocks serverless functions without breaking anything else.

If you stay on 2025.2, the only durable downside is that you cannot use HubSpot-hosted serverless functions; you have to keep porting that logic to Cloudflare Workers, AWS Lambda, or Vercel and calling it via hubspot.fetch(). That's a valid choice (and what HS-X does by default), but it's a choice you should make on architectural grounds, not because the upgrade is hard.

 {
   "name": "my_project",
   "srcDir": "src",
-  "platformVersion": "2025.2"
+  "platformVersion": "2026.03"
 }

Then hs project upload. That's the entire 2025.2 → 2026.03 migration for apps that don't use serverless functions.

Why did serverless functions disappear and come back?

When 2025.2 shipped in September 2025, HubSpot rebuilt the project framework around a new file-based build-and-deploy model, and project-built apps on 2025.2 lost serverless function support in the transition. The official guidance for 2025.2 was: if you need serverless functions, stay on 2025.1; otherwise, move to 2025.2 for the new build system.

2026.03 resolves the split. It uses the same file-based projects framework as 2025.2, but reintroduces serverless functions with a new per-function configuration shape (*-hsmeta.json) instead of the old monolithic serverless.json. Migration from 2025.2 to 2026.03 does not require any code changes if you don't use serverless functions, only the platformVersion bump.

The takeaway: the 2025.2-without-serverless era is over, and so is the stay-on-2025.1 workaround. If you ported your function logic to an external runtime during that window, you can keep that architecture (HS-X recommends it for portability) or you can move it back into HubSpot-hosted serverless on 2026.03. Both are valid; the runtime is a deploy-time choice, not a platform-version constraint. The serverless functions answer compares the two.

How do I check which version my project is on?

Open the top-level hsproject.json in your project directory and read the platformVersion field. That single string is the authoritative answer.

{
  "name": "my_project",
  "srcDir": "src",
  "platformVersion": "2026.03"
}

If there's no hsproject.json file in your project, your app is not on the projects framework at all; it's a legacy private or public app. Public apps migrate via hs app migrate (a different command), and the path depends on whether the app is listed on the HubSpot Marketplace and how many accounts it's installed in: unlisted with 10 or more installs means listing it first. Legacy private apps have no migration path today; rebuild them as a new project. The legacy public app answer has the full decision tree.

Last updated: August 27, 2026. Sourced from HubSpot's Developer platform and API versioning and Determine your migration path to 2026.03 pages. Refreshed whenever HubSpot ships a new platform version (every six months, March and September).