Skip to content

Add guide for customizing Presidio Docker images #1792

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
SAIRAMSSSS wants to merge 3 commits into
base: main
Choose a base branch
from
Open

Add guide for customizing Presidio Docker images #1792

Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
c4a3651
Add guide for customizing Presidio Docker images
SAIRAMSSSS Nov 21, 2025
3f28082
Merge branch 'main' into main
omri374 Dec 8, 2025
b28e7f9
Merge branch 'main' into main
SharonHart Dec 17, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
234 changes: 234 additions & 0 deletions docs/docker_customization.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,234 @@
# Customizing Presidio Docker Images

## Overview

This guide provides detailed instructions on how to build and customize Presidio Docker images to support additional languages and custom configurations. The official Presidio Docker images support English by default, but you can create custom images to work with other languages.

## Prerequisites

- Docker installed ([Download Docker](https://docs.docker.com/get-docker/))
- Basic knowledge of Docker and YAML
- Familiarity with spaCy language models

## Understanding Presidio's Docker Architecture

Presidio consists of three main Docker images:
- `presidio-analyzer`: Detects PII entities in text
- `presidio-anonymizer`: Anonymizes detected PII
- `presidio-image-redactor`: Redacts PII from images

For multi-language support, you'll primarily need to customize the `presidio-analyzer` image.

## Step 1: Clone the Presidio Repository

First, clone the Presidio repository:

```bash
git clone https://github.com/microsoft/presidio.git
cd presidio
```

## Step 2: Locate Configuration Files

The key files for customization are:

- `presidio-analyzer/Dockerfile`: Defines the analyzer Docker image
- `presidio-analyzer/presidio_analyzer/conf/default_recognizers.yaml`: Configures recognizers

Comment on lines +32 to +37
Copy link

Copilot AI Jan 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The documentation doesn't mention that users need to update the NLP configuration file (default.yaml) to specify which language models to install. Based on the actual Presidio Dockerfile (line 36), models are installed by running install_nlp_models.py --conf_file ${NLP_CONF_FILE}, which reads from the configuration file.

For multi-language support, users should either:

  1. Modify presidio_analyzer/conf/default.yaml to add additional models, OR
  2. Create a custom NLP configuration file (e.g., spacy_multilingual.yaml which already exists in the repo) and pass it as a build arg

The current documentation focuses on modifying the Dockerfile directly, which is not the recommended approach according to the actual Presidio architecture.

Copilot uses AI. Check for mistakes.
## Step 3: Modify the Dockerfile for Additional Languages

Navigate to `presidio-analyzer/Dockerfile` and add your desired spaCy language models.

### Example: Adding Spanish Support
Copy link
Collaborator

@omri374 omri374 Dec 8, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Presidio supports the installation of spacy, stanza and transformers models using the NLP config, so there is no need to explicitly add those to the Dockerfile. Have you given this a try?


In the Dockerfile, locate the section where spaCy models are downloaded and add:

```dockerfile
RUN python -m spacy download es_core_news_md
```

### Example: Adding Multiple Languages

```dockerfile
# Install language models
RUN python -m spacy download en_core_web_lg
RUN python -m spacy download es_core_news_md # Spanish
RUN python -m spacy download fr_core_news_md # French
RUN python -m spacy download de_core_news_md # German
```
Comment on lines +40 to +58
Copy link

Copilot AI Jan 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The documentation incorrectly describes how to add language models to the Dockerfile. The actual Presidio Dockerfile uses a configuration-based approach where models are installed automatically via the install_nlp_models.py script that reads from configuration YAML files (like default.yaml), not by directly adding RUN python -m spacy download commands in the Dockerfile.

The correct approach is to modify the NLP configuration file (e.g., presidio_analyzer/conf/default.yaml) to specify which models should be installed. The Dockerfile already contains the logic to read this configuration and install the models automatically during the build process at line 36: RUN poetry run python install_nlp_models.py --conf_file ${NLP_CONF_FILE}

This section should be rewritten to reflect the actual architecture and direct users to modify the YAML configuration files instead.

Copilot uses AI. Check for mistakes.

## Step 4: Configure Language Support

### Update Configuration File

Modify the recognizers configuration to support your languages. Edit `presidio-analyzer/presidio_analyzer/conf/default_recognizers.yaml`:

```yaml
# Add supported languages
supported_languages:
- en
- es
- fr
- de
```
Comment on lines +62 to +73
Copy link

Copilot AI Jan 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This YAML configuration section is incorrect. The default_recognizers.yaml file already contains a supported_languages list at the top level (line 1-2 of the actual file), and it uses the format:

supported_languages: 
  - en

The documentation should clarify that users need to:

  1. Modify the NLP configuration file (e.g., presidio_analyzer/conf/default.yaml) to add language models
  2. Update the top-level supported_languages list in default_recognizers.yaml to include new language codes
  3. Optionally add or update individual recognizers with language-specific context words

The current documentation incorrectly suggests adding a supported_languages block under the recognizers configuration without explaining the proper structure.

Copilot uses AI. Check for mistakes.

## Step 5: Build the Custom Docker Image

Build your customized Docker image:

```bash
cd presidio-analyzer
docker build . -t presidio-analyzer-custom:latest
```
Comment on lines +75 to +82
Copy link

Copilot AI Jan 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The documentation misses the proper way to build custom Docker images using the existing configuration files. The actual Dockerfile supports build arguments (ARGs) for specifying custom configuration files:

  • NLP_CONF_FILE=presidio_analyzer/conf/default.yaml (for NLP models)
  • RECOGNIZER_REGISTRY_CONF_FILE=presidio_analyzer/conf/default_recognizers.yaml (for recognizers)

Users can leverage existing configuration files like spacy_multilingual.yaml or create custom ones and pass them as build arguments. For example:

docker build --build-arg NLP_CONF_FILE=presidio_analyzer/conf/spacy_multilingual.yaml -t presidio-analyzer-custom .

This approach is cleaner and more maintainable than modifying the Dockerfile directly, and should be documented as the recommended method.

Copilot uses AI. Check for mistakes.

## Step 6: Run Your Custom Image

Run the custom image:

```bash
docker run -d -p 5002:3000 presidio-analyzer-custom:latest
```
Comment on lines +84 to +90
Copy link

Copilot AI Jan 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The Docker run command uses port 5002 for the external mapping but the Dockerfile default PORT environment variable is 3000 (as seen in the actual Dockerfile line 13). This creates confusion about which internal port the service is actually running on.

The documentation should be consistent with the actual Presidio Dockerfile which uses PORT=3000 by default. The command should either be:

  • docker run -d -p 5002:3000 presidio-analyzer-custom:latest (using default PORT=3000)
  • Or document that users can override the PORT environment variable if needed

Copilot uses AI. Check for mistakes.

## Common Pitfalls and Best Practices

### 1. Memory Issues with Multiple Languages

**Problem**: Adding 10+ languages at once can cause the Docker image to run out of memory during build or runtime.

**Solutions**:
- Use smaller spaCy models (e.g., `es_core_news_sm` instead of `es_core_news_lg`)
Copy link
Collaborator

@omri374 omri374 Dec 8, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please add a caveat about smaller models likely being less accurate in detecting PII in the text

- Increase Docker memory allocation:
```bash
docker run -d -p 5002:3000 --memory="4g" presidio-analyzer-custom:latest
```
- Build images with only the languages you actually need
- Consider using transformers models which can be more memory-efficient
Copy link
Collaborator

@omri374 omri374 Dec 8, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not sure this is true. Do you have a concrete example?

Copy link

Copilot AI Jan 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The recommendation to "Consider using transformers models which can be more memory-efficient" may be misleading. Transformers models are typically more memory-intensive than smaller spaCy models, not less. The advantage of transformers is usually better accuracy for certain tasks, not memory efficiency.

If the intent is to suggest using a single multilingual transformer model instead of multiple language-specific spaCy models, this should be clarified. Otherwise, this recommendation could confuse users about the memory characteristics of transformers vs spaCy models.

Consider revising to: "Consider using a single multilingual transformers model instead of multiple language-specific spaCy models, which can reduce the total model size" or removing this point if it's not accurate for the intended use case.

Suggested change
- Consider using transformers models which can be more memory-efficient
- Consider using a single multilingual transformers model instead of multiple language-specific spaCy models, which can reduce the total model size

Copilot uses AI. Check for mistakes.

### 2. Warning: NLP Recognizer Not in List

If you see warnings like:
```
UserWarning: NLP recognizer (e.g. SpacyRecognizer, StanzaRecognizer) is not in the list of recognizers for language en.
```

**Solution**: Ensure your language configuration matches your installed models:

1. Check `default_recognizers.yaml` includes your language
2. Verify the spaCy model is properly downloaded in the Dockerfile
3. Ensure the language code matches (e.g., 'en' for English, 'es' for Spanish)

Comment on lines +107 to +119
Copy link

Copilot AI Jan 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The warning about "NLP recognizer is not in the list of recognizers" is misleading. This warning typically occurs when the NLP engine configuration (spacy models) doesn't match the recognizer registry configuration, not just when language configuration doesn't match installed models.

The solution provided is incomplete. Based on the actual Presidio architecture:

  1. The default_recognizers.yaml file controls which recognizers are loaded and which languages they support
  2. The NLP configuration file (e.g., default.yaml) controls which spaCy models are installed
  3. These two must be aligned: if you add Spanish support, you need BOTH the Spanish spaCy model in the NLP config AND Spanish language support declared in the recognizer registry

The documentation should clarify that this warning appears when recognizers are configured for a language but no NLP model is configured for that language in the NLP configuration file.

Copilot uses AI. Check for mistakes.
### 3. Model Size vs. Accuracy Trade-off

spaCy offers different model sizes:
- `sm` (small): ~15MB, faster but less accurate
- `md` (medium): ~40MB, balanced
- `lg` (large): ~500MB+, most accurate but resource-intensive

**Recommendation**: Start with `md` models for a good balance.
Copy link
Collaborator

@omri374 omri374 Dec 8, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Our recommendation is to start with the large models


## Complete Example: Building a Multi-Language Analyzer

Here's a complete example for Spanish and French support:

### Modified Dockerfile

```dockerfile
FROM python:3.11-slim
Copy link

Copilot AI Jan 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The Dockerfile example specifies Python 3.11-slim, but the actual Presidio Dockerfile uses Python 3.12-slim (as seen in line 1 of the actual Dockerfile). While Python 3.11 is supported by Presidio according to the installation documentation, the example should match the current official Dockerfile to avoid confusion.

Consider updating to Python 3.12-slim to match the current official implementation, or add a note that users can use any supported Python version (3.10-3.13 according to installation.md).

Suggested change
FROM python:3.11-slim
FROM python:3.12-slim

Copilot uses AI. Check for mistakes.

WORKDIR /usr/bin/presidio-analyzer

# Copy requirements
COPY requirements.txt .
RUN pip install -r requirements.txt

# Install spaCy language models
RUN python -m spacy download en_core_web_lg
RUN python -m spacy download es_core_news_md
RUN python -m spacy download fr_core_news_md
Copy link
Collaborator

@omri374 omri374 Dec 8, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If you download models but not configure the NER model configuration, presidio will ignore those models.


# Copy application code
COPY . .

EXPOSE 3000

CMD ["python", "app.py"]
Comment on lines +138 to +154
Copy link

Copilot AI Jan 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The Dockerfile example provided is incomplete and doesn't match the actual Presidio architecture. The real Presidio Dockerfile:

  1. Uses Python 3.12-slim (not 3.11-slim) as of the current version
  2. Uses Poetry for dependency management, not direct pip install
  3. Installs models via a configuration-driven approach using install_nlp_models.py, not direct spacy download commands
  4. Has a more complex structure with environment variables, non-root user setup, and health checks

This simplified example could mislead users into thinking they should manually add RUN python -m spacy download commands, when they should actually be modifying the YAML configuration files. Either remove this example or replace it with accurate guidance on modifying the NLP configuration file (e.g., conf/default.yaml or using a custom configuration file via build args).

Suggested change
WORKDIR /usr/bin/presidio-analyzer
# Copy requirements
COPY requirements.txt .
RUN pip install -r requirements.txt
# Install spaCy language models
RUN python -m spacy download en_core_web_lg
RUN python -m spacy download es_core_news_md
RUN python -m spacy download fr_core_news_md
# Copy application code
COPY . .
EXPOSE 3000
CMD ["python", "app.py"]
FROM python:3.12-slim
# Install system dependencies and Poetry
RUN apt-get update && \
apt-get install -y --no-install-recommends curl build-essential && \
pip install --no-cache-dir poetry && \
rm -rf /var/lib/apt/lists/*
WORKDIR /usr/bin/presidio-analyzer
# Copy project metadata and install Python dependencies with Poetry
COPY pyproject.toml poetry.lock ./
RUN poetry install --no-dev --no-interaction --no-ansi
# Copy NLP configuration which controls which spaCy models are installed
# Customize this YAML file (or provide your own via build args) instead of
# adding `python -m spacy download ...` commands in the Dockerfile.
COPY conf ./conf
# Install NLP models based on the configuration file
RUN poetry run python -m presidio_analyzer.install_nlp_models --conf-file conf/default.yaml
# Copy application code
COPY . .
# Create and switch to a non-root user
RUN useradd -m presidio && chown -R presidio /usr/bin/presidio-analyzer
USER presidio
EXPOSE 3000
# Simple health check endpoint is expected at /health
HEALTHCHECK --interval=30s --timeout=5s --retries=3 \
CMD curl -fsS http://localhost:3000/health || exit 1
# Start the analyzer service (command may vary by version; see official Dockerfile)
CMD ["poetry", "run", "gunicorn", "-b", "0.0.0.0:3000", "presidio_analyzer.entrypoints.app:app"]

Copilot uses AI. Check for mistakes.
```

### Test Your Custom Image

```bash
# Build the image
docker build -t my-presidio-analyzer .

# Run the container
docker run -d -p 5002:3000 my-presidio-analyzer
Comment on lines +163 to +164
Copy link

Copilot AI Jan 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The docker run command has an inconsistent port mapping. The command maps external port 5002 to internal port 3000, but the Dockerfile example shown earlier in the documentation (lines 135-155) doesn't specify the PORT environment variable, and the subsequent curl test (line 167) uses port 5002 which would only work if the port mapping is correct.

The documentation should clarify:

  1. What the default internal port is (3000 in actual Presidio Dockerfile)
  2. Ensure all examples use consistent port mappings throughout the document

Copilot uses AI. Check for mistakes.

# Test with curl
curl -X POST http://localhost:5002/analyze \
-H "Content-Type: application/json" \
-d '{"text": "Mi nombre es David y mi email es david@example.com", "language": "es"}'
```

## Using Docker Compose

For complex setups, use docker-compose.yml:

```yaml
version: '3.8'
Copy link

Copilot AI Jan 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The docker-compose.yml example uses version '3.8', but the actual Presidio docker-compose.yml files in the repository don't specify a version (which is the recommended practice for modern Docker Compose). The version field is deprecated in the latest Docker Compose specification.

Consider either:

  1. Removing the version: '3.8' line to follow current best practices
  2. Adding a note that the version field is optional in modern Docker Compose

This is a minor point but helps keep the documentation aligned with current Docker Compose conventions.

Suggested change
version: '3.8'

Copilot uses AI. Check for mistakes.
services:
presidio-analyzer:
build:
context: ./presidio-analyzer
ports:
- "5002:3000"
environment:
- LOG_LEVEL=INFO
deploy:
resources:
limits:
memory: 4G

presidio-anonymizer:
image: mcr.microsoft.com/presidio-anonymizer:latest
ports:
- "5001:3000"
Comment on lines +186 to +194
Copy link

Copilot AI Jan 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The docker-compose.yml example has incorrect port mappings. Looking at the actual Presidio docker-compose files:

  • The actual Dockerfile exposes port 3000 (line 13: ENV PORT=3000)
  • The docker-compose files use port 5001 internally and map it to different external ports

The example should either:

  1. Match the actual default configuration where services run on internal port 5001 (or 3000 depending on environment variables)
  2. Ensure the external to internal port mapping is consistent (e.g., "5002:3000" for analyzer, "5001:3000" for anonymizer if using PORT=3000)

The current example uses "5002:3000" for presidio-analyzer and "5001:3000" for presidio-anonymizer, which is inconsistent with the environment variable PORT=5001 shown in the anonymizer service configuration. Additionally, the memory limits syntax should use "cpus" and "memory" under deploy.resources.limits as per the actual docker-compose.yml in the repository.

Suggested change
deploy:
resources:
limits:
memory: 4G
presidio-anonymizer:
image: mcr.microsoft.com/presidio-anonymizer:latest
ports:
- "5001:3000"
- PORT=3000
deploy:
resources:
limits:
cpus: "1.0"
memory: 4G
presidio-anonymizer:
image: mcr.microsoft.com/presidio-anonymizer:latest
ports:
- "5001:3000"
environment:
- PORT=3000

Copilot uses AI. Check for mistakes.
```

Run with:
```bash
docker-compose up --build
```

## Additional Resources

- [Presidio Analyzer Documentation](https://microsoft.github.io/presidio/analyzer/)
- [spaCy Language Models](https://spacy.io/models)
- [Presidio Custom Recognizers](https://microsoft.github.io/presidio/analyzer/adding_recognizers/)
- [Analyzer Engine Provider](https://microsoft.github.io/presidio/analyzer/analyzer_engine_provider/)
Copy link

Copilot AI Jan 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The link to "Analyzer Engine Provider" documentation appears to be inconsistent with the actual file name. The link uses /analyzer/analyzer_engine_provider/ (suggesting a directory), but the actual file in the repository is analyzer/analyzer_engine_provider.md (a single markdown file).

The correct link format should be:
[Analyzer Engine Provider](https://microsoft.github.io/presidio/analyzer/analyzer_engine_provider/)

This likely works in practice due to how MkDocs handles URLs, but it's better to be consistent with the actual file structure for clarity.

Suggested change
- [Analyzer Engine Provider](https://microsoft.github.io/presidio/analyzer/analyzer_engine_provider/)
- [Analyzer Engine Provider](https://microsoft.github.io/presidio/analyzer/analyzer_engine_provider.md)

Copilot uses AI. Check for mistakes.

## Troubleshooting

### Issue: Build fails with "No space left on device"
**Solution**: Clean up Docker resources:
```bash
docker system prune -a
```

### Issue: Container crashes on startup
**Solution**: Check logs and increase memory:
```bash
docker logs <container-id>
docker run --memory="6g" ...
```

## Contributing

For questions or contributions, please refer to the [Presidio Contributing Guide](https://github.com/microsoft/presidio/blob/main/CONTRIBUTING.md).

## Related Documentation

- [Installation Guide](./installation.md)
- [Getting Started with Presidio](./getting_started/getting_started_text.md)
- [Supported Languages](https://microsoft.github.io/presidio/analyzer/languages/)

This guide addresses [Issue #1663](https://github.com/microsoft/presidio/issues/1663) - More elaborate description for building custom Docker images for Presidio.
Comment on lines +1 to +234
Copy link

Copilot AI Jan 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The new documentation file docker_customization.md is not added to the MkDocs navigation structure in mkdocs.yml. This means the documentation will not be accessible through the site navigation menu.

The file should be added to the appropriate section of the nav: structure in mkdocs.yml, likely under the "Resources" section near the "Installation" or "Setting up a development environment" entries, or possibly under the "Learn Presidio" section near the language/NLP configuration documentation.

For example, it could be added under Resources:

- Resources:
    - Supported entities: supported_entities.md
    - Installation: installation.md
    - Docker Image Customization: docker_customization.md

Without this change, users will not be able to navigate to this documentation through the normal site structure.

Copilot uses AI. Check for mistakes.