| 1 |
.. _guide_quickstart: |
| 2 |
|
| 3 |
Quickstart |
| 4 |
========== |
| 5 |
|
| 6 |
This guide details the steps needed to install or update the AWS SDK for Python. |
| 7 |
|
| 8 |
The SDK is composed of two key Python packages: Botocore (the library providing the low-level |
| 9 |
functionality shared between the Python SDK and the AWS CLI) and Boto3 (the package implementing the |
| 10 |
Python SDK itself). |
| 11 |
|
| 12 |
.. note:: |
| 13 |
|
| 14 |
Documentation and developers tend to refer to the AWS SDK for Python as "Boto3," and this |
| 15 |
documentation often does so as well. |
| 16 |
|
| 17 |
Installation |
| 18 |
------------ |
| 19 |
|
| 20 |
To use Boto3, you first need to install it and its dependencies. |
| 21 |
|
| 22 |
.. _quickstart_install_python: |
| 23 |
|
| 24 |
Install or update Python |
| 25 |
~~~~~~~~~~~~~~~~~~~~~~~~ |
| 26 |
|
| 27 |
Before installing Boto3, ensure you're using Python 3.10 or later. |
| 28 |
For details on how to update your project from older versions of Python, |
| 29 |
see :ref:`guide_migration_py3`. |
| 30 |
|
| 31 |
For information about how to get the latest version of Python, see the official `Python |
| 32 |
documentation <https://www.python.org/downloads/>`_. |
| 33 |
|
| 34 |
Setup a virtual environment |
| 35 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 36 |
|
| 37 |
Once you have a supported version of Python installed, you should set up |
| 38 |
your workspace by creating a virtual environment and activate it:: |
| 39 |
|
| 40 |
$ python -m venv .venv |
| 41 |
... |
| 42 |
$ source .venv/bin/activate |
| 43 |
|
| 44 |
This provides an isolated space for your installation that will avoid unexpected |
| 45 |
interactions with packages installed at the system level. Skipping this step may |
| 46 |
result in unexpected dependency conflicts or failures with other tools installed |
| 47 |
on your system. |
| 48 |
|
| 49 |
Install Boto3 |
| 50 |
~~~~~~~~~~~~~ |
| 51 |
|
| 52 |
Install the latest Boto3 release via :command:`pip`:: |
| 53 |
|
| 54 |
pip install boto3 |
| 55 |
|
| 56 |
If your project requires a specific version of Boto3, or has compatibility concerns with |
| 57 |
certain versions, you may provide constraints when installing:: |
| 58 |
|
| 59 |
# Install Boto3 version 1.0 specifically |
| 60 |
pip install boto3==1.0.0 |
| 61 |
|
| 62 |
# Make sure Boto3 is no older than version 1.15.0 |
| 63 |
pip install boto3>=1.15.0 |
| 64 |
|
| 65 |
# Avoid versions of Boto3 newer than version 1.15.3 |
| 66 |
pip install boto3<=1.15.3 |
| 67 |
|
| 68 |
.. note:: |
| 69 |
|
| 70 |
The latest development version of Boto3 is on `GitHub <https://github.com/boto/boto3>`_. |
| 71 |
|
| 72 |
Using the AWS Common Runtime (CRT) |
| 73 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 74 |
|
| 75 |
In addition to the default install of Boto3, you can choose to include the new `AWS Common Runtime <https://docs.aws.amazon.com/sdkref/latest/guide/common-runtime.html>`_ |
| 76 |
(CRT). The AWS CRT is a collection of modular packages that serve as a new foundation for AWS SDKs. |
| 77 |
Each library provides better performance and minimal footprint for the functional area it |
| 78 |
implements. Using the CRT, SDKs can share the same base code when possible, improving consistency |
| 79 |
and throughput optimizations across AWS SDKs. |
| 80 |
|
| 81 |
When the AWS CRT is included, Boto3 uses it to incorporate features not otherwise |
| 82 |
available in the AWS SDK for Python. |
| 83 |
|
| 84 |
You'll find it used in features like: |
| 85 |
|
| 86 |
- `Amazon S3 Multi-Region Access Points <https://docs.aws.amazon.com/AmazonS3/latest/userguide/MultiRegionAccessPoints.html>`_ |
| 87 |
- `Amazon S3 Object Integrity <https://docs.aws.amazon.com/AmazonS3/latest/userguide/checking-object-integrity.html>`_ |
| 88 |
- Amazon EventBridge Global Endpoints |
| 89 |
|
| 90 |
However, Boto3 doesn't use the AWS CRT by default but you can opt into using it by specifying the |
| 91 |
:code:`crt` `extra feature <https://www.python.org/dev/peps/pep-0508/#extras>`_ when installing Boto3:: |
| 92 |
|
| 93 |
pip install boto3[crt] |
| 94 |
|
| 95 |
To revert to the non-CRT version of Boto3, use this command:: |
| 96 |
|
| 97 |
pip uninstall awscrt |
| 98 |
|
| 99 |
If you need to re-enable CRT, reinstall :code:`boto3[crt]` to ensure you get a compatible version of :code:`awscrt`:: |
| 100 |
|
| 101 |
pip install boto3[crt] |
| 102 |
|
| 103 |
Configuration |
| 104 |
------------- |
| 105 |
|
| 106 |
Before using Boto3, you need to set up authentication credentials for your AWS account using either |
| 107 |
the `IAM Console <https://console.aws.amazon.com/iam/home>`_ or the AWS CLI. You can either choose |
| 108 |
an existing user or create a new one. |
| 109 |
|
| 110 |
For instructions about how to create a user using the IAM Console, see `Creating IAM users |
| 111 |
<https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_create.html#id_users_create_console>`_. |
| 112 |
Once the user has been created, see `Managing access keys |
| 113 |
<https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html#Using_CreateAccessKey>`_ |
| 114 |
to learn how to create and retrieve the keys used to authenticate the user. |
| 115 |
|
| 116 |
If you have the `AWS CLI <http://aws.amazon.com/cli/>`_ installed, then you can use the |
| 117 |
:command:`aws configure` command to configure your credentials file:: |
| 118 |
|
| 119 |
aws configure |
| 120 |
|
| 121 |
Alternatively, you can create the credentials file yourself. By default, its location is |
| 122 |
``~/.aws/credentials``. At a minimum, the credentials file should specify the access key and secret |
| 123 |
access key. In this example, the key and secret key for the account are specified in the ``default`` profile:: |
| 124 |
|
| 125 |
[default] |
| 126 |
aws_access_key_id = YOUR_ACCESS_KEY |
| 127 |
aws_secret_access_key = YOUR_SECRET_KEY |
| 128 |
|
| 129 |
You may also want to add a default region to the AWS configuration file, which is located by default |
| 130 |
at ``~/.aws/config``:: |
| 131 |
|
| 132 |
[default] |
| 133 |
region=us-east-1 |
| 134 |
|
| 135 |
Alternatively, you can pass a ``region_name`` when creating clients and resources. |
| 136 |
|
| 137 |
You have now configured credentials for the default profile as well as a default region to use when |
| 138 |
creating connections. See :ref:`guide_configuration` for in-depth configuration sources and options. |
| 139 |
|
| 140 |
Using Boto3 |
| 141 |
------------ |
| 142 |
|
| 143 |
To use Boto3, you must first import it and indicate which service or services you're going to use:: |
| 144 |
|
| 145 |
import boto3 |
| 146 |
|
| 147 |
# Let's use Amazon S3 |
| 148 |
s3 = boto3.resource('s3') |
| 149 |
|
| 150 |
Now that you have an ``s3`` resource, you can make send requests to the service. The following code uses the ``buckets`` collection to print out all bucket names:: |
| 151 |
|
| 152 |
# Print out bucket names |
| 153 |
for bucket in s3.buckets.all(): |
| 154 |
print(bucket.name) |
| 155 |
|
| 156 |
You can also upload and download binary data. For example, the following |
| 157 |
uploads a new file to S3, assuming that the bucket ``amzn-s3-demo-bucket`` |
| 158 |
already exists:: |
| 159 |
|
| 160 |
# Upload a new file |
| 161 |
with open('test.jpg', 'rb') as data: |
| 162 |
s3.Bucket('amzn-s3-demo-bucket').put_object(Key='test.jpg', Body=data) |
| 163 |
|
| 164 |
:ref:`guide_resources` and :ref:`guide_collections` are covered in more detail in the following |
| 165 |
sections. |