---
id: ec2-metadata
version: "3.0.0"
license: MIT
license_treatment: permissive
maintenance: active
---

# ec2-metadata — An easy interface to query the EC2 metadata API, with caching.

License: permissive · Maintenance: active · Downloads: 2.4M/mo

## What it is and what it does

ec2-metadata is a Python library that provides a clean interface to the AWS EC2 Instance Metadata Service v2 (IMDSv2), which is more secure against SSRF attacks than the older v1 service. It wraps urllib3 to handle HTTP requests to the metadata endpoint and caches most attributes on first access, since EC2 instance metadata is largely immutable without stopping the instance.

The library exposes a singleton instance (ec2_metadata) with attributes like region, instance_id, availability_zone, iam_security_credentials, and account_id. Most attributes are cached using functools.cached_property and can be cleared individually or all at once. It handles IMDSv2's token-based authentication automatically and is designed as a lightweight alternative to boto3 for applications that only need metadata, not the full AWS SDK.

Use it for:

- Retrieve the current EC2 instance's region or availability zone at runtime for region-aware application logic.
- Fetch temporary IAM security credentials from instance metadata for AWS API calls without managing long-lived keys.
- Determine instance identity and configuration (instance type, AMI ID, account ID) for logging, monitoring, or auto-discovery.
- Build Docker containers on EC2 that need to query instance metadata without adding boto3 as a dependency.
- Implement health checks or lifecycle hooks that read uncached metadata like instance_action or autoscaling target state.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Queries the EC2 Instance Metadata Service v2 to retrieve instance configuration data (region, instance ID, IAM credentials, availability zone, and similar) with built-in caching.

Yes. This is a stable, actively maintained library with no known vulnerabilities, low install friction, and a permissive MIT license. It solves a real gap left by boto3's lack of a metadata utility. Install it if you're running on EC2 and need to query instance metadata without pulling in the full AWS SDK.

## Install

pip install ec2-metadata
uv add ec2-metadata
poetry add ec2-metadata

## Installing ec2-metadata

Before you install: Low friction install with a single runtime dependency (urllib3). Actively maintained as of 2026-02-11, with recent commits and no known vulnerabilities. Supports Python 3.10 through 3.14.

License in practice: MIT license permits free use, modification, and distribution with minimal restrictions—suitable for both open-source and commercial projects.

Quickstart:

pip install ec2-metadata

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

Must be running on an EC2 instance with access to the metadata service. IMDSv2 has a default hop limit of 1, which can cause timeouts in Docker containers; reconfigure with aws ec2 modify-instance-metadata-options --http-put-response-hop-limit 3 if needed.

Verify before relying:

- Whether the singleton instance pattern (ec2_metadata) is thread-safe for concurrent access in multi-threaded applications.
- Performance characteristics of the metadata API calls under high-frequency access patterns.
- Behavior when running outside EC2 or when the metadata service is unavailable.

## Package facts

- License: MIT (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 2.4M/month (top 5,000 on PyPI)
- Known vulnerabilities: none known

## Tags

ec2 metadata api client, aws instance metadata query, ec2 instance info retrieval, aws metadata service v2, ec2 region and instance id, aws iam credentials from metadata, ec2 instance configuration, aws-ec2, metadata-service, instance-discovery

[View on SkillFed](https://skillfed.io/packages/ec2-metadata) · [View on PyPI](https://pypi.org/project/ec2-metadata/)