Nov 20, 20266 min read

Generate S3 Presigned URLs in Python

Create presigned download and upload URLs with boto3, use presigned POST to cap upload size, avoid the signature, Region and expiry mistakes that break URLs, and test the flow locally.

Illustration for Generate S3 Presigned URLs in Python

A presigned URL lets a browser download or upload one S3 object directly, so the file never passes through your Python backend. boto3 signs it locally with no API call, which looks trivial until a URL fails with SignatureDoesNotMatch or dies hours before its expiry.

This guide covers download URLs, upload URLs, size-limited POST uploads and the mistakes behind most broken links.

S3 presigned URLs in Python at a glance

Goalboto3 methodWatch out for
Temporary download linkgenerate_presigned_url("get_object", ...)Credentials that expire before the URL
Browser upload, simplegenerate_presigned_url("put_object", ...)Signed Content-Type must match, no size limit
Browser upload, size limitgenerate_presigned_post(...)Client sends a multipart form, not a PUT
Force a download filenameResponseContentDisposition in ParamsQuote the filename
Maximum lifetimeExpiresIn up to 604800 secondsRole credentials usually expire sooner

How do you create a download URL?

Create the client with the bucket's Region and Signature Version 4. Without an explicit Region, a client in us-east-1 can sign a URL for a bucket elsewhere, and S3 answers with a redirect or an error instead of the object:

import uuid import boto3 from botocore.config import Config # Pin the Region and SigV4 so the URL is signed for the bucket's regional endpoint. s3 = boto3.client( "s3", region_name="eu-west-1", config=Config(signature_version="s3v4", s3={"addressing_style": "virtual"}), ) BUCKET = "acme-user-uploads" def download_url(key: str, filename: str) -> str: return s3.generate_presigned_url( "get_object", Params={ "Bucket": BUCKET, "Key": key, "ResponseContentDisposition": f'attachment; filename="{filename}"', }, ExpiresIn=900, # seconds ) def upload_url(content_type: str) -> dict: key = f"avatars/{uuid.uuid4()}" url = s3.generate_presigned_url( "put_object", Params={"Bucket": BUCKET, "Key": key, "ContentType": content_type}, ExpiresIn=300, ) # The client must send exactly this Content-Type header, or S3 rejects the signature. return {"key": key, "url": url, "headers": {"Content-Type": content_type}} def upload_form(max_bytes: int = 5 * 1024 * 1024) -> dict: key = f"avatars/{uuid.uuid4()}" return s3.generate_presigned_post( Bucket=BUCKET, Key=key, Fields={"Content-Type": "image/png"}, Conditions=[ {"Content-Type": "image/png"}, ["content-length-range", 1, max_bytes], ], ExpiresIn=300, )

generate_presigned_url does not check that the object exists or that your role may read it. It signs whatever you ask for, and the permission check happens when the browser uses the URL, so a missing s3:GetObject shows up as a 403 on the client rather than an exception in your code.

How do you let a browser upload a file?

upload_url returns a URL for a PUT. The ContentType in Params becomes part of the signature, so the browser must send the same Content-Type header, and the server generates the key so a client cannot overwrite someone else's object:

const { url, headers, key } = await fetch("/uploads/avatar", { method: "POST" }).then((r) => r.json()); await fetch(url, { method: "PUT", headers, body: file }); // file from an <input type="file">

A presigned PUT cannot limit the file size. When that matters, upload_form uses presigned POST, where a policy document with content-length-range makes S3 reject anything larger. The browser sends a multipart form with the returned fields first and the file last:

const { url, fields } = await fetch("/uploads/avatar-form", { method: "POST" }).then((r) => r.json()); const form = new FormData(); Object.entries(fields).forEach(([k, v]) => form.append(k, v)); form.append("file", file); // must be the last field await fetch(url, { method: "POST", body: form });

Browser uploads also need a CORS rule on the bucket that allows your origin and the PUT or POST method, or the browser blocks the request before S3 sees it.

Why do presigned URLs stop working early?

A URL is only valid while the credentials that signed it are. The S3 presigned URL docs set the Signature Version 4 maximum at seven days, but a URL signed with temporary credentials expires when the session token does. On ECS, Lambda and EKS the code runs with role credentials that rotate every few hours, so a seven-day ExpiresIn can quietly become a six-hour link. For links that must last days, sign on demand when the user clicks rather than storing URLs, or serve the files through CloudFront signed URLs, which use a key pair you control.

The other common failure is SignatureDoesNotMatch, which means the request differs from what was signed: a different Content-Type, a client created for the wrong Region, or a proxy that rewrites headers. The signing code in the boto3 presigned URL guide shows the same parameters, and comparing the canonical request in the S3 error body with what you signed usually points at the difference.

Which IAM permissions are needed?

The role that signs needs the permission the URL grants: s3:GetObject for downloads and s3:PutObject for uploads, on the bucket's objects. If the bucket uses SSE-KMS with a customer managed key, add kms:Decrypt for downloads and kms:GenerateDataKey for uploads.

How do you test it locally?

moto can run as a local server, and pointing the client's endpoint_url at it lets a test sign a URL, upload with requests and download the object again. It checks that the signing code and the client agree on headers, but it does not enforce IAM, so the permission check still has to happen in an AWS account.

Signed URLs from a bucket declared in Python with Encore

Encore

Encore works alongside your Python framework, here FastAPI, as an SDK that declares infrastructure in code, and an object storage bucket is a module-level variable with signed URL methods on it. Encore for Python is in private beta, and you can request an invite. There is no client, Region or signature configuration in the code, and encore run serves the bucket locally.

Application code passes through Encore and infrastructure guardrails to resources provisioned in your own AWS or GCP account.
Encore provisions the infrastructure your application needs in your own AWS or GCP account.
# uploads/main.py import uuid import encore from encore.storage import objects from fastapi import FastAPI, HTTPException # S3 on AWS, Cloud Storage on GCP, local storage under `encore run`. avatars = objects.Bucket("avatars", versioned=False) app = FastAPI() @app.post("/avatars/upload-url") async def avatar_upload_url() -> dict: key = f"{uuid.uuid4()}.png" url = await avatars.signed_upload_url(key, ttl=300) return {"key": key, "url": url} @app.get("/avatars/{key}/url") async def avatar_download_url(key: str) -> dict: if not await avatars.exists(key): raise HTTPException(status_code=404, detail="no such avatar") return {"url": await avatars.signed_download_url(key, ttl=900)} if __name__ == "__main__": encore.run(app)

The ttl is in seconds, the browser uploads with a PUT to the returned URL, and the existence check keeps the download endpoint from handing out links to objects that do not exist. The service is registered with an encore.service.json file next to the code, and the SDK needs Python 3.9 or later. On deploy to your own AWS account, Encore creates the S3 bucket, with CloudFront in front of public buckets as the AWS infrastructure docs describe, and Encore provisions an IAM role for the service.

A coding agent asked to add document uploads next to avatars declares a second bucket in the same change as the endpoint and tests the full upload and download locally, which is where Region and header mismatches would otherwise surface after deploy.

Request a private-beta invite to try this setup:

Try Encore →

Frequently asked questions

How do I generate a presigned URL for S3 in Python?

Call s3.generate_presigned_url("get_object", Params={"Bucket": bucket, "Key": key}, ExpiresIn=900) on a boto3 S3 client. For uploads use "put_object" as the client method, and include ContentType in Params if the client will send a Content-Type header, because the header becomes part of the signature.

How long can an S3 presigned URL be valid?

Up to seven days with Signature Version 4. The URL also stops working when the credentials that signed it expire, so a URL signed with an ECS task role or Lambda role credentials can die after a few hours even if ExpiresIn was longer.

Why does my presigned URL return SignatureDoesNotMatch?

The request does not match what was signed. Common causes are a Content-Type header that differs from the signed one on a PUT, a client created for a different Region than the bucket, or a proxy that changes headers or the query string. Sign with the bucket's Region and send exactly the headers you signed.

How do I limit the size of a presigned upload?

Use generate_presigned_post with a ["content-length-range", min, max] condition, and S3 rejects larger files. A presigned PUT URL cannot enforce a maximum size. Encore is another option, where a bucket's signed_upload_url creates the URL from a declared bucket with no client setup. Encore for Python is in private beta (sign up at /py).

Deploy to your cloud on AWS and Google Cloud
without managing infrastructure

Encore lets developers and agents define application infrastructure directly in code, then automatically provisions it from local development to production in your AWS or GCP account.

~/orders — claude
Claude Code
Claude Code v2.1.180Opus 5.5~/orders