Installation & Environment Setup

Mongomock is distributed as a standard Python package on PyPI. It is built to run on modern Python environments and integrates with standard virtual environment workflows.

Prerequisites & Requirements

Mongomock requires Python 3.9 or newer (including support for 3.10, 3.11, 3.12, 3.13, and PyPy3). Support for deprecated Python runtimes (including Python 3.8 and below) has been removed.

The base installation depends on the following libraries:

packaging: For internal version check calculations.
pytz: To manage timezone metadata.
sentinels: For handling null/unassigned states in query logic.

Standard Installation

Install the stable package from PyPI using your preferred package manager:

pip install mongomock

Optional Dependencies (Extras)

Depending on your application's testing needs, you can install Mongomock with specialized dependencies:

PyMongo Support (pymongo): Enables native BSON encoding, exception parsing, and validation checks that mirror the actual driver. Highly recommended if your code depends on PyMongo exceptions or custom helper classes:
```
pip install mongomock[pymongo]
```
Map-Reduce Support (pyexecjs): Required if your legacy testing flows call .map_reduce() or .group() collection methods. This extra requires a JavaScript runtime environment (like Node.js) installed on the host system to run compiled JS blocks:
```
pip install mongomock[pyexecjs]
```

Development Workspace Setup

To contribute to the library or run the test suite directly on your machine, Mongomock uses Hatch for environment management and compilation.

Clone the Repository:

git clone https://github.com/mongomock/mongomock.git
cd mongomock

Install Hatch: We recommend installing Hatch globally via pipx:
```
pipx install hatch
```
Run the Local Test Suite: Hatch automatically manages dependencies, environment matrix allocations, and executes testing commands:
```
hatch test
```
Run Static Type Checkers: Verify code type correctness using mypy via Hatch:
```
hatch run types:check
```

Containerized Integration Testing

The repository includes a docker-compose.yml and Dockerfile to simplify local integration testing. This setup mounts your local workspace and runs testing actions inside an isolated Ubuntu-based environment alongside a physical MongoDB v5.0.5 container.

services:
  mongomock:
    build:
      context: .
    image: mongomock:latest
    working_dir: /project
    command: hatch test
    environment:
      - TEST_MONGO_HOST=mongodb://mongo/mock
      - MONGODB=5.0.5
    volumes:
      - .:/project
    depends_on:
      - mongo

  mongo:
    image: mongo:5.0.5
    ports:
      - 127.0.0.1:27017:27017

Building and Running the Containers

Build the Testing Image:
```
docker compose build
```
Execute the Test Suites: Runs the test runner inside the Ubuntu container:
```
docker compose run --rm mongomock
```
Run Tests Against a Specific Environment Matrix: If you want to run hatch against a specific environment version combination inside the container:
```
docker compose run --rm mongomock hatch test -py=3.11 -i pymongo=4
```

Note: If the MongoDB service container configuration changes, run docker compose down before rebuilding to ensure a clean database state. For details on configuring server variables, read the Configuration Guide.