---
title: Using Object Storage with s3cmd
description: Learn how to use s3cmd with Scaleway Object Storage with this detailed tutorial, offering step-by-step instructions and insights to help you effectively use the capabilities of this versatile tool.
tags: Object-Storage s3cmd CORS buckets
products:
  - object-storage
dates:
  validation: 2025-07-21
  posted: 2018-06-04
  validation_frequency: 12
difficulty: beginner
usecase:
  - resource-management
ecosystem:
  - third-party
---
import Requirements from '@macros/iam/requirements.mdx'

In this tutorial, you will learn how to use [s3cmd](https://github.com/s3tools/s3cmd) as a client for [Scaleway Object Storage](/object-storage/concepts/#object-storage). `s3cmd` is a tool that allows you to create, list and delete buckets from the command line, as well as to download, upload, and delete objects to/from your buckets.

<Requirements />

- A Scaleway account logged into the [console](https://console.scaleway.com)
- [Owner](/iam/concepts/#owner) status or [IAM permissions](/iam/concepts/#permission) allowing you to perform actions in the intended Organization
- A valid [API key](/iam/how-to/create-api-keys/)

## Installing s3cmd

You can install s3cmd from the command line using your Linux package manager.

<Tabs>
  <TabsTab label="Linux">
    1. Run the following command in a terminal to update and upgrade your packages:
        ```bash
        apt update && apt upgrade -y
        ```
    2. Run the following command to install s3cmd:
    ```bash
    apt install s3cmd
    ```
  </TabsTab>
  <TabsTab label="OSX">
    1. Ensure Homebrew is updated by running:
        ```bash
        brew update
        ```
    2. Run the following command to install s3cmd:
        ```bash
        brew install s3cmd
        ```
  </TabsTab>
</Tabs>
<Message type="note">
  Check the installed version of s3cmd using `s3cmd --version` after installation. To install the latest version or for other operating systems, download directly from GitHub or SourceForge. See the official [s3cmd documentation](https://s3tools.org/download) for more help.
</Message>

## Configuring s3cmd

Carry out the following commands from your terminal.

1. Create a configuration file named `.s3cfg` in your home directory:
    ```bash
    cd $HOME
    touch .s3cfg
    ```
2. Open the file with a text editor, e.g. nano:
    ```bash
    nano .s3cfg
    ```
3. Paste the following text into the file, save your changes, and exit. Make sure you use the `host_base`, `host_bucket`, and `bucket_location` details of your own bucket (visible in the **Bucket settings** tab of the console). You will also need to replace `<ACCESS_KEY>` and `<SECRET_KEY>` with your [own API credentials](/iam/how-to/create-api-keys/).
    ```bash
    [default]
    # Object Storage Region NL-AMS

    host_base = s3.nl-ams.scw.cloud
    host_bucket = %(bucket)s.s3.nl-ams.scw.cloud
    bucket_location = nl-ams
    use_https = True

    # Login credentials

    access_key = <ACCESS_KEY>
    secret_key = <SECRET_KEY>
    ```
    <Message type="tip">
      Alternatively, you can use the configuration file generator by running `s3cmd --configure` to generate a configuration file. You can also generate a configuration file using the Scaleway CLI with `scw object config get type=s3cmd region=nl-ams`.
    </Message>

### Using multiple configuration files

You can configure s3cmd to use different configuration files on the same computer to manage buckets in multiple regions. Here, we assume that your default configuration file was for a bucket in `nl-ams`, and we create a new configuration file for buckets in `fr-par`.

Carry out the following steps from the terminal.

1. Create a default configuration file as indicated in the [previous step](#configuring-s3cmd).
2. Create a new file named `.s3cfg-fr-par` in your home directory.
    ```bash
    cd $HOME
    touch .s3cfg-fr-par
    ```
3. Copy and paste the following text into the file, then save and close. Make sure you replace `<ACCESS_KEY>` and `<SECRET_KEY>` with your [own API credentials](/iam/how-to/create-api-keys/).
    ```bash
    [default]
    signature = s3v4

    # Object Storage Region FR-PAR

    bucket_location = fr-par
    host_base = s3.fr-par.scw.cloud
    host_bucket = %(bucket)s.s3.fr-par.scw.cloud

    # Login credentials

    access_key = <ACCESS_KEY>
    secret_key = <SECRET_KEY>
    ```
    <Message type="note">
      The `signature = s3v4` line ensures compatibility with Scaleway’s S3 API, which uses AWS Signature Version 4. Alternatively, generate this configuration file using `scw object config get type=s3cmd region=fr-par`.
    </Message>
4. Use s3cmd by specifying the new configuration file in the command:
    ```bash
    s3cmd ls -c ~/.s3cfg-fr-par
    ```

## Using Object Storage with s3cmd

### Creating a new bucket

Enter the following command to create a bucket with s3cmd. The bucket name must contain only alphanumeric and lowercase characters. Here, we call it `mynewbucket`:

```bash
s3cmd mb s3://mynewbucket
```

An output similar to the following displays:

```bash
Bucket 's3://mynewbucket/' created
```

### Uploading objects into the bucket

Enter the following command to upload files into a bucket. Here, we upload the files `movie1.avi` and `photo1.jpg` into `mynewbucket`:

```bash
s3cmd put movie1.avi photo1.jpg s3://mynewbucket
```

<Message type="tip">
Object Storage uses the MIME type sent by s3cmd. If Object Storage is unable to determine the MIME type because the client (in this case s3cmd) has not sent any, then it first tries to infer the correct MIME type from the file extension; and if it cannot find a matching type, it falls back to the default MIME type, which is `binary/octet-stream`.
</Message>

An output similar to the following displays:

```bash
movie1.avi -> s3://mynewbucket/movie1.avi [1 of 2]
0 of 0 0% in 0s 0.00 B/s done
photo1.jpg -> s3://mynewbucket/photo1.jpg [2 of 2]
0 of 0 0% in 0s 0.00 B/s done
```

<Message type="important">
  When uploading files from a Scaleway Instance, an error message like the following may appear. Your file will be uploaded nonetheless, and you can ignore this message:

  ```
  ERROR: Cannot retrieve any response status before encountering an EPIPE or ECONNRESET exception
  WARNING: Upload failed: /bucket_name?partNumber=1&uploadId=ZWY5ZWRhNzItMjE3NS00ZTY4LWFkOTMtYTFhODRkYTRkNzdl ([Errno 32] Broken pipe)
  ```
  We are currently working to correct this issue.
</Message>
<Message type="note">
  For large files (>5 GB), `s3cmd` supports multipart uploads, which Scaleway’s Object Storage handles with a limit of 1000 chunks. Adjust settings like `--multipart-chunk-size-mb` if needed.
</Message>

### Listing objects inside a bucket

Enter the following command to list files inside a bucket. Here, we list the files in the bucket `mynewbucket`:

```bash
s3cmd ls s3://mynewbucket
```

An output similar to the following displays, showing the files inside your bucket:

```bash
2014-09-10 08:44 0 s3://mynewbucket/movie1.avi
2014-09-10 08:44 0 s3://mynewbucket/photo1.jpg
```

### Downloading an object from a bucket

Enter the following command to download an object from your bucket to your local machine. Here, we download the object `movie1.avi` from the bucket `mynewbucket`:

```bash
s3cmd get s3://mynewbucket/movie1.avi movie1.avi
```

An output similar to the following displays:

```bash
s3://mynewbucket/movie1.avi -> movie.avi [1 of 1]
0 of 0 0% in 0s 0.00 B/s done
```

### Removing objects from a bucket

Enter the following command to remove an object from your bucket. Here, we remove the object `movie1.avi` from the bucket `mynewbucket`:

```bash
s3cmd del s3://mynewbucket/movie1.avi
```

An output similar to the following displays:

```bash
delete: 's3://mynewbucket/movie1.avi'
```

### Removing a bucket

Enter the following command to remove a bucket. Here, we remove the bucket `mynewbucket`:

```bash
s3cmd rb s3://mynewbucket
```

You should see an output similar to the following:

```bash
Bucket 's3://mynewbucket/' removed
```

## Configuring CORS

The [CORS standard](https://en.wikipedia.org/wiki/Cross-origin_resource_sharing) provides browsers with a way to request resources from remote domains when they have permission. This lets you configure how your buckets can be accessed from browser-based applications and websites.

### Setting a CORS configuration on a bucket

1. Create a [CORS](https://en.wikipedia.org/wiki/Cross-origin_resource_sharing) configuration file and open it in a text editor:
    ```bash
    nano cors.xml
    ```
2. Put your configuration in the file, save it, and exit the editor:
    ```bash
    <CORSConfiguration>
      <CORSRule>
        <AllowedOrigin>http://www.example.com</AllowedOrigin>
        <AllowedMethod>PUT</AllowedMethod>
        <AllowedMethod>POST</AllowedMethod>
        <AllowedMethod>DELETE</AllowedMethod>
        <AllowedHeader>*</AllowedHeader>
        <MaxAgeSeconds>3000</MaxAgeSeconds>
        <ExposeHeader>x-server-side-encryption</ExposeHeader>
      </CORSRule>
    </CORSConfiguration>
    ```
3. Set the information on the bucket. Make sure to replace `bucketname` with the name of your bucket:
    ```bash
    s3cmd setcors cors.xml s3://bucketname
    ```
    <Message type="note">
      You can also manage CORS settings directly in the Scaleway console under the **Bucket Settings** tab, which is often easier than using XML files.
    </Message>

### Deleting the CORS configuration of a bucket

Run the following command to delete the CORS configuration of a bucket. Replace `bucketname` with the name of your bucket:

```bash
s3cmd delcors s3://bucketname
```

<Message type="important">
  It is currently not possible to get the CORS configuration of a bucket with `s3cmd`. To retrieve CORS settings, use `aws s3api get-bucket-cors --bucket bucketname --endpoint-url https://s3.nl-ams.scw.cloud` with `aws-cli` configured for Scaleway.
</Message>

## Going further

For more information about the different s3cmd commands, refer to the [official documentation](https://s3tools.org/usage), or run the following command in a terminal:
```bash
s3cmd --help
```