Getting Started with Boto — boto v2.27.0

### Navigation

- index
- modules |
- next |
- previous |
- boto v2.27.0 »

# Getting Started with Boto

This tutorial will walk you through installing and configuring `boto`, as 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.

## Installing Boto

You can use `pip` to install the latest released version of `boto`:

    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

Note

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 like `boto.cloudsearch`, `boto.manage` & `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 `virtualenv`, which provides isolated environments. First, install the `virtualenv` Python package:

    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 `virtualenvwrapper`):

    mkdir ~/.virtualenvs
    virtualenv ~/.virtualenvs/boto

You can now activate the virtual environment:

    source ~/.virtualenvs/boto/bin/activate

Now, any usage of `python` or `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:

    deactivate

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`.

## Making Connections

`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')

## Troubleshooting Connections

When calling the various `connect_*` functions, you might run into an error like this:

    >>> 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 created a `~/.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.

## Next Steps

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.

### Navigation

- index
- modules |
- next |
- previous |
- boto v2.27.0 »