Registry / aws / ec2-metadata

ec2-metadata

library3.0.0pypypi✓ verified 25d ago

ec2-metadata is a Python library that provides an easy, cached interface to query the EC2 Instance Metadata Service (IMDS). It supports IMDSv2 exclusively and is designed for use within EC2 instances to retrieve details like instance ID, AMI ID, region, and more. The current version is 3.0.0, and it is actively maintained.

aws http-networking

pip install ec2-metadata

github ↗package ↗changelog ↗

INSTALL

IMPORT

SIG · EC2-METADATA

ec2-metadata

awspythonv3.0.0

Install

1.9s avg

Import

253ms

Disk

17MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v3.0.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.250s · 18.8MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.9s · import 0.256s · 19MB

17MB installed

● package 17MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

ec2_metadata

✓ from ec2_metadata import ec2_metadata

Demonstrates how to retrieve basic EC2 instance metadata attributes using the singleton `ec2_metadata` object. This code should be run from within an EC2 instance.

from ec2_metadata import ec2_metadata try: print(f"Region: {ec2_metadata.region}") print(f"Instance ID: {ec2_metadata.instance_id}") print(f"AMI ID: {ec2_metadata.ami_id}") print(f"Instance Type: {ec2_metadata.instance_type}") except Exception as e: print(f"Could not retrieve EC2 metadata: {e}") print("This code must be run on an EC2 instance with IMDSv2 enabled and accessible.")

ec2-metadata --version

Debug

Known issues

breakingec2-metadata version 3.0.0 and above exclusively uses Instance Metadata Service Version 2 (IMDSv2). If your EC2 instance is configured to *only* allow IMDSv1, this library will not work. Ensure your instance supports IMDSv2.

fix

Ensure EC2 instances are configured to support IMDSv2 (default behavior) or explicitly enable it. Consult AWS documentation on 'Transition to using Instance Metadata Service Version 2'.

affects: <3.0.0 to 3.0.0+

gotchaWhen running `ec2-metadata` within a Docker container on an EC2 instance, you might encounter `requests.exceptions.ReadTimeout` errors. This is often due to IMDSv2's default IP hop limit of 1.

fix

Reconfigure your EC2 instance's metadata options to allow more hops, e.g., `aws ec2 modify-instance-metadata-options --instance-id <instance-id> --http-put-response-hop-limit 3`.

affects: All versions using IMDSv2 (3.0.0+)

gotchaInstance metadata and user data are not cryptographically protected and are accessible by any user or process on the instance. Do not store sensitive information like passwords or private keys in user data.

fix

Use AWS Secrets Manager or Parameter Store for sensitive data and retrieve them securely within your application.

affects: All versions (inherent to EC2 IMDS design)

deprecatedThe functionality provided by the older `boto` library's `boto.utils.get_instance_metadata` for retrieving EC2 metadata is not ported to `boto3`. `ec2-metadata` was created to serve as a standalone replacement for this specific functionality.

fix

Migrate from `boto.utils.get_instance_metadata` to `ec2-metadata` or `boto3`'s equivalent if available for specific needs.

affects: Prior to boto3

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'ec2_metadata'

The 'ec2-metadata' Python package has not been installed in the current environment.

fix

Run `pip install ec2-metadata` to install the library.

requests.exceptions.ReadTimeout: Read timed out.

The EC2 Instance Metadata Service (IMDS) did not respond within the configured timeout. This often occurs when running in containerized environments (like Docker or Kubernetes pods) where the `HttpPutResponseHopLimit` for IMDSv2 is set to the default of 1, preventing access from the container to the metadata service.

fix

For containerized environments, reconfigure your EC2 instance's metadata options to increase the `HttpPutResponseHopLimit` to a value like 3: `aws ec2 modify-instance-metadata-options --instance-id <your-instance-id> --http-put-response-hop-limit 3`. Additionally, ensure no firewalls or proxies are blocking access to `http://169.254.169.254` within the instance.

requests.exceptions.ConnectionError: ('Connection aborted.', ConnectionResetError(104, 'Connection reset by peer'))

The EC2 Instance Metadata Service (IMDS) is unreachable. This typically happens when the code is not executing on an actual EC2 instance, if IMDS is explicitly disabled on the instance, or if network configurations (such as local firewalls, proxy settings, or incorrect route tables) prevent access to `http://169.254.169.254`.

fix

Verify that the code is running on an EC2 instance. Ensure that IMDS is enabled for the instance. Check local firewall rules (e.g., `iptables`, `firewalld`) and proxy configurations on the instance to ensure they allow outbound HTTP access to `http://169.254.169.254`.

Upgrade

Version history

3.0.0latest on PyPI · released Feb 11, 2026

Audit

Dependencies

No dependency data recorded yet.

Agent activity

10 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/adamchainz/ec2-metadata ↗

packagehttps://pypi.org/project/ec2-metadata/ ↗

changeloghttps://github.com/adamchainz/ec2-metadata/blob/main/CHANGELOG.rst ↗