Install & Compatibility
Where this runs
tested against v1.2.3 · 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
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.156s · 18.1MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.5s · import 0.144s · 19MB
16MB installed
● package 16MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Amplitude
✓ from amplitude import Amplitude
BaseEvent
✓ from amplitude import BaseEvent
Identify
✓ from amplitude import Identify
Initializes the Amplitude SDK with an API key (preferably from environment variables), tracks a custom event, and sets user properties. It emphasizes the importance of calling `flush()` to ensure events are sent before the application terminates, and shows how to configure for EU data residency.
import os
from amplitude import Amplitude, BaseEvent, Identify
import time
AMPLITUDE_API_KEY = os.environ.get("AMPLITUDE_API_KEY", "YOUR_AMPLITUDE_API_KEY")
# Initialize the SDK
# For EU data residency, add: server_zone='EU' to Amplitude(API_KEY, ...)
amplitude = Amplitude(AMPLITUDE_API_KEY)
# Example: Configure for EU data residency (uncomment if applicable)
# amplitude.configuration.server_zone = 'EU'
# Create and track a basic event
print("Tracking a 'User Logged In' event...")
event = BaseEvent(
event_type="User Logged In",
user_id="user_123",
device_id="device_abc",
event_properties={
"login_method": "email",
"timestamp": int(time.time())
}
)
amplitude.track(event)
# Identify a user and set/update user properties
print("Setting user properties for 'user_123'...")
identify = Identify()
identify.set("plan", "premium")
identify.set_once("initial_referrer", "google") # Set only once
identify.add("login_count", 1) # Increment a property
amplitude.identify("user_123", identify)
# Important: Flush events before application exit to ensure delivery
print("Flushing events...")
amplitude.flush()
print("Events sent and flushed. Check your Amplitude project.")
Debug
Known issues
breakingMajor version updates (e.g., v1.x to v2.x) may introduce significant changes to public interfaces, behaviors, or semantics. Always review upgrade guidelines carefully when moving to a new major version.fixConsult the official Amplitude documentation and release notes for specific migration guides and breaking changes when updating to a new major version.
affects: All major version transitions (e.g., from an hypothetical 0.x to 1.x or 1.x to 2.x)
gotchaEvents are queued in memory and sent in batches. If your application exits immediately after calling `track()`, events might not be sent. You must call `client.flush()` to ensure all buffered events are delivered.fixExplicitly call `amplitude.flush()` before your application terminates, especially in short-lived scripts or serverless functions. You can also configure `flush_queue_size` and `flush_interval_millis` for batching behavior.
affects: All versions
gotchaBy default, data is sent to Amplitude's US servers. If your project requires EU data residency, you must explicitly configure the `server_zone` to 'EU' during SDK initialization.fixInitialize the SDK with `amplitude = Amplitude(API_KEY, configuration={'server_zone': 'EU'})` or set it via `amplitude.configuration.server_zone = 'EU'` after initialization. affects: All versions
gotchaUsing an incorrect API key or having multiple SDK instances (e.g., different Amplitude projects within the same application) without proper separation can lead to events not being ingested or being sent to the wrong project.fixVerify that the correct API key is used during `Amplitude` client initialization. If using multiple instances, ensure each is configured with its specific API key and managed distinctly.
affects: All versions
gotchaAmplitude has a minimum length requirement for `user_id` and `device_id`. Providing IDs shorter than this minimum can result in 400 errors and events not being tracked.fixEnsure that `user_id` and `device_id` values meet the minimum length requirements (typically 5 characters, configurable via `min_id_length`).
affects: All versions
gotchaAmplitude enforces a throttling limit of 30 events per user or device per second. Exceeding this limit can cause events to be throttled and logged with a warning, leading to incomplete data.fixDistribute your event tracking across time or reduce the frequency of event calls for individual users/devices to stay within the throttling limit.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'amplitude'
This error occurs when the 'amplitude-analytics' package is not installed in your Python environment.
fixInstall the package using pip: 'pip install amplitude-analytics'.
ImportError: cannot import name 'Amplitude' from 'amplitude'
This error occurs when attempting to import 'Amplitude' directly from 'amplitude', which is incorrect.
fixUse the correct import statement: 'from amplitude import Amplitude'.
AttributeError: 'Amplitude' object has no attribute 'track_event'
This error occurs when calling a non-existent method 'track_event' on an 'Amplitude' object.
fixUse the correct method name: 'track'. For example: 'amplitude_instance.track(event_name, event_properties)'.
TypeError: track() missing 1 required positional argument: 'event_name'
This error occurs when calling the 'track' method without providing the required 'event_name' argument.
fixEnsure you provide the 'event_name' argument when calling 'track'. For example: 'amplitude_instance.track('event_name', event_properties)'. ValueError: Invalid API key
This error occurs when an incorrect or invalid API key is used to initialize the 'Amplitude' client.
fixVerify and use the correct API key when initializing the 'Amplitude' client: 'amplitude_instance = Amplitude(api_key)'.
Upgrade
Version history
1.2.3latest on PyPI · released Mar 31, 2026
Audit
Dependencies
No dependency data recorded yet.