You are viewing the documentation for an older version of boto (boto2).
Boto3, the next version of Boto, is now stable and recommended for general use. It can be used side-by-side with Boto in the same project, so it is easy to start using Boto3 in your existing projects as well as new projects. Going forward, API updates and all new feature work will be focused on Boto3.
For more information, see the documentation for boto3.
Getting Started with Boto¶
This tutorial will walk you through installing and configuring
well how to use it to make API calls.
This tutorial assumes you are familiar with Python & that you have registered
for an Amazon Web Services account. You’ll need retrieve your
Access Key ID and
Secret Access Key from the web-based console.
You can use
pip to install the latest released version of
pip install boto
If you want to install
boto from source:
git clone git://github.com/boto/boto.git cd boto python setup.py install
For most services, this is enough to get going. However, to support
everything Boto ships with, you should additionally run
pip install -r requirements.txt.
This installs all additional, non-stdlib modules, enabling use of things
boto.mashups, as well as
covering everything needed for the test suite.
Using Virtual Environments¶
Another common way to install
boto is to use a
provides isolated environments. First, install the
pip install virtualenv
Next, create a virtual environment by using the
virtualenv command and
specifying where you want the virtualenv to be created (you can specify
any directory you like, though this example allows for compatibility with
mkdir ~/.virtualenvs virtualenv ~/.virtualenvs/boto
You can now activate the virtual environment:
Now, any usage of
pip (within the current shell) will default
to the new, isolated version within your virtualenv.
You can now install
boto into this virtual environment:
pip install boto
When you are done using
boto, you can deactivate your virtual environment:
If you are creating a lot of virtual environments, virtualenvwrapper is an excellent tool that lets you easily manage your virtual environments.
Configuring Boto Credentials¶
You have a few options for configuring
boto (see Boto Config).
For this tutorial, we’ll be using a configuration file. First, create a
~/.boto file with these contents:
[Credentials] aws_access_key_id = YOURACCESSKEY aws_secret_access_key = YOURSECRETKEY
boto supports a number of configuration values. For more information,
see Boto Config. The above file, however, is all we need for now.
You’re now ready to use
boto provides a number of convenience functions to simplify connecting to a
service. For example, to work with S3, you can run:
>>> import boto >>> s3 = boto.connect_s3()
If you want to connect to a different region, you can import the service module
and use the
connect_to_region functions. For example, to create an EC2
client in ‘us-west-2’ region, you’d run the following:
>>> import boto.ec2 >>> ec2 = boto.ec2.connect_to_region('us-west-2')
When calling the various
connect_* functions, you might run into an error
>>> import boto >>> s3 = boto.connect_s3() Traceback (most recent call last): File "<stdin>", line 1, in <module> File "boto/__init__.py", line 121, in connect_s3 return S3Connection(aws_access_key_id, aws_secret_access_key, **kwargs) File "boto/s3/connection.py", line 171, in __init__ validate_certs=validate_certs) File "boto/connection.py", line 548, in __init__ host, config, self.provider, self._required_auth_capability()) File "boto/auth.py", line 668, in get_auth_handler 'Check your credentials' % (len(names), str(names))) boto.exception.NoAuthHandlerFound: No handler was ready to authenticate. 1 handlers were checked. ['HmacAuthV1Handler'] Check your credentials
This is because
boto cannot find credentials to use. Verify that you have
~/.boto file as shown above. You can also turn on debug logging
to verify where your credentials are coming from:
>>> import boto >>> boto.set_stream_logger('boto') >>> s3 = boto.connect_s3() 2012-12-10 17:15:03,799 boto [DEBUG]:Using access key found in config file. 2012-12-10 17:15:03,799 boto [DEBUG]:Using secret key found in config file.
Interacting with AWS Services¶
Once you have a client for the specific service you want, there are methods on that object that will invoke API operations for that service. The following code demonstrates how to create a bucket and put an object in that bucket:
>>> import boto >>> import time >>> s3 = boto.connect_s3() # Create a new bucket. Buckets must have a globally unique name (not just # unique to your account). >>> bucket = s3.create_bucket('boto-demo-%s' % int(time.time())) # Create a new key/value pair. >>> key = bucket.new_key('mykey') >>> key.set_contents_from_string("Hello World!") # Sleep to ensure the data is eventually there. >>> time.sleep(2) # Retrieve the contents of ``mykey``. >>> print key.get_contents_as_string() 'Hello World!' # Delete the key. >>> key.delete() # Delete the bucket. >>> bucket.delete()
Each service supports a different set of commands. You’ll want to refer to the other guides & API references in this documentation, as well as referring to the official AWS API documentation.
For many of the services that
boto supports, there are tutorials as
well as detailed API documentation. If you are interested in a specific
service, the tutorial for the service is a good starting point. For instance,
if you’d like more information on S3, check out the S3 Tutorial
and the S3 API reference.