docs/sf/guides/upgrading-v4.md
This guide covers upgrading to Serverless Framework version 4 from version 3 or earlier, and includes info on breaking changes, key license and pricing updates, and practical advice tailored for both small and large organizations.
We are uniquely accessible to chat, even for same-day meetings. Feel free to schedule a meeting with us to discuss upgrading, pricing, and more.
Here is a quick overview video answering common questions around V.4
::youtube{id="p7dnwVslChs"}
Also, the Serverless MCP is a great tool for upgrading Serverless Framework and using the latest features. It comes packaged with the latest Serverless Framework documentation, so it will always give you the most up to date advice directly in AI-enhanced IDEs like Cursor, Windsurf and VS Code.
Serverless Framework CLI version 4 was released in May 2024. It's stable and now widely used, and introduces no breaking changes—except for a new license and authentication requirement.
V.4 works out of the box for older projects built using Amazon Web Services with no migration steps required. Organizations making over $2 million/year may need to purchase a subscription based on the new terms (detailed below), but most developers will not.
V.4 features significant improvements, integrating plug-ins into the core for better reliability, improving developer workflows, enhancing integrations with tools like Terraform and observability solutions, and larger innovations like the Serverless Container Framework and Serverless MCP. Serverless Framework CLI version 4's development velocity has surged, with weekly updates replacing the quarterly releases of the prior open-source model.
Overall, V.4 delivers a stable, customer-centric experience, with powerful updates, built-in support, and a focus on your features and fixes for lasting dependability.
Here are quick steps to upgrade to Serverless Framework V.4:
npm install -g serverless to install v4 globally.As announced in late 2023, the Serverless Framework CLI remains free for individual developers and small businesses. However, developers and organizations with annual revenue exceeding $2M USD (as measured by their latest fiscal year) are now required to obtain a paid subscription.
If you're a developer or organization that does not exceed the revenue threshold, no additional action is required. You may continue to freely use the Serverless Framework CLI as much as you'd like without providing proof of eligibility.
This license change applies only to Serverless Framework CLI version 4 and later. Versions 3 and earlier remain open-source and will continue to be available as open-source software.
Please note: As of early 2025, version 3 is no longer maintained and will no longer receive security updates, bug fixes, or feature improvements.
These license changes apply exclusively to the CLI. The optional Serverless Framework Dashboard—offering features such as observability, CI/CD, and secrets management—has separate pricing and is unaffected by this licensing change.
The updated license terms can be reviewed in the On-Premise Software License section of Serverless Inc.'s Customer Agreement.
For organizations that meet or exceed the revenue threshold, a subscription is required, priced based on Credits. One Credit is equivalent to one Serverless Framework Service Instance. A Service corresponds to a serverless.yml file, while a Service Instance refers to the deployment of that file to a specific AWS account, Stage, and Region. Another way to think about a Service Instance is that it equates to an AWS CloudFormation Stack deployed via Serverless Framework.
To estimate pricing, multiply the Credit price by the number of estimated Service Instances you might have. Our Serverless Framework Dashboard also features a pricing calculator within the Billing page.
If a Service Instance is interacted with using Serverless Framework CLI version 4 at any point (including instances initially deployed using versions 3 or earlier), it will be counted towards usage. To stop a Service Instance from counting towards your usage, run the serverless remove CLI command using version 4.
Additionally, a Service Instance will only be counted if it exists for more than 10 days in a given month. This rule prevents charges for temporary Service Instances used for testing or previews.
For greater clarity, subscriptions are not priced based on:
The Credit price is a fixed fee per deployed Service Instance. Here are some sample estimated costs, depending on your plan:
The optional Serverless Framework Dashboard offers separate pricing for additional features like CI/CD and observability. These charges apply only if the Dashboard is explicitly enabled in your serverless.yml using the app property. Otherwise, these features and associated costs do not apply. Many users rely exclusively on the CLI.
We offer check out via credit card, bank transfer, traditional invoice, as well as AWS Marketplace. Many orgs favor using AWS Marketplace as it can ease the procurement process and count towards enteprise agreements orgs have with AWS.
If you have pricing, sales or general questions, please book a meeting with us or check out our pricing page.
All subscriptions include comprehensive support via email at support[at]serverless.com. Our team is available daily to help with migration questions and ensure a smooth transition. Unlike the open-source model where users are typically left to manage issues independently, our subscribers receive prioritized, personalized assistance.
Customers with larger subscriptions benefit further from a dedicated Customer Success team that provides proactive guidance and tailored support.
We also offer a Premium Support package, which includes:
For further details or inquiries, please schedule a meeting with our team or contact us directly at support[at]serverless.com.
Serverless Framework CLI version 4 is designed to minimize breaking changes and supports older AWS-based projects out of the box, requiring no migration steps. Here is a full list of potential breaking changes and notable differences that may affect your workflow.
While not a technical breaking change affecting services or architecture, Serverless Framework version 4 introduces a new license. Refer to the "License Changes" section of this guide for full details.
Version 4 of the Serverless Framework CLI now requires authentication. This is a breaking change as the authentication prompt in the CLI will disrupt usage of CLI commands on local machines and in CI/CD pipelines.
We offer two ways to sign in using either the Serverless Framework Dashboard or License Keys.
Authenticate via the CLI using your Serverless Framework Dashboard credentials (email/password, Google, or GitHub). This generates an Access Key on your machine, eliminating the need for repeated logins.
In the Serverless Framework Dashboard, you can generate further Access Keys to use in your CI/CD pipelines in the Settings > Access Keys tab, to avoid the authentication prompt in the CLI.
License Keys provide an alternative sign-in method, ideal for teams and organizations that:
You can generate one or multiple License Keys for your subscription. These can be set as environment variables in your terminal or CI/CD pipelines. Alternatively, a new feature allows you to store License Keys as AWS SSM Parameters on your AWS accounts. This eliminates the need to distribute keys to team members or update CI/CD configurations, simplifying onboarding, offboarding, and management. For most large organizations, this AWS SSM approach is the preferred method.
For more details, see the License Keys guide.
Version 4 discontinues support for cloud providers beyond AWS, marking a breaking change for users of non-AWS providers.
Historically, we’ve supported multiple providers, but creating a consistent abstraction across their diverse serverless offerings proved difficult. As a result, AWS has become the primary choice for most of our users. Looking ahead, we’re investigating improved multi-cloud support through initiatives like the Serverless Container Framework.
The Serverless Framework CLI features a thriving ecosystem with over a thousand community-maintained plugins. To ensure compatibility and optimal performance with Serverless Framework V4, we've proactively reviewed these plugins and contributed dozens of improvements.
If you encounter any compatibility issues with plugins in V4, please let us know—we’re committed to reaching out to plugin authors, providing fixes, and assisting with improvements.
To report plugin issues, you can open an issue in our main repository, or, if you're a customer, contact us directly at support[at]serverless.com.
Here are some of the many plugins which we've tested for V.4:
In previous versions of Serverless Framework (<= V.3), the useDotEnv configuration in serverless.yml would have to be set in order to load .env and .env.[stage] files, and make their environment variables accessible within serverless.yml.
In V.4, these files are read automatically, without the useDotEnv property.
In previous versions of Serverless Framework (<= V.3), the dev command would work exclusively with Serverless Console or Serverless Framework Dashboard. However, dev has been completely re-imagined to only work with the CLI, not requiring Dashboard, and proxy events from your live AWS Lambda functions to your local code, enabling you to develop faster than ever.
Learn more about the new dev mode.
In V.4, esbuild is included within Serverless Framework, allowing you to use Typescript files directly in your AWS Lambda function handlers and have your code build automatically upon deploy, without a plugin and without configuration.
Please note, plugins that build your code will not work unless you opt out of the default build experience. Some of the plugins affected are:
serverless-esbuildserverless-webpackserverless-plugin-typescriptTo learn more about this, check out the building guide.
Auto-updating has been introduced in Serverless Framework V.4. This is checked once every day, and can be manually updated via serverless update.
Please note that if you do not have frameworkVersion specified in your serverless.yml, auto-updating will be enabled. We recommend using frameworkVersion with traditional semantic versioning syntax to control how version updating should work in a way that's ideal for you.
Git-related Serverless Framework Variables have been introduced into the Variable system.
As a result, the Serverless Git Variables Plugin no longer works.
In V.4 there is a new global stages syntax that allows you to define parameters for each stage. This is not a breaking change for the previous stages syntax; however, the new syntax is recommended.
The old V.3 syntax:
params:
default:
key1: devValue
prod:
key1: prodValue
The new V.4 syntax:
stages:
default:
params:
key1: devValue
prod:
params:
key1: prodValue
The functionality is similar, but parameters should be defined under stages.<stage>.params instead of just params.<stage>.
You're no longer on your own—Serverless Framework V4 prioritizes your experience and support. Whether you have specific migration questions, licensing inquiries, or general feedback, our team is ready and eager to assist.
Feel free to book a meeting with us today, or reach out directly at support[at]serverless.com. We're here to ensure your upgrade to Version 4 is smooth, efficient, and successful.