Install & Compatibility
Where this runs
tested against v2.9.2 · 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.920 runs
installs and imports cleanly · install 0.0s · import 0.000s · 87.4MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 5.0s · import 0.000s · 88MB
88MB installed
● package 88MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Customer
✓ from djstripe.models import Customer
✗ from djstripe.models import Customer
To get started with dj-stripe, add it to your `INSTALLED_APPS`, configure your Stripe API keys (test and live) in `settings.py`, and include dj-stripe's URLs in your project's `urls.py`. Remember to run `python manage.py migrate` after installation to create the necessary database tables. For webhooks, configure them via the Django admin (since 2.7.0).
import os
# settings.py
INSTALLED_APPS = [
# ... other apps
'djstripe',
# ...
]
STRIPE_LIVE_MODE = False # Set to True for production
STRIPE_TEST_SECRET_KEY = os.environ.get('STRIPE_TEST_SECRET_KEY', 'sk_test_YOUR_TEST_SECRET_KEY')
STRIPE_LIVE_SECRET_KEY = os.environ.get('STRIPE_LIVE_SECRET_KEY', 'sk_live_YOUR_LIVE_SECRET_KEY')
STRIPE_TEST_PUBLIC_KEY = os.environ.get('STRIPE_TEST_PUBLIC_KEY', 'pk_test_YOUR_TEST_PUBLIC_KEY')
STRIPE_LIVE_PUBLIC_KEY = os.environ.get('STRIPE_LIVE_PUBLIC_KEY', 'pk_live_YOUR_LIVE_PUBLIC_KEY')
# urls.py
from django.urls import path, include
urlpatterns = [
# ... other paths
path('djstripe/', include('djstripe.urls', namespace="djstripe")),
# ...
]
# Run migrations
# python manage.py migrate
Debug
Known issues
breakingUpgrading to dj-stripe 2.10.x requires first upgrading to 2.9.x due to a migration reset. Additionally, many database fields have been removed from models and replaced by `stripe_data` property accessors, requiring code changes.fixEnsure you are on a 2.9.x release before upgrading to 2.10.x. Review your code for direct model field access and update to use `model_instance.stripe_data['field_name']` where applicable.
affects: 2.10.0 and newer
breakingDeprecated settings (`DJSTRIPE_WEBHOOK_TOLERANCE`, `DJSTRIPE_WEBHOOK_SECRET`), the `Order` model, `Customer.add_card` method, and direct support for `Source` and `SourceTransaction` models have been removed. The `Source` models are now under `djstripe.models.payment_methods` and are slated for full removal.fixRemove deprecated settings from `settings.py`. Update code relying on removed models or methods. Reconfigure webhooks via the Django admin interface instead of `DJSTRIPE_WEBHOOK_SECRET`.
affects: 2.9.0 and newer
breakingDirect upgrade paths for older dj-stripe versions are restricted. For instance, upgrading to 2.8.0 is not possible from versions older than 2.5.0, and upgrading to 2.7.0 is not possible from versions older than 2.4.0.fixConsult release notes for your current and target versions. Perform staged upgrades (e.g., old -> 2.4.0 -> 2.7.0 -> 2.9.0 -> 2.10.x) if jumping multiple major versions.
affects: 2.7.0, 2.8.0, and newer (from older versions)
gotchadj-stripe has a strict `requires_python` range. Starting with 2.8.0, Python 3.7 is no longer supported. The latest versions (2.10.x) require Python >=3.11 and support newer Django versions like 4.1 and 4.2.fixVerify your Python and Django versions against the `dj-stripe` version you plan to use. Upgrade your Python environment and Django project if necessary.
affects: 2.8.0 and newer
gotchaWebhook endpoint configuration has changed significantly. Starting from 2.7.0, webhook endpoints are primarily configured via the Django administration interface, replacing older methods like `DJSTRIPE_WEBHOOK_SECRET` (which was removed in 2.9.0).fixMigrate webhook secret configuration from `settings.py` to the Django admin panel under the dj-stripe app. Ensure your Stripe dashboard is configured to send events to the `/djstripe/webhook/` endpoint.
affects: 2.7.0 and newer
Upgrade
Version history
2.10.3latest on PyPI · released Oct 15, 2025
Audit
Dependencies
DjangorequiredCore framework dependency. Check `requires_python` and release notes for compatible Django versions.
striperequiredStripe Python client library, used for direct API calls.