Deploy with Hugo

Use these instructions to deploy your site to an Amazon S3 bucket, an Azure Blob Storage container, or a Google Cloud Storage bucket with the hugo deploy command.

Deployment constraints

Deploying a Hugo site requires more than copying files to your host. For example, typical FTP clients do not remove orphaned files from the server, and compare files by modification time and size.

• Deployments must remove orphaned files. When you rename a page, change its permalink, or delete content, Hugo does not remove the corresponding files from your local public directory. Hugo also leaves a page’s files in place when the page becomes a draft, expires, or has its publication date changed to a future date. To remove these files, clear the public directory before you build, or build with the --cleanDestinationDir flag or the cleanDestinationDir configuration option enabled. Unless your deployment also removes them from your host, the old pages remain online.

• Deployments should compare files by checksum. Hugo updates the modification time of every file in the public directory on every build, so tools that compare modification times transfer your entire site each time. Tools that compare only file size can miss changed files, because editing text does not always change a file’s size.

The hugo deploy command meets both requirements.

Prerequisites

Please complete the following tasks before continuing:

1. Create a Hugo project and test it with the hugo server command.

2. Set the baseURL in your project configuration to the URL of your production site.

3. Install the deploy or extended/deploy edition of Hugo. See the installation section for details.

4. Create a bucket or container. To serve your site directly from it, configure it to host a static website. See the documentation for Amazon S3, Azure Blob Storage, or Google Cloud Storage.

5. Install the command-line tool for your cloud provider, then use it to log in. Hugo uses the credentials that the tool stores on your local machine.

   • Amazon S3: Install version 2.32.0 or later of the AWS CLI, then run the aws login command. Your IAM user, role, or group must have the SignInLocalDevelopmentAccess managed policy attached.
   • Azure Blob Storage: Install the Azure CLI, then run the az login command. Your account must have the Storage Blob Data Contributor role on the storage account.
   • Google Cloud Storage: Install the Google Cloud CLI, then run the gcloud auth application-default login command.

Procedure

Step 1

Create a deployment target in your project configuration, adjusting the values as needed.

deployment:
  targets:
  - name: production
    url: s3://my-bucket?region=us-west-1

[deployment]
  [[deployment.targets]]
    name = 'production'
    url = 's3://my-bucket?region=us-west-1'

{
   "deployment": {
      "targets": [
         {
            "name": "production",
            "url": "s3://my-bucket?region=us-west-1"
         }
      ]
   }
}

Set name to any name you choose. Set url to the destination URL of your bucket or container. The format of the URL depends on your cloud provider:

• Amazon S3: s3://my-bucket?region=us-west-1
• Azure Blob Storage: azblob://my-container?storage_account=my-account
• Google Cloud Storage: gs://my-bucket

Step 2

Build your site from the root of your project.

hugo build --cleanDestinationDir --gc --minify

Step 3

Deploy your site.

hugo deploy

To preview changes without modifying anything in your bucket or container, add the --dryRun flag to the hugo deploy command.

The hugo deploy command does not upload .DS_Store files, or files within hidden directories such as .git. It does upload files within the .well-known directory.

Command-line flags

The hugo build command uses these flags:

--cleanDestinationDir

Removes orphaned files from the public directory. See configure build.

--gc

Removes unused files from the file cache. See configure file caches.

--minify

Minifies the output. See configure minify.

The hugo deploy command compares files by size and MD5 checksum, and deletes files in your bucket or container that do not exist in the local public directory. Use these flags as needed:

--confirm

Lists the changes and prompts for confirmation before applying them.

--dryRun

Lists the changes without applying them.

--force

Uploads every file, even if it has not changed.

--maxDeletes

Sets the maximum number of files to delete, or -1 to disable the limit. Default is 256. If a deployment would delete more files than this limit, Hugo uploads files as usual but skips every deletion and logs a warning.

--target

Specifies the name of the deployment target. Defaults to the first target in your project configuration.

Related resources

For more information on deploying your site with Hugo, consult the documentation:

• Configure deployment, including file inclusion and exclusion, HTTP headers, upload order, and CDN cache invalidation
• hugo deploy command reference