{"id":2017,"library":"ec2-metadata","title":"EC2 Metadata Python Library","description":"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.","status":"active","version":"3.0.0","language":"en","source_language":"en","source_url":"https://github.com/adamchainz/ec2-metadata","tags":["aws","ec2","metadata","cloud","instance-metadata","imds","imds-v2"],"install":[{"cmd":"pip install ec2-metadata","lang":"bash","label":"Install stable version"}],"dependencies":[],"imports":[{"symbol":"ec2_metadata","correct":"from ec2_metadata import ec2_metadata"}],"quickstart":{"code":"from ec2_metadata import ec2_metadata\n\ntry:\n    print(f\"Region: {ec2_metadata.region}\")\n    print(f\"Instance ID: {ec2_metadata.instance_id}\")\n    print(f\"AMI ID: {ec2_metadata.ami_id}\")\n    print(f\"Instance Type: {ec2_metadata.instance_type}\")\nexcept Exception as e:\n    print(f\"Could not retrieve EC2 metadata: {e}\")\n    print(\"This code must be run on an EC2 instance with IMDSv2 enabled and accessible.\")","lang":"python","description":"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."},"warnings":[{"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'.","message":"ec2-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.","severity":"breaking","affected_versions":"<3.0.0 to 3.0.0+"},{"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`.","message":"When 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.","severity":"gotcha","affected_versions":"All versions using IMDSv2 (3.0.0+)"},{"fix":"Use AWS Secrets Manager or Parameter Store for sensitive data and retrieve them securely within your application.","message":"Instance 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.","severity":"gotcha","affected_versions":"All versions (inherent to EC2 IMDS design)"},{"fix":"Migrate from `boto.utils.get_instance_metadata` to `ec2-metadata` or `boto3`'s equivalent if available for specific needs.","message":"The 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.","severity":"deprecated","affected_versions":"Prior to boto3"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}