Unified Analyzer Configuration by SharonHart · Pull Request #1970 · microsoft/presidio

SharonHart · 2026-04-13T09:34:53Z

Consolidate analyzer configuration into a single unified file
Migrates the presidio-analyzer from three separate config files (default_analyzer.yaml, default.yaml, default_recognizers.yaml) to a single unified analyzer.yaml. Old files are preserved with deprecation banners.

Copilot

Pull request overview

This PR consolidates Presidio Analyzer configuration into a single unified conf/analyzer.yaml, while keeping the legacy per-section YAML files for backward compatibility with deprecation messaging across code, Docker, and docs.

Changes:

Added a unified analyzer configuration schema (AnalyzerConfiguration) and a new default conf/analyzer.yaml.
Updated AnalyzerEngineProvider defaults/deprecation warnings to prefer the unified config file.
Updated Dockerfiles and documentation to reference the unified configuration approach.

Reviewed changes

Copilot reviewed 27 out of 27 changed files in this pull request and generated 8 comments.

Show a summary per file

File	Description
presidio-analyzer/tests/test_analyzer_engine_provider.py	Updates default config filename expectation to `analyzer.yaml`.
presidio-analyzer/presidio_analyzer/recognizer_registry/recognizers_loader_utils.py	Adds deprecation warning when loading standalone recognizer-registry config files.
presidio-analyzer/presidio_analyzer/nlp_engine/nlp_engine_provider.py	Adds deprecation warning when loading standalone NLP config files.
presidio-analyzer/presidio_analyzer/configuration/analyzer_configuration.py	Introduces Pydantic-based unified configuration models and YAML loader.
presidio-analyzer/presidio_analyzer/configuration/init.py	Exposes unified configuration models as a package API.
presidio-analyzer/presidio_analyzer/conf/default.yaml	Adds deprecation banner pointing users to `conf/analyzer.yaml`.
presidio-analyzer/presidio_analyzer/conf/default_recognizers.yaml	Adds deprecation banner pointing users to `conf/analyzer.yaml`.
presidio-analyzer/presidio_analyzer/conf/default_analyzer.yaml	Adds deprecation banner pointing users to `conf/analyzer.yaml`.
presidio-analyzer/presidio_analyzer/conf/default_analyzer_full.yaml	Adds deprecation banner pointing users to `conf/analyzer.yaml`.
presidio-analyzer/presidio_analyzer/conf/analyzer.yaml	Adds the new unified default analyzer configuration file.
presidio-analyzer/presidio_analyzer/analyzer_engine_provider.py	Makes `analyzer.yaml` the default analyzer config and adds deprecation warnings for old patterns/params.
presidio-analyzer/install_nlp_models.py	Switches model installation to prefer NLP config embedded in analyzer config.
presidio-analyzer/Dockerfile.windows	Switches defaults toward unified config and changes model-install invocation.
presidio-analyzer/Dockerfile.transformers	Switches defaults toward unified config and changes model-install invocation.
presidio-analyzer/Dockerfile.stanza	Switches defaults toward unified config and changes model-install invocation.
presidio-analyzer/Dockerfile.dev	Updates build args to prefer unified config defaults.
presidio-analyzer/Dockerfile	Switches defaults toward unified config and changes model-install invocation.
presidio-analyzer/app.py	Adds deprecation warnings for legacy env vars and minor formatting fixes.
docs/tutorial/08_no_code.md	Updates tutorial to reference unified config and adds deprecation note for separate files.
docs/samples/python/no_code_config.ipynb	Updates sample notebook links/text to use the unified config approach.
docs/samples/python/langextract/index.md	Updates LangExtract sample to enable/configure recognizer via unified config and `AnalyzerEngineProvider`.
docs/analyzer/languages.md	Updates guidance to configure NLP models via `nlp_configuration` inside unified config.
docs/analyzer/customizing_nlp_models.md	Updates config references from `default.yaml` to unified config (but includes an inaccurate statement).
docs/analyzer/analyzer_engine_provider.md	Updates docs to recommend unified configuration and marks multi-file usage as deprecated.
docs/analyzer/adding_recognizers.md	Updates docs to add recognizers via `conf/analyzer.yaml`.
CONTRIBUTING.md	Updates contributor guidance to add recognizers in `conf/analyzer.yaml`.
.github/copilot-instructions.md	Updates repo instructions to reference `conf/analyzer.yaml` as the configuration target.

Copilot · 2026-04-13T09:42:00Z

+ARG ANALYZER_CONF_FILE=presidio_analyzer/conf/analyzer.yaml
+ARG NLP_CONF_FILE=
+ARG RECOGNIZER_REGISTRY_CONF_FILE=


NLP_CONF_FILE and RECOGNIZER_REGISTRY_CONF_FILE are now defaulted to an empty string, but the Dockerfile still unconditionally uses these build args in COPY instructions later. With empty defaults, the Docker build will fail when it reaches those COPY ${NLP_CONF_FILE} ... / COPY ${RECOGNIZER_REGISTRY_CONF_FILE} ... steps. Either remove those COPY steps entirely, or keep non-empty defaults (and rely on the unified analyzer config taking priority at runtime).

Copilot · 2026-04-13T09:42:00Z

+ARG ANALYZER_CONF_FILE=presidio_analyzer/conf/analyzer.yaml
+ARG NLP_CONF_FILE=
+ARG RECOGNIZER_REGISTRY_CONF_FILE=


NLP_CONF_FILE / RECOGNIZER_REGISTRY_CONF_FILE are defaulted to empty, but this Dockerfile still uses them in later COPY instructions. With empty defaults, docker build will fail on those COPY steps. Either drop the per-section COPYs entirely or keep non-empty defaults (the unified analyzer_conf_file already takes priority in AnalyzerEngineProvider).

Copilot · 2026-04-13T09:42:00Z

+ARG ANALYZER_CONF_FILE=presidio_analyzer/conf/analyzer.yaml
+ARG NLP_CONF_FILE=
+ARG RECOGNIZER_REGISTRY_CONF_FILE=


NLP_CONF_FILE / RECOGNIZER_REGISTRY_CONF_FILE are set to empty defaults, but later COPY steps still reference them. This will break Docker builds unless the args are overridden. Consider removing the per-section COPYs (preferred if deprecating them) or keeping non-empty defaults for backward compatibility.

Copilot · 2026-04-13T09:42:01Z

+ARG ANALYZER_CONF_FILE=presidio_analyzer/conf/analyzer.yaml
+ARG NLP_CONF_FILE=
+ARG RECOGNIZER_REGISTRY_CONF_FILE=


NLP_CONF_FILE / RECOGNIZER_REGISTRY_CONF_FILE are defaulted to empty strings, but this Dockerfile still unconditionally COPYs them later. With empty defaults, the Docker build will fail on those COPY steps unless the args are always overridden. Either remove those COPY instructions or keep non-empty defaults.

Copilot · 2026-04-13T09:42:01Z

    install_models(
-        nlp_conf_file=args.nlp_conf_file or "presidio_analyzer/conf/default.yaml",
-        analyzer_conf_file=args.analyzer_conf_file,
+        nlp_conf_file=args.nlp_conf_file,
+        analyzer_conf_file=args.analyzer_conf_file
+        or "presidio_analyzer/conf/analyzer.yaml",
    )


The CLI entrypoint always passes analyzer_conf_file=args.analyzer_conf_file or "presidio_analyzer/conf/analyzer.yaml". Since the default analyzer.yaml contains nlp_configuration, this makes --nlp_conf_file (and the deprecated --conf_file) effectively ignored in the common case, and can also lead to errors if the analyzer conf file lacks nlp_configuration while nlp_conf_file is still None. Consider only defaulting analyzer_conf_file when neither an analyzer config nor an NLP config was provided, and otherwise default nlp_conf_file to the legacy conf/default.yaml for backward compatibility.

@copilot apply changes based on this feedback

Copilot · 2026-04-13T09:42:02Z

+    def from_yaml(cls, file_path: Union[str, Path]) -> "AnalyzerConfiguration":
+        """Load and validate configuration from a YAML file.
+
+        :param file_path: Path to the YAML configuration file.
+        :return: Validated AnalyzerConfiguration instance.
+        :raises FileNotFoundError: If the file does not exist.
+        :raises ValueError: If the YAML content is invalid.
+        """
+        path = Path(file_path)
+        if not path.exists():
+            raise FileNotFoundError(f"Configuration file not found: {path}")
+        if not path.is_file():
+            raise ValueError(f"Path is not a file: {path}")
+
+        with open(path) as f:
+            raw = yaml.safe_load(f)
+


AnalyzerConfiguration.from_yaml() documents :raises ValueError: If the YAML content is invalid, but yaml.safe_load() can raise yaml.YAMLError, and return cls(**raw) can raise pydantic.ValidationError. Either catch/wrap these into ValueError (to match the API contract) or update the docstring/type hints to reflect the actual exceptions.

@copilot apply changes based on this feedback

SharonHart · 2026-04-13T09:54:46Z

@copilot address the comments on COPY command for deprecated conf file, remove the COPY command altogether and assume the files are copied as part of being in the root dir

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

…kerfiles Agent-Logs-Url: https://github.com/microsoft/presidio/sessions/88e42ff4-6920-4698-9769-1c702ccf5556 Co-authored-by: SharonHart <15013757+SharonHart@users.noreply.github.com>

Copilot · 2026-04-13T09:59:12Z

@copilot address the comments on COPY command for deprecated conf file, remove the COPY command altogether and assume the files are copied as part of being in the root dir

Done in commit 01edd76. Removed the COPY ${NLP_CONF_FILE} and COPY ${RECOGNIZER_REGISTRY_CONF_FILE} instructions from all 4 Dockerfiles (Dockerfile, Dockerfile.transformers, Dockerfile.stanza, Dockerfile.windows). Also removed the duplicate COPY ${ANALYZER_CONF_FILE} in Dockerfile.windows. These deprecated conf files are now picked up via the later COPY . /app/ (or COPY . .) step.

SharonHart · 2026-04-19T15:21:02Z

@omri374 Notice that the base branch is v3

Copilot

Pull request overview

Copilot reviewed 27 out of 27 changed files in this pull request and generated 7 comments.

+        """Load and validate configuration from a YAML file.
+
+        :param file_path: Path to the YAML configuration file.
+        :return: Validated AnalyzerConfiguration instance.
+        :raises FileNotFoundError: If the file does not exist.
+        :raises ValueError: If the YAML content is invalid.
+        """
+        path = Path(file_path)
+        if not path.exists():
+            raise FileNotFoundError(f"Configuration file not found: {path}")
+        if not path.is_file():
+            raise ValueError(f"Path is not a file: {path}")
+
+        with open(path) as f:
+            raw = yaml.safe_load(f)
+
+        if raw is None:
+            raise ValueError(f"Configuration file is empty: {path}")
+        if not isinstance(raw, dict):
+            raise ValueError(
+                f"Configuration file must contain a YAML mapping, "
+                f"got {type(raw).__name__}: {path}"
+            )
+
+        # Detect and warn about deprecated separate-file format keys
+        deprecated_top_keys = {"nlp_engine_name", "models"}
+        found_deprecated = deprecated_top_keys & set(raw.keys())
+        if found_deprecated:
+            warnings.warn(
+                f"Configuration file '{path}' appears to use the deprecated "
+                f"standalone NLP configuration format "
+                f"(found top-level keys: {sorted(found_deprecated)}). "
+                f"Please migrate to the unified analyzer configuration format. "
+                f"See: https://microsoft.github.io/presidio/analyzer/"
+                f"analyzer_engine_provider/",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+
+        return cls(**raw)


    install_models(
-        nlp_conf_file=args.nlp_conf_file or "presidio_analyzer/conf/default.yaml",
-        analyzer_conf_file=args.analyzer_conf_file,
+        nlp_conf_file=args.nlp_conf_file,
+        analyzer_conf_file=args.analyzer_conf_file
+        or "presidio_analyzer/conf/analyzer.yaml",
    )


 ENV RECOGNIZER_REGISTRY_CONF_FILE=${RECOGNIZER_REGISTRY_CONF_FILE}
 ENV NLP_CONF_FILE=${NLP_CONF_FILE}

 ENV PORT=3000
 ENV WORKERS=1

 COPY ${ANALYZER_CONF_FILE} /app/${ANALYZER_CONF_FILE}


 ENV ANALYZER_CONF_FILE=${ANALYZER_CONF_FILE}
 ENV RECOGNIZER_REGISTRY_CONF_FILE=${RECOGNIZER_REGISTRY_CONF_FILE}
 ENV NLP_CONF_FILE=${NLP_CONF_FILE}

 COPY ${ANALYZER_CONF_FILE} /app/${ANALYZER_CONF_FILE}


 ENV ANALYZER_CONF_FILE=${ANALYZER_CONF_FILE}
 ENV RECOGNIZER_REGISTRY_CONF_FILE=${RECOGNIZER_REGISTRY_CONF_FILE}
 ENV NLP_CONF_FILE=${NLP_CONF_FILE}

 ENV PORT=3000
 ENV WORKERS=1

 COPY ${ANALYZER_CONF_FILE} /app/${ANALYZER_CONF_FILE}


 ENV ANALYZER_CONF_FILE=${ANALYZER_CONF_FILE}
 ENV RECOGNIZER_REGISTRY_CONF_FILE=${RECOGNIZER_REGISTRY_CONF_FILE}
 ENV NLP_CONF_FILE=${NLP_CONF_FILE}

 RUN powershell -Command \
    "Write-Host 'Downloading VC++ Redistributable...'; \
    Invoke-WebRequest -Uri 'https://aka.ms/vs/16/release/vc_redist.x64.exe' -OutFile 'vc_redist.x64.exe' -UseBasicParsing; \
    Write-Host 'Installing VC++ Redistributable...'; \
    Start-Process -FilePath 'vc_redist.x64.exe' -ArgumentList '/quiet', '/install' -Wait; \
    Write-Host 'VC++ Redistributable installed successfully'; \
    Remove-Item 'vc_redist.x64.exe'"

 COPY ${ANALYZER_CONF_FILE} /app/${ANALYZER_CONF_FILE}


  - `low_score_entity_names`: A list of entity types to apply the low confidence score multiplier to.

-    The [default conf file](https://github.com/microsoft/presidio/blob/main/presidio-analyzer/presidio_analyzer/conf/default.yaml) is read during the default initialization of the `AnalyzerEngine`. Alternatively, the path to a custom configuration file can be passed to the `NlpEngineProvider`:
+    To load NLP settings from a configuration file, use `NlpEngineProvider` with a config file such as the [analyzer configuration file](https://github.com/microsoft/presidio/blob/main/presidio-analyzer/presidio_analyzer/conf/analyzer.yaml). Alternatively, NLP configuration can be passed directly:


omri374

Thanks! there's one issue with the recognizer registry currently reading default_recognizers.yaml but aside from this it looks great.
We should think about how this would look like once it is deprecated completely and not just a warning- does it break? do we have a fallback mechanism? not for this pr of course.

omri374 · 2026-05-04T07:19:01Z

+        ):
+            warnings.warn(
+                f"Configuration file '{conf_file}' uses the deprecated "
+                f"partial-configuration format (only supported_languages and "


it's not cleat what partial-configuration format is. Is the warning about using deprecated files or is it aiming at something more specific here?

Indeed a warning about using deprecated files

omri374 · 2026-05-04T07:56:32Z

        # Load defaults if needed (no config provided,
        # or registry_configuration is incomplete)
        if use_defaults:
            with open(RecognizerConfigurationLoader._get_full_conf_path()) as file:


this still uses the "default_recognizers.yaml" file. Do we want to update this too?

I think that considering it relates to recognizers_loader, we can keep it until the full deprecation, in which, to your question, I think we should eventually fail when passed with non-unified config.

Unified Analyzer Configuration

4fbc51f

SharonHart requested a review from Copilot April 13, 2026 09:35

Copilot started reviewing on behalf of SharonHart April 13, 2026 09:36 View session

Copilot AI reviewed Apr 13, 2026

View reviewed changes

SharonHart marked this pull request as ready for review April 13, 2026 09:47

Copilot started work on behalf of SharonHart April 13, 2026 09:54 View session

SharonHart and others added 3 commits April 13, 2026 12:56

Update presidio-analyzer/Dockerfile.windows

5f39030

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Update docs/analyzer/customizing_nlp_models.md

66aba73

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

fix: remove broken COPY commands for deprecated conf files in all Doc…

01edd76

…kerfiles Agent-Logs-Url: https://github.com/microsoft/presidio/sessions/88e42ff4-6920-4698-9769-1c702ccf5556 Co-authored-by: SharonHart <15013757+SharonHart@users.noreply.github.com>

Copilot finished work on behalf of SharonHart April 13, 2026 10:00

SharonHart requested review from RonShakutai and omri374 April 13, 2026 11:57

omri374 requested a review from Copilot May 4, 2026 07:15

Copilot started reviewing on behalf of omri374 May 4, 2026 07:15 View session

Copilot AI reviewed May 4, 2026

View reviewed changes

omri374 reviewed May 4, 2026

View reviewed changes

Conversation

SharonHart commented Apr 13, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Apr 13, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 13, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 13, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 13, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Copilot AI Apr 13, 2026

Choose a reason for hiding this comment

Uh oh!

SharonHart Apr 13, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 13, 2026

Choose a reason for hiding this comment

Uh oh!

SharonHart Apr 13, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

SharonHart commented Apr 13, 2026

Uh oh!

Copilot AI commented Apr 13, 2026

Uh oh!

SharonHart commented Apr 19, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

omri374 left a comment

Choose a reason for hiding this comment

Uh oh!

omri374 May 4, 2026

Choose a reason for hiding this comment

Uh oh!

SharonHart May 4, 2026

Choose a reason for hiding this comment

Uh oh!

omri374 May 4, 2026

Choose a reason for hiding this comment

Uh oh!

SharonHart May 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

SharonHart May 4, 2026 •

edited

Loading