Install sentry-sdk in Python

Sentry helps you catch errors before your users report them. The sentry-sdk package connects your Python application to the Sentry platform.

This guide walks you through installation, configuration, and verification. It is written for beginners who want a clean and reliable setup.

Prerequisites

You need two things before you begin. A Sentry account and a Sentry project.

Create a project in your Sentry dashboard. Copy the DSN (Data Source Name). You will need it during configuration.

You also need Python 3.6 or newer. Check your version with the command below.

python --version
python3 --version

Set Up a Virtual Environment

Always isolate your project dependencies. A virtual environment keeps packages separate and reproducible.

This is a best practice for every Python project, not just Sentry. It prevents version conflicts between applications.

# Create a virtual environment
python -m venv myenv

# Activate on Linux or macOS
source myenv/bin/activate

# Activate on Windows
myenv\Scripts\activate

Your terminal prompt should change after activation. You will see the environment name in parentheses.

Install sentry-sdk with pip

The core SDK is lightweight and has very few dependencies. Install it with the pip install command.

pip install --upgrade sentry-sdk

The --upgrade flag ensures you get the latest stable release. This is important because the SDK improves quickly.

Install Framework-Specific Extras

Sentry provides optional integrations for popular frameworks. Install only what matches your stack.

# Django
pip install "sentry-sdk[django]"

# Flask
pip install "sentry-sdk[flask]"

# FastAPI
pip install "sentry-sdk[fastapi]"

# Celery
pip install "sentry-sdk[celery]"

If you use Django, you may also benefit from focused utilities. For example, many teams learn how to install django-filter in Python to clean up query filtering alongside error monitoring.

For performance testing, you can also write Locust tasks in Python and monitor failures in Sentry. If you are new to that tool, start with a guide on how to install Locust in Python before adding load tests.

Configure sentry_sdk.init()

Initialization must happen as early as possible in your application. Place it at the top of your entry point, before other imports that may raise errors.

Call sentry_sdk.init() with your DSN and a sample rate for performance tracing.

import sentry_sdk

sentry_sdk.init(
    dsn="https://@o.ingest.sentry.io/",
    # Capture 100% of transactions for tracing during setup
    traces_sample_rate=1.0,
)

Replace the placeholder DSN with the real value from your Sentry project settings.

The traces_sample_rate controls performance data. A value of 1.0 captures 100% of transactions, which is useful for testing but expensive in production.

Lower this value before deploying to production. A rate between 0.1 and 0.2 is common for high-traffic applications.

Verify the Installation

Verification proves that the SDK can reach Sentry. It also confirms that your DSN is valid.

Send a test message with capture_message(). Then check the Issues tab in your Sentry dashboard.

import sentry_sdk

sentry_sdk.init(
    dsn="https://@o.ingest.sentry.io/",
    traces_sample_rate=1.0,
)

# Send a test message to Sentry
sentry_sdk.capture_message("Sentry SDK verification test", level="info")
print("Test message sent. Check your Sentry dashboard.")

Run the script and wait about 30 seconds. The message should appear in your project.

You can also trigger a real exception with capture_exception() or by raising an error inside a try/except block.

import sentry_sdk

sentry_sdk.init(dsn="https://@o.ingest.sentry.io/")

try:
    raise ValueError("This is a controlled test error")
except Exception as e:
    sentry_sdk.capture_exception(e)
    print("Exception captured and sent to Sentry.")

Exception captured and sent to Sentry.

If nothing appears, call flush() before your program exits. The SDK sends events asynchronously, so a fast exit can drop data.

import sentry_sdk

sentry_sdk.init(dsn="https://@o.ingest.sentry.io/")
sentry_sdk.capture_message("Flush test")
sentry_sdk.flush(timeout=2)
print("Flush completed.")

Troubleshoot Common Installation Issues

Most problems fall into three categories. Package conflicts, invalid DSNs, and framework import order.

If pip fails, upgrade your packaging tools first. Old versions of pip can reject modern package metadata.

python -m pip install --upgrade pip setuptools

If the SDK imports but nothing reaches Sentry, check the DSN. It must match the project exactly, including the organization ID and project ID.

For Django or Flask, confirm that sentry_sdk.init() runs before the framework loads. Incorrect order is a common cause of missing events.

If you see a ModuleNotFoundError after installation, verify that your virtual environment is active. Run which python or where python to confirm the path.

Best Practices for a Clean Setup

Pin the SDK version in your requirements.txt. This keeps deployments reproducible across environments.

pip freeze | grep sentry-sdk >> requirements.txt

Store the DSN in an environment variable instead of hardcoding it. Never commit secrets to version control.

import os
import sentry_sdk

sentry_sdk.init(
    dsn=os.environ["SENTRY_DSN"],
    traces_sample_rate=0.2,
)

Use a lower traces_sample_rate in production. Test environments can use 1.0, but production should sample selectively.

Enable send_default_pii only if your privacy policy allows it. This setting attaches user information to events.

Conclusion

Installing sentry-sdk in Python is a short process. Create a virtual environment, install the package, and initialize it with your DSN.

Always verify with a test message or exception. Then check your Sentry dashboard before moving on.

A clean setup gives you real-time visibility into errors and performance issues. With these steps, your Python application is ready for reliable monitoring.