AWS Boto3’s S3 API provides two methods that can be used to upload a file to an S3 bucket. These methods are:

  • put_object
  • upload_file

In this article, we will look at the differences between these methods and when to use them.

Table of contents


put_object adds an object to an S3 bucket. This method maps directly to the low-level S3 API defined in botocore. The method signature for put_object can be found here.


  • Configurable - Since put_object maps to the low-level S3 API, it accepts a lot of different parameters and thus can be configured based on your needs.


  • No support for multipart uploads: AWS S3 has a limit of 5 GB for a single upload operation. put_object doesn’t support the ability to upload files larger than 5 GB.


The upload_file API is also used to upload a file to an S3 bucket. The API exposed by upload_file is much simpler as compared to put_object. The details of the API can be found here.


  • Simpler API: easy to use and understand
  • Supports multipart uploads: Leverages S3 Transfer Manager and provides support for multipart uploads.


Both put_object and upload_file provide the ability to upload a file to an S3 bucket. You should use:

  • upload_file if you want a simple API or you are uploading large files (>5GB) to your S3 bucket.
  • put_object if you need additional configurability like setting the ACL on the uploaded object.