Quickstart: S3‑compatible storage (MinIO, local)

This example shows how to explore an S3‑compatible bucket with Jupyter fsspec using a local MinIO server.

Note

This quickstart complements the Config File and Basic Usage sections. It assumes you already have JupyterLab installed and that you will run MinIO locally with Docker.

---

Install required packages (one line)

pip install jupyter-fsspec s3fs

If you already have JupyterLab, the command above just adds the fsspec extension and the S3 backend.

---

Start MinIO locally (Docker)

# create a directory to store MinIO data
mkdir -p ~/minio-data

# run MinIO with S3 API on :9000 and Console on :9001
# credentials are set to the defaults below for local testing only
# (change them for anything beyond local dev)
docker run -d --name minio \
  -p 9000:9000 -p 9001:9001 \
  -e MINIO_ROOT_USER=minioadmin \
  -e MINIO_ROOT_PASSWORD=minioadmin \
  -v ~/minio-data:/data \
  minio/minio server /data --console-address ":9001"

• S3 API: http://localhost:9000

• Web console: http://localhost:9001 (login: minioadmin / minioadmin)

Create a bucket in the console (e.g., test-bucket): Buckets → Create bucket.

---

Configure the extension

Create or edit ~/.jupyter/jupyter-fsspec.yaml and add a source for your MinIO bucket. This example assumes you made a bucket called test-bucket.

# ~/.jupyter/jupyter-fsspec.yaml
sources:
  - name: 'MinIO (local)'
    path: 's3://test-bucket' # bucket you created
    args: []
    kwargs:
      # authentication for MinIO
      anon: false
      key: 'minioadmin'
      secret: 'minioadmin'

      # point s3fs at your local MinIO endpoint
      use_ssl: false
      client_kwargs:
        endpoint_url: 'http://127.0.0.1:9000'

      # ensure path-style URLs (works best on localhost) and v4 signing
      config_kwargs:
        signature_version: 's3v4'
        s3:
          addressing_style: 'path'

Note

• endpoint_url directs s3fs to MinIO instead of AWS.

• addressing_style: path avoids bucket.localhost hostnames by using path‑style URLs.

• Keep use_ssl: false for local HTTP MinIO. If you terminate TLS, switch to true and use https:// in endpoint_url.

---

Use it in JupyterLab

Start JupyterLab. Open the Jupyter fsspec sidebar and select “MinIO (local)” to browse the bucket. Right‑click for actions such as copying the object path or uploading files (see Uploading Files).