serverless remove
serverless remove deletes a deployed service from one stage and region: its CloudFormation stack with every resource in it, its deployment artifacts in the deployment bucket, and its ECR repository. Use it to tear down a stage you no longer need. To go back to an earlier deployment instead, use serverless rollback.
serverless remove --stage dev --region us-east-1
Without --stage and --region, the command removes the stage in provider.stage and provider.region, or stage dev in us-east-1.
Warning: serverless remove deletes the stack's resources, including stateful ones such as DynamoDB tables and S3 buckets defined under resources, unless they have a DeletionPolicy of Retain. It doesn't ask for confirmation.
Options
serverless remove accepts these options:
| Option | Alias | Value | Default | Required | Description |
|---|---|---|---|---|---|
--stage | -s | string | provider.stage, else dev | No | Stage to remove. |
--region | -r | string | provider.region, else us-east-1 | No | AWS Region of that stage. |
--aws-profile | string | provider.profile | No | AWS profile whose credentials the command uses. | |
--config | -c | file path | serverless.yml | No | Service configuration file to use. |
--verbose | flag | off | No | Print each CloudFormation stack event during the removal. |
serverless remove also accepts the options every command takes: --param="key=value" (repeatable), --org, --app, --debug and --help (-h). For an AWS SAM or CloudFormation project, it takes --stack and --bucket; see AWS SAM and CloudFormation.
What serverless remove deletes
serverless remove does this, in order:
- Deletes the service's objects under
<deploymentPrefix>/<service>/<stage>/in the deployment bucket (in the shared or stack-owned bucket, their earlier object versions too, and in a bucket set inprovider.deploymentBucketwhenprovider.deploymentBucket.versioningistrue), and the stage's Dev Mode payloads. Deleting earlier versions needs thes3:ListBucketVersionspermission. Without it, the command deletes only the current objects, so in a versioned bucket the earlier versions stay. Deleting the Dev Mode payloads, underserverless-dev-mode/<service>/<stage>/, is best effort: when it can't delete them, the command logs the reason only at debug level and continues, and the payloads stay in the bucket. - Deletes the CloudFormation stack
<service>-<stage>(orprovider.stackName) and waits for the deletion to finish. A deployment bucket that the stack owns is deleted with it. - Deletes the ECR repository
serverless-<service>-<stage>and its images, when the service has one.
Before the stack is deleted, the command also removes the base path mappings and web app aliases of custom domains set in provider.domain or provider.domains; after it, it deletes the log groups of web apps.
serverless remove keeps:
- the region's shared deployment bucket, which other services use, and a bucket set in
provider.deploymentBucket; - resources with
DeletionPolicy: Retain; - Lambda@Edge functions of
cloudFrontevents: the command prints a reminder to delete them yourself after the CloudFront distribution's removal has propagated.
After a removal has finished, a second serverless remove finds no stack and treats the stack deletion as complete.
Run serverless remove in CI
serverless remove asks no confirmation and has no prompts of its own, so it runs unattended. In CI, sign in with SERVERLESS_ACCESS_KEY or SERVERLESS_LICENSE_KEY; see Non-interactive use. Pass --stage explicitly, so the command removes the stage you intend.
Output of serverless remove
Removing "my-service" from stage "dev" (us-east-1)
✔ Service my-service has been successfully removed (28s)
Provided lifecycle events
remove:remove
Examples
Remove a preview stage
serverless remove --stage pr-123
This removes the stack my-service-pr-123 in the region from provider.region, or us-east-1.
Remove a stage and print each stack event
serverless remove --stage dev --region us-east-1 --verbose
Related commands
serverless deploydeploys the service again.serverless infoshows what is deployed in a stage before you remove it.- Deployment bucket explains the shared bucket that
serverless removekeeps.