vercel deploy

The vercel deploy command deploys Vercel projects, executable from the project's root directory or by specifying a path. You can omit 'deploy' in vercel deploy, as vercel is the only command that operates without a subcommand. This document will use 'vercel' to refer to vercel deploy.

vercel

Vercel automatically detects eligible static deployments and makes them ready without a build step. This optimization supports deployments containing only HTML (.html, .htm) or Markdown (.md) files, with up to 10 files and a total size of up to 5 MB.

Eligibility also depends on your project's build settings and deployment configuration. Other deployments automatically use the standard deployment flow.

vercel --cwd [path-to-project]

vercel deploy --prebuilt

When deploying, stdout is always the Deployment URL.

vercel > deployment-url.txt

In the following example, you create a bash script that you include in your CI/CD workflow. The goal is to have all preview deployments be aliased to a custom domain so that developers can bookmark the preview deployment URL. Note that you may need to define the scope when using vercel alias

# save stdout and stderr to files
vercel deploy >deployment-url.txt 2>error.txt
 
# check the exit code
code=$?
if [ $code -eq 0 ]; then
    # Now you can use the deployment url from stdout for the next step of your workflow
    deploymentUrl=`cat deployment-url.txt`
    vercel alias $deploymentUrl my-custom-domain.com
else
    # Handle the error
    errorMessage=`cat error.txt`
    echo "There was an error: $errorMessage"
fi

If you need to check for errors when the command is executed such as in a CI/CD workflow, use stderr. If the exit code is anything other than 0, an error has occurred. The following example demonstrates a script that checks if the exit code is not equal to 0:

# save stdout and stderr to files
vercel deploy >deployment-url.txt 2>error.txt
 
# check the exit code
code=$?
if [ $code -eq 0 ]; then
    # Now you can use the deployment url from stdout for the next step of your workflow
    deploymentUrl=`cat deployment-url.txt`
    echo $deploymentUrl
else
    # Handle the error
    errorMessage=`cat error.txt`
    echo "There was an error: $errorMessage"
fi

These are options that only apply to the vercel command.

The --prebuilt option can be used to upload and deploy the results of a previous vc build execution located in the .vercel/output directory. See vercel build and Build Output API for more details.

When using the --prebuilt flag, System Environment Variables will be missing at build time, so frameworks that rely on them at build time may not function correctly.

For Next.js projects, Skew Protection is supported with --prebuilt by configuring a custom deployment ID. See Custom Deployment ID for setup instructions. Prebuilt deployments cannot use dpl_ as a user-configured deployment ID prefix.

If you need System Environment Variables at build time, do not use the --prebuilt flag or use Git-based deployments.

vercel --prebuilt

You should also consider using the archive option to minimize the number of files uploaded and avoid hitting upload limits:

# Build the project locally
vercel build
 
# Deploy the pre-built project, archiving it as a .tgz file
vercel deploy --prebuilt --archive=tgz

This example uses the vercel build command to build your project locally. It then uses the --prebuilt and --archive=tgz options on the deploy command to compress the build output and then deploy it.

The --build-env option, shorthand -b, can be used to provide environment variables to the build step.

vercel --build-env KEY1=value1 --build-env KEY2=value2

The --yes option can be used to skip questions you are asked when setting up a new Vercel project. The questions will be answered with the provided defaults, inferred from vercel.json and the folder name.

vercel --yes

The --env option, shorthand -e, can be used to provide environment variables at runtime.

vercel --env KEY1=value1 --env KEY2=value2

The --name option, shorthand -n, can be used to provide a Vercel project name for a deployment.

vercel --name foo

The --prod option can be used to create a deployment for a production domain specified in the Vercel project dashboard.

vercel --prod

Must be used with --prod. The --skip-domain option will disable the automatic promotion (aliasing) of the relevant domains to a new production deployment. You can use vercel promote to complete the domain-assignment process later.

vercel --prod --skip-domain

The --public option can be used to ensure the source code is publicly available at the /_src path.

vercel --public

The --regions option can be used to specify which regions the deployments Vercel functions should run in.

vercel --regions sfo1

The --no-wait option does not wait for a deployment to finish before exiting from the deploy command.

vercel --no-wait

The --force option, shorthand -f, is used to force a new deployment without the build cache.

vercel --force

The --with-cache option is used to retain the build cache when using --force.

vercel --force --with-cache

The --archive option compresses the deployment code into one or more files before uploading it. This option should be used when deployments include thousands of files to avoid rate limits such as the files limit.

In some cases, --archive makes deployments slower. This happens because the caching of source files to optimize file uploads in future deployments is negated when source files are archived.

vercel deploy --archive=tgz

The --logs option, shorthand -l, also prints the build logs.

vercel deploy --logs

The --meta option, shorthand -m, is used to add metadata to the deployment.

vercel deploy --meta KEY1=value1

The CLI reads Git metadata from the local checkout. If the checkout has no Git metadata or uses a detached HEAD, a deployment can lack the branch association needed for branch-specific Preview variables and domains. Check the linked Vercel project, team, and branch shown on the deployment first.

For a GitHub-linked project, supply the branch explicitly when deploying source files:

vercel deploy --meta githubDeployment=1 --meta githubCommitRef=feature-checkout

Use the keys for your project's Git provider:

Use the branch name, such as feature-checkout, rather than a pull request merge ref. These values describe the deployment; they do not check out the branch or connect a Git repository. Other provider metadata keys are not interchangeable by changing their prefix.

Confirm that the environment variable is assigned to Preview and the same branch, and that the branch domain is configured on this project. A production deployment uses Production settings even if you attach branch metadata. A named custom environment requires its own target, such as --target=staging.

For a local or prebuilt deployment, fetch the branch's variables before building:

vercel pull --environment=preview --git-branch=feature-checkout
vercel build
vercel deploy --prebuilt --meta githubDeployment=1 --meta githubCommitRef=feature-checkout

Adding metadata at upload time cannot change values already embedded in build output. For a custom environment, use matching commands: vercel pull --environment=staging, vercel build --target=staging, and vercel deploy --prebuilt --target=staging. After deploying, verify the environment and assigned domains in the dashboard.

Use the --target option to define the environment you want to deploy to. This could be production, preview, or a custom environment.

vercel deploy --target=staging

The --guidance option displays suggested next steps and commands after deployment completes. This can help you discover relevant CLI commands for common post-deployment tasks.

vercel deploy --guidance

The following global options can be passed when using the vercel deploy command:

• --cwd
• --debug
• --global-config
• --help
• --local-config
• --no-color
• --non-interactive
• --scope
• --team
• --token
• --version

For more information on global options and their usage, refer to the options section.