{"id":7693,"library":"rudder-sdk-python","title":"RudderStack Python SDK","description":"RudderStack's Python SDK (`rudder-sdk-python`) is an open-source client for tracking and sending server-side customer event data from Python applications. It acts as an open-source Segment alternative, enabling developers to collect and route event data to various downstream destinations. The library is currently at version 2.1.4 and is actively maintained with regular updates.","status":"active","version":"2.1.4","language":"en","source_language":"en","source_url":"https://github.com/rudderlabs/rudder-sdk-python","tags":["analytics","event tracking","customer data platform","data pipeline","segment alternative"],"install":[{"cmd":"pip install rudder-sdk-python","lang":"bash","label":"Install latest version"}],"dependencies":[],"imports":[{"note":"Aliasing as 'rudder_analytics' (or 'analytics') is a common convention in examples and helps distinguish it from other modules.","wrong":"import rudderstack.analytics","symbol":"rudderstack.analytics","correct":"import rudderstack.analytics as rudder_analytics"}],"quickstart":{"code":"import os\nimport rudderstack.analytics as rudder_analytics\n\n# Set your RudderStack Write Key and Data Plane URL from environment variables\n# Replace with your actual values or use environment variables for production\nWRITE_KEY = os.environ.get('RUDDERSTACK_WRITE_KEY', 'YOUR_WRITE_KEY')\nDATA_PLANE_URL = os.environ.get('RUDDERSTACK_DATA_PLANE_URL', 'YOUR_DATA_PLANE_URL')\n\nrudder_analytics.write_key = WRITE_KEY\nrudder_analytics.dataPlaneUrl = DATA_PLANE_URL\n\n# Optional: Configure debug mode for verbose logging\nrudder_analytics.debug = True\n\n# Identify a user\nrudder_analytics.identify(\n    user_id='user_123',\n    traits={'name': 'John Doe', 'email': 'john.doe@example.com'}\n)\n\n# Track an event\nrudder_analytics.track(\n    user_id='user_123',\n    event='Product Viewed',\n    properties={'product_id': '456', 'product_name': 'Example Widget'}\n)\n\n# You can also use anonymous_id if user_id is not available\nrudder_analytics.page(\n    anonymous_id='anon_789',\n    name='Homepage',\n    category='Marketing'\n)\n\n# Ensure all queued events are sent before exiting\nrudder_analytics.flush()\n\nprint('Events sent to RudderStack.')\n","lang":"python","description":"Initialize the RudderStack Python SDK with your source write key and data plane URL, then use `identify`, `track`, and `page` methods to send customer events. Remember to call `flush()` to ensure all buffered events are sent before your application exits."},"warnings":[{"fix":"Always pass `user_id` or `anonymous_id` as an argument to event methods: `rudder_analytics.track('user_id_123', 'Event Name')`.","message":"The Python SDK does not persist user state. You must explicitly provide either `user_id` or `anonymous_id` with every event API call (e.g., `track`, `identify`, `page`). Failing to do so will result in events not being processed correctly or being dropped.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Consider using asynchronous processing (e.g., a background thread, a message queue, or a dedicated worker) for RudderStack event calls in performance-sensitive applications.","message":"The SDK blocks the calling thread until all messages are flushed from the queue. Avoid using SDK calls directly within the critical path of a request lifecycle (e.g., in web server request handlers) to prevent performance bottlenecks.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Monitor event sizes and truncate or restructure large event payloads to stay within the 32KB limit. Split large events into multiple smaller events if necessary.","message":"The Python SDK drops any event data larger than 32KB without logging a warning. Ensure your event payloads (including properties and context) do not exceed this size limit.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"1. Verify your `rudder_analytics.write_key` and `rudder_analytics.dataPlaneUrl` are correct. 2. Check the status of your RudderStack server/data plane (if self-hosted) or the RudderStack cloud dashboard. 3. Confirm the destination is enabled and configured correctly in your RudderStack workspace. 4. Enable `rudder_analytics.debug = True` for more verbose logging.","cause":"Several potential causes: RudderStack server is in 'degraded' or 'maintenance' mode, incorrect data plane URL or write key, Control Plane is inaccessible, or the specific destination is not enabled or misconfigured in the RudderStack dashboard.","error":"SDK returns success, but events are not visible in the destination."},{"fix":"1. Check your network connection and proxy settings. 2. Ensure the `DATA_PLANE_URL` is accessible from your application's environment. 3. Verify that any firewalls are configured to allow outbound HTTP/HTTPS connections to your data plane URL. 4. Increase the `timeout` configuration option for the SDK if transient network issues are expected.","cause":"Network connectivity issues preventing the SDK from reaching the RudderStack data plane, potentially due to firewall rules, proxy misconfiguration, or an unavailable data plane server. While this specific error often appears with `rudder-cli`, similar underlying network problems can affect the SDK.","error":"HTTPSConnectionPool(...): Max retries exceeded with url: ... (Caused by ProxyError or ConnectionError)"},{"fix":"1. Check the status of your destination service (e.g., Google Analytics, S3). 2. If self-hosting RudderStack, monitor your server resources and consider scaling up if the incoming event rate consistently exceeds processing capacity. 3. Review RudderStack dashboard metrics for any alerts on pending events or degraded performance.","cause":"This usually indicates a bottleneck in processing, either on the RudderStack backend side or the destination service itself. Possible reasons include a high rate of incoming events overwhelming the system or a temporary outage/degradation of the destination service.","error":"Events are being sent successfully but appear in the destination with significant delay."}]}