s3cmd 2.x Setup

s3cmd is a popular cross-platform command-line tool for managing S3 and S3-compatible object stores.

To use s3cmd, you will need:

  • s3cmd version 2.0.0+ or higher. You can check your version with s3cmd --version. Versions from package managers may be out of date, so we recommend using the s3cmd download page.
  • An access key pair for your Spaces. To generate these, visit the API page in the DigitalOcean Control Panel.

Initialize the Configuration File

By default, s3cmd stores its configuration file, .s3cfg, in the home directory of the user who runs the configuration command. This is a plain text file of key/value pairs which can be edited directly once it has been created. You can choose between setting up DigitalOcean as the default configuration or creating a different configuration file.

If DigitalOcean is the main or only provider you’ll connect to with s3cmd, configure it in the default ~/.s3cfg file with the following command:

s3cmd --configure

By choosing this option, you won’t have to specify the configuration file each time you run a command.

If you’re already using s3cmd with another service, you may want to create an alternate configuration file, which you can do by adding the -c flag and supplying a filename. The configuration file will be created in the directory where you issue the command, so specify the path if you want it created elsewhere. To use a configuration file this way, you must explicitly provide it at the end of each command by appending -c ~/path/to/config/file.

Whether you use the default configuration file or specify your own, when you issue the configuration command, it will launch an interactive multi-step configuration script. In this section, we’ll go through each of the steps in the configuration process.

Enter Access Keys

The script begins by asking for an Access Key and Secret Key. If you don’t already have keys, you can generate a set for s3cmd by visiting the control panel’s API page.

Enter your keys, then accept US for the Default Region because the region information isn’t relevant to DigitalOcean. If you prefer, you can use the environment variables AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY to store a set of keys.

Enter new values or accept defaults in brackets with Enter.
Refer to user manual for detailed description of all options.
Access key and Secret key are your identifiers for Amazon S3. Leave them empty for using the env variables.
Secret Key []: exampleb8e1ec97b97bff326955375c5
Default Region [US]:

Enter the DigitalOcean Endpoint

Next, enter the DigitalOcean Spaces endpoint. The Spaces endpoint naming pattern is region.digitaloceanspaces.com, and our example will use nyc3.digitaloceanspaces.com. You may need to change nyc3 to reflect the region for your endpoint.

Use "s3.amazonaws.com" for S3 Endpoint and not modify it to the target Amazon S3.
S3 Endpoint [s3.amazonaws.com]: nyc3.digitaloceanspaces.com

The next prompt asks for a URL template to access your bucket, which is the S3 equivalent of a Space. Because Spaces supports DNS-based endpoint URLs, you can use the variable %(bucket)s to stand in for the name of your space. Enter the following template format exactly as written: %(bucket)s.nyc3.digitaloceanspaces.com. Again, you will change this if your Space is in a different region.

Use "%(bucket)s.s3.amazonaws.com" to the target Amazon S3. "%(bucket)s" and "%(location)s" vars c
an be used if the target S3 system supports dns based buckets.
DNS-style bucket+hostname:port template for accessing a bucket []: %(bucket)s.nyc3.digitaloceanspaces.com

Optional: Set an Encryption Password

Next, we’re asked to supply an encryption password. Unlike HTTPS, which protects files only while in transit, GPG encryption prevents others from reading files while they are stored on DigitalOcean as well as in transit.

Encryption password is used to protect your files from reading
by unauthorized persons while in transfer to S3
Encryption password:
Path to GPG program [/usr/bin/gpg]:

Setting a password now won’t cause objects to be automatically encrypted; it just makes encryption available later.

Connect via HTTPS

Next, we’re prompted to connect via HTTPS. As mentioned in the encryption password section, HTTPS protects data from being read while it is in transit. DigitalOcean Spaces do not support unencrypted transfer, so press ENTER to accept the default, YES:

When using secure HTTPS protocol all communication with Amazon S3
servers is protected from 3rd party eavesdropping. This method is
slower than plain HTTP, and can only be proxied with Python 2.7 or newer
Use HTTPS protocol [Yes]: Yes

Optional: Set a Proxy Server

If your network requires you to use an HTTP Proxy server, enter its IP address or domain name without the protocol, e.g. or proxy.example.com. Because we aren’t using an HTTP Proxy server, we’ll leave this question blank and press ENTER:

On some networks all internet access must go through a HTTP proxy.
Try setting it here if you can't connect to S3 directly
HTTP Proxy server name:

Confirm, Test, and Save Settings

After the prompt for the HTTP Proxy server name, the configuration script presents a summary of the values it will use, followed by the opportunity to test them:

New settings:
 Secret Key: b8e1ec97b97bff326955375c5example
 Default Region: US
 S3 Endpoint: nyc3.digitaloceanspaces.com
 DNS-style bucket+hostname:port template for accessing a bucket: %(bucket)s.n
 Encryption password: secure_password
 Path to GPG program: /usr/bin/gpg
 Use HTTPS protocol: True
 HTTP Proxy server name:
 HTTP Proxy server port: 0

Test access with supplied credentials? [Y/n] Y

When the test completes successfully, enter Y to save the settings:

Please wait, attempting to list all buckets...
Success. Your access key and secret key worked fine :-)

Now verifying that encryption works...
Success. Encryption and decryption worked fine :-)

Save settings? [y/N] Y

If the test fails or you choose N you’ll have the opportunity to retry the configuration. Once you save the configuration, you’ll receive confirmation of its location:

Configuration saved to '/home/sammy/nyc3'

The test step confirms that we can connect to our DigitalOcean Spaces.

More Information

You can use our quick reference on s3cmd usage to get started. For a comprehensive guide to s3cmd, see the s3cmd usage guide or access the help file from the command line with s3cmd --help.