Dual Python Architecture

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• pyproject.toml
• tests/test_static.py
• docker/container/metatrader/setup.sh
• docker/compose.yaml
• tests/constants.py
• tests/test_runtime.py

The Dual Python Architecture is a core design feature of the mt5-docker project, designed to reconcile the version requirements of modern Python development tools with the legacy environment constraints of MetaTrader 5 (MT5). It utilizes two distinct Python installations: a modern System Python (3.13) for the Linux host environment and a specific Wine Python (3.12) within the Windows emulation layer.

This architecture ensures that the system can leverage high-performance asynchronous libraries and modern dependency management on the Linux side while maintaining strict compatibility with MetaTrader 5 and NumPy 1.26.4 on the Windows/Wine side.

Sources: README.md:15-18, tests/test_static.py:87-105

---

Architectural Components

The system is split into two isolated execution environments that communicate via a gRPC bridge.

Linux System Environment (Python 3.13)

The Linux environment (based on Debian) runs Python 3.13. This version is used for:

• Running the gRPC client via mt5linux.
• Modern development tooling, linting (Ruff, Mypy), and testing (Pytest).
• Container orchestration and health monitoring scripts.

Sources: README.md:112-114, pyproject.toml:49, tests/constants.py:276

Wine/Windows Environment (Python 3.12)

Inside the Wine prefix, the system installs Python 3.12. This specific version is required because:

• MT5 Compatibility: The MetaTrader5 Python package has strict dependencies on specific Windows-compiled binaries.
• NumPy Constraints: MetaTrader 5 requires numpy 1.26.4, which has specific compatibility requirements met by the Python 3.12 Wine installation.

Sources: README.md:115-117, docker/compose.yaml:8-12, tests/test_static.py:100-115

---

Data Flow and Communication

The two Python environments interact through a gRPC-based bridge pattern. The Wine Python environment hosts the gRPC server, which directly interfaces with the MetaTrader 5 terminal.

The diagram shows the transition from the modern Linux Python 3.13 environment to the specialized Wine Python 3.12 environment via gRPC calls.

Sources: docker/container/metatrader/mt5.proto:1-10, tests/test_static.py:650-670, README.md:180-210

---

Environment Comparison

Feature	System Python	Wine Python
Version	3.13.x	3.12.x
Operating System	Linux (Debian)	Windows (via Wine 10.0)
Primary Role	Tooling, Tests, gRPC Client	MT5 API, gRPC Server
Key Dependency	mt5linux	MetaTrader5, numpy 1.26.4
Installation Path	/usr/bin/python3	C:\Python ($WINEPREFIX/drive_c/Python)

Sources: README.md:110-120, docker/container/metatrader/setup.sh:138-142, tests/test_runtime.py:175-210

---

Initialization and Setup Logic

The installation of the Wine-side Python 3.12 is handled during the container's first boot by the setup.sh script. This process is isolated and idempotent.

Wine Python Installation Sequence

1. Prefix Init: A Wine prefix is created at /config/.wine.
2. Binary Download: The Python 3.12 installer (python-installer.exe) is executed via Wine in quiet mode.
3. Path Configuration: Python is installed to C:\Python.
4. Dependency Pinning: Specific versions of grpcio, protobuf, and numpy are installed into the Wine site-packages.

This sequence ensures that the Wine Python environment is correctly provisioned before the MT5 terminal starts.

Sources: docker/container/metatrader/setup.sh:105-165, docker/compose.yaml:7-13

---

Version Consistency Validation

The project employs static and runtime tests to prevent "version drift" between the two environments.

• Static Checks: tests/test_static.py verifies that versions.env, Dockerfile ARGs, and pyproject.toml all reference the correct corresponding versions (3.13 for system, 3.12 for Wine).
• Runtime Checks: tests/test_runtime.py executes version checks inside the running container to ensure the expected binaries are actually in use.

# tests/test_runtime.py:177-185
def test_wine_python_version(self, container_name: str) -> None:
    """Verify Python 3.12.x is installed in Wine."""
    result = docker_exec(
        container_name,
        ["wine", "python", "--version"],
        user="abc",
    )
    assert result.returncode == 0
    version = result.stdout.strip()
    assert "3.12" in version

Sources: tests/test_static.py:125-160, tests/test_runtime.py:175-185

---

Summary

The Dual Python Architecture provides a robust solution for running MetaTrader 5 in a modern DevOps workflow. By isolating the legacy requirements of the MT5 Python API (Python 3.12/Wine) from the requirements of modern development tools (Python 3.13/Linux), the project achieves high stability without sacrificing performance or developer experience.

Sources: README.md:15-30, AGENTS.md:7-15