Skip to main content

An easy interface to query the EC2 metadata API, with caching.

Project description

An easy interface to query the EC2 metadata API, with caching.

A quick example:

>>> from ec2_metadata import ec2_metadata
>>> print(ec2_metadata.region)
>>> print(ec2_metadata.instance_id)


Use pip:

pip install ec2-metadata

Tested on Python 2.7 and Python 3.6.


boto came with a utility function to retrieve the instance metadata as a lazy loading dictionary, boto.utils.get_instance_metadata, but this has not been ported to boto3, as per this issue. I thought that rather than building a new version inside boto3 it would work well as a standalone library.


There is a special singleton object in the module to import:

from ec2_metadata import ec2_metadata

This object has a number of lazy attributes that pull the respective data from the metadata service on first access, all documented below. They are all strings (Python 3 str) except where noted.

Attributes don’t entirely correspond to the paths in the metadata service - they have been ‘cleaned up’. You may also want to refer to the metadata service docs to understand the exact contents.

Attribute Name Contents
account_id The current AWS account ID, e.g. '123456789012'
ami_id The ID of the AMI used to launch the instance, e.g. 'ami-123456'
availability_zone The name of the current AZ e.g. 'eu-west-1a'
ami_launch_index The index of the instance in the launch request, zero-based, e.g. 0
ami_manifest_path The path to the AMI manifest file in Amazon S3, or '(unknown)' on EBS-backed AMI’s
instance_id The current instance’s ID, e.g. 'i-123456'
instance_identity_document A dictionary of dynamic data, see AWS docs
instance_type The current instance’s type, e.g. 't2.nano'
mac The instance’s MAC address, e.g. '0a:d2:ae:4d:f3:12'
private_hostname The private IPv4 DNS hostname of the instance, e.g. ''
private_ipv4 The private IPv4 of the instance, e.g. ''
public_hostname The public DNS hostname of the instance, e.g. ''
public_ipv4 The public IPv4 address of the instance, e.g. ''
region The region the instance is running in, e.g. 'eu-west-1'
reservation_id The ID of the reservation used to launch the instance, e.g. 'r-12345678901234567'
security_groups List of security groups by name, e.g. ['ssh-access', 'custom-sg-1']'
user_data (bytes) The raw user data assigned to the instance (not base64 encoded), or None if there is none.

These values should all be safe to cache for the lifetime of your Python process, since they are (nearly entirely) immutable (some things can change, e.g. public_ipv4 when you attach an Elastic IP to the instance). If you need to flush the caching, you can call ec2_metadata.clear_all() to wipe it all.


Pending Release

1.1.0 (2017-08-07)

  • Add security_groups and user_data attributes.

1.0.0 (2017-06-16)

  • First release on PyPI, featuring ec2_metadata object.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Filename, size & hash SHA256 hash help File type Python version Upload date
ec2_metadata-1.1.0-py2.py3-none-any.whl (6.6 kB) Copy SHA256 hash SHA256 Wheel 2.7
ec2-metadata-1.1.0.tar.gz (4.9 kB) Copy SHA256 hash SHA256 Source None

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN SignalFx SignalFx Supporter DigiCert DigiCert EV certificate StatusPage StatusPage Status page