RudderStack Python SDK
RudderStack’s Python SDK lets you track events from your Python application. Once enabled, the event requests hit the RudderStack servers. RudderStack then transforms and routes these events to your specified destination platforms.
More details on the Python SDK can be found in our documentation
Getting Started with Python SDK
Install rudder-sdk-python using pip:
pip install rudder-sdk-python
Initializing the RudderStack Client
import rudderstack.analytics as analytics
analytics.write_key = <SOURCE_WRITE_KEY>
analytics.on_error = <FAILURE CALLBACK>
analytics.debug = <True or False>
analytics.dataPlaneUrl = <RUDDERSTACK_DATA_PLANE_URL>
analytics.gzip = <True or False>
Sending Events
Once the RudderStack client is initialized, you can use it to send your customer events. A sample track call is shown below:
rudder_analytics.track('developer_user_id', 'Simple Track Event', {
'key1': 'val1'
})
analytics.track('user_id', 'Simple Track Event', anonymous_id='anonymousId',
properties={
'key1': 'val1'
}, context={
'key1': 'val1'
})
For more information on the supported calls, refer to the documentation.
Editing or dropping events before enqueue
Set before_enqueue to edit or drop events before they leave your process. It
runs once per event, on the calling thread, after the SDK fills in messageId,
timestamp, channel and context. It receives its own copy of the event as a
dict. Return the (possibly edited) dict to send it, or None to drop it.
import rudderstack.analytics as analytics
def before_enqueue(msg):
# Drop: internal test traffic never leaves the process
if (msg.get('userId') or '').startswith('test-'):
return None
# Edit: strip the email before it is transmitted
for container in (msg, msg.get('context')):
if isinstance(container, dict):
traits = container.get('traits')
if isinstance(traits, dict):
traits.pop('email', None)
# Must return the event: an implicit None drops it
return msg
analytics.before_enqueue = before_enqueue
# This hook redacts PII, so never fall back to the unredacted original
analytics.before_enqueue_on_error = 'drop'
Set module-level before_enqueue and before_enqueue_on_error before the first module call,
when the default client is created. Later assignments do not reconfigure that client.
Creating an explicit Client is the safe option when module calls may already have occurred:
from rudderstack.analytics.client import Client
client = Client(
'YOUR_WRITE_KEY', before_enqueue=before_enqueue,
before_enqueue_on_error='drop',
)
client.identify('user-id', traits={'email': 'ada@example.com', 'plan': 'pro'})
- Returning
Nonedrops the event, including a hook that ends without areturn.Clientmethods return(True, None)andon_erroris not called. - With a hook configured, validation waits until the hook returns, so the hook
can fix an invalid call. The returned dict uses the call's normal field and
serialization validation. Events over Python's 4 MB limit raise the usual
RuntimeError, just as without a hook; oversize is not a hook error. - If the hook raises an
Exception, returns something other than a dict orNone, or fails validation (including cyclic data), the SDK logs the error as thrown. The defaultbefore_enqueue_on_error='send'validates and sends the original event;'drop'drops it. Hook errors never callon_error. If the original is also invalid under'send', its validation error surfaces as it would without a hook. channelandcontext.libraryare restored with one warning if changed. A changedmessageIdis kept; a missing or empty one is restored silently. Other fields, includingtype, are yours to change. IDs are not coerced again after the hook, and its result is not copied or cleaned.- The hook must be synchronous and thread-safe if you call the SDK from several threads. It runs once per event, including when delivery retries.
before_enqueuemust be callable orNone;before_enqueue_on_errormust be'send'or'drop'. Invalid options fail at client construction.sentAtis absent from the hook input; the SDK sets it on the batch when sending. Python enrichestimestamp; it does not add Node'soriginalTimestampor_metadata.KeyboardInterruptandSystemExitpropagate.
Proxy configuration
Pass proxies when you create a Client. A Requests-style mapping is preferred:
from rudderstack.analytics.client import Client
client = Client(
'SOURCE_WRITE_KEY',
host='https://YOUR_DATA_PLANE_URL',
proxies={
'http': 'http://proxy.example:8080',
'https': 'http://proxy.example:8080',
},
)
A legacy string such as proxy.example:8080 is also supported. The SDK applies
the string to both HTTP and HTTPS requests. If the string has no scheme, the SDK
adds http://. An existing scheme is preserved.
Configured proxies are now used for event requests. Earlier versions ignored this option. Check that any existing proxy configuration is reachable before upgrading.
About RudderStack
RudderStack is a customer data platform for developers. Our tooling makes it easy to deploy pipelines that collect customer data from every app, website and SaaS platform, then activate it in your warehouse and business tools.
More information on RudderStack can be found here.
Contact Us
For more information on any of the sections covered in this readme, you can contact us or start a conversation on our Slack channel.
Metadata
Release files for rudder-sdk-python 2.2.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| rudder_sdk_python-2.2.0.tar.gz | 28.9 kB | With provenance | Details for rudder_sdk_python-2.2.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| rudder_sdk_python-2.2.0-py2.py3-none-any.whl | Python 2, Python 3 | none | any | Details for rudder_sdk_python-2.2.0-py2.py3-none-any.whl |
Total release size: 65.4 kB
Release files / rudder_sdk_python-2.2.0.tar.gz
| Download URL | rudder_sdk_python-2.2.0.tar.gz |
|---|---|
| Size | 28.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
88ef79ca259c9f3e8450a50240ebac2889f73f570a9abdf22dae0c5c7cda7e25
|
|
BLAKE2b-256 checksum How to use checksums |
6dd8a9d6bd4c0e46aafbe4d6f91370295e6b52ff4bb0fba2d4b6870de3e6ce56
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 4, 2026.
Transparency logRelease files / rudder_sdk_python-2.2.0-py2.py3-none-any.whl
| Download URL | rudder_sdk_python-2.2.0-py2.py3-none-any.whl |
|---|---|
| Size | 36.6 kB |
| Tags | Python 2 Python 3 |
|
SHA-256 checksum How to use checksums |
3f3705f0591ebdef6e0efd841ff796c37b3941c8ac53c7582559830646586c37
|
|
BLAKE2b-256 checksum How to use checksums |
6f1622ee8b34fecefb6e9ef572e824e05715f1e1796aff8c080ce3da8b607ffc
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 4, 2026.
Transparency logSecurity for rudder-sdk-python 2.2.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for rudder_sdk_python-2.2.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 4, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.