--- title: Migrate to dd-trace-py v3 description: Upgrade your Python tracer from v2 to v3. breadcrumbs: Docs > APM > Application Instrumentation > Migrate to dd-trace-py v3 --- # Migrate to dd-trace-py v3 Version 3.0.0 of `dd-trace-py` drops support for Python 3.7 and removes previously deprecated APIs. This guide provides steps to help you upgrade your application. With the release of `v3.0.0`, the `2.x` release line is in maintenance mode. Only critical bug fixes should be backported. For more details, see the [versioning support policy](https://docs.datadoghq.com/tracing/trace_collection/compatibility/python/#releases). ### Step 1: Detect deprecations{% #step-1-detect-deprecations %} To ensure a smooth transition, first upgrade to the latest v2 release (`2.21.0`) and use the following tools to find any deprecated code that will break in v3. #### In tests{% #in-tests %} Run `pytest` with warnings enabled as errors to identify areas in your test suite that need updates: ```sh pytest -W "error::ddtrace.DDTraceDeprecationWarning" tests.py ``` #### In applications{% #in-applications %} Set the`PYTHONWARNINGS` environment variable to surface deprecation warnings when you run your application. ```sh PYTHONWARNINGS=all python app.py ``` ### Step 2: Address breaking changes{% #step-2-address-breaking-changes %} After identifying potential issues, review the following breaking changes. Update your code to be compatible with v3 before proceeding with the upgrade. #### Environment variable changes{% #environment-variable-changes %} The following environment variables have been removed or replaced. Update your configuration with the new variables where applicable. You can use the following command to find all occurrences of these deprecated variables in your codebase: ```sh git grep -P -e "DD_LLMOBS_APP_NAME" \ -e "_DD_LLMOBS_EVALUATOR_SAMPLING_RULES" \ -e "_DD_LLMOBS_EVALUATORS" \ -e "DD_TRACE_PROPAGATION_STYLE=.*b3 single header" \ -e "DD_TRACE_SAMPLE_RATE" \ -e "DD_TRACE_API_VERSION=v0.3" \ -e "DD_ANALYTICS_ENABLED" \ -e "DD_TRACE_ANALYTICS_ENABLED" \ -e "DD_HTTP_CLIENT_TAG_QUERY_STRING" \ -e "DD_TRACE_SPAN_AGGREGATOR_RLOCK" \ -e "DD_TRACE_METHODS=.*\[\]" ``` | Deprecation | Action Required | | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `DD_ANALYTICS_ENABLED` | Removed. This is a no-op. See [Ingestion Controls](https://docs.datadoghq.com/tracing/trace_pipeline/ingestion_mechanisms/?tab=python) for alternatives. | | `DD_HTTP_CLIENT_TAG_QUERY_STRING` | Use `DD_TRACE_HTTP_CLIENT_TAG_QUERY_STRING` instead. | | `DD_LLMOBS_APP_NAME` | Use `DD_LLMOBS_ML_APP` instead. | | `_DD_LLMOBS_EVALUATOR_SAMPLING_RULES` | Use `DD_LLMOBS_EVALUATOR_SAMPLING_RULES` instead (without the leading underscore). | | `_DD_LLMOBS_EVALUATORS` | Use `DD_LLMOBS_EVALUATORS` instead (without the leading underscore). | | `DD_PYTEST_USE_NEW_PLUGIN_BETA` | Removed. The new pytest plugin is the default and is no longer in beta. | | `DD_TRACE_ANALYTICS_ENABLED` | Removed. This is a no-op. See [Ingestion Controls](https://docs.datadoghq.com/tracing/trace_pipeline/ingestion_mechanisms/?tab=python) for alternatives. | | `DD_TRACE_METHODS` (using `[]` notation) | You must use the `:` notation. For example: `mod.submod:method2;mod.submod:Class.method1`. See the [DD_TRACE_METHODS](https://ddtrace.readthedocs.io/en/stable/configuration.html?highlight=dd_trace_methods#DD_TRACE_METHODS) for details. | | `DD_TRACE_PROPAGATION_STYLE="b3 single header"` | Use `DD_TRACE_PROPAGATION_STYLE=b3` for identical behavior. | | `DD_TRACE_SAMPLE_RATE` | Use `DD_TRACE_SAMPLING_RULES` instead. See [User-Defined Rules](https://docs.datadoghq.com/tracing/trace_pipeline/ingestion_mechanisms/?tab=python#in-tracing-libraries-user-defined-rules) for details. | | `DD_TRACE_SPAN_AGGREGATOR_RLOCK` | Removed. This feature has been removed and the variable is a no-op. | {% alert level="info" %} These changes only apply to `dd-trace-py` configuration and not the Datadog Agent. {% /alert %} #### API and interface changes{% #api-and-interface-changes %} The following methods, attributes, and behaviors have been removed or changed. ##### General{% #general %} - **Python 3.7 Support**: Support for Python 3.7 is removed. ##### Tracing{% #tracing %} - **Multiple Tracer Instances**: Support for multiple `Tracer` instances is removed. You must use the global `ddtrace.tracer` instance. - `Tracer.configure()`: Deprecated parameters have been removed. Use environment variables to configure Agent connection details (`hostname`, `port`), sampling, and other settings. - `Span.sampled`: This attribute is removed. Use `span.context.sampling_priority > 0` to check if a span is sampled. - `ddtrace.opentracer`: The `_dd_tracer` attribute is removed. Use the global `ddtrace.tracer` instead. - `LLMObs.annotate()`: The `parameters` argument is removed. Use `metadata` instead. - `choose_matcher()`: Callables and regex patterns are no longer allowed as arguments to `ddtrace.tracer.sampler.rules[].choose_matcher`. You must pass a string. ##### LLM Observability{% #llm-observability %} - **OpenAI and Langchain**: Support for OpenAI v0.x and Langchain v0.0.x is dropped. ##### CI Visibility{% #ci-visibility %} - The new pytest plugin is the default. - Module, suite, and test names are parsed from `item.nodeid`. - Test names for class-based tests include the class name (for example, `TestClass::test_method`). - Test skipping is performed at the suite level. ### Step 3: Upgrade the library{% #step-3-upgrade-the-library %} After you have updated your code to address the breaking changes, you can upgrade to the latest v3 release. ```sh pip install --upgrade ddtrace ``` #### Python 3.13 compatibility{% #python-313-compatibility %} Full support for Python 3.13 is in active development. While the core tracing library is compatible, some integrations may not be fully tested or supported in the latest version. For the most current compatibility details for a specific integration, see the library's [latest release notes](https://github.com/DataDog/dd-trace-py/releases).