installation.md

Installation

PyMemoryEditor is published on PyPI as a pure-Python wheel — there is no native build step or compiler required on any platform.

Requirements

Python	3.10 or newer
Operating systems	🪟 Windows · 🐧 Linux · 🍎 macOS

Install the library

pip install PyMemoryEditor

Install with the bundled GUI app

The library ships an optional Cheat Engine-style GUI built on PySide6 (Qt for Python). To install it, use the app extra:

pip install "PyMemoryEditor[app]"

Once installed, launch the app from any terminal:

pymemoryeditor

The library itself stays dependency-free — only the app extra pulls in its dependencies.

See the GUI App guide for a tour of every feature.

Install with scan acceleration (speed)

Scans run in pure Python by default — no dependencies, works everywhere. If you scan large processes often, the optional speed extra pulls in NumPy and automatically vectorizes the inner comparison loop of the typed numeric scans (BIGGER_THAN, SMALLER_THAN, VALUE_BETWEEN, …):

pip install "PyMemoryEditor[speed]"

That's the only change required — there is no new API and no flag to toggle. PyMemoryEditor detects NumPy at import time and switches the fast path on; if NumPy is absent it falls back to the pure-Python loop transparently. The results are identical either way — only the speed changes (typically ~10–30× faster on selective scans of large regions). See Scan acceleration for details and benchmarks.

NumPy ships prebuilt wheels for Windows, Linux and macOS, so the speed extra stays compiler-free and cross-platform — no native build step on any OS.

Install with the MCP server (mcp)

The library ships an optional Model Context Protocol server, which lets an AI assistant run the scan / refine / read loop itself. The mcp extra pulls in the official MCP SDK:

pip install "PyMemoryEditor[mcp]"

That installs a pymemoryeditor-mcp console script. You do not run it yourself — it speaks the protocol over stdin/stdout, so a client launches it. Register it once:

claude mcp add pymemoryeditor -- pymemoryeditor-mcp

Or, in any client that reads mcpServers JSON (Claude Desktop, editors, …):

{
  "mcpServers": {
    "pymemoryeditor": {
      "command": "pymemoryeditor-mcp",
      "args": []
    }
  }
}

No flags either way. You do not name a target when you register it: the server asks for your approval before attaching to a process you have not pre-approved, so one registration covers whatever you end up working on, and your client confirms every write. Pass --read-only to drop the write tool entirely.

Only the protocol layer needs the SDK — the tool implementations import nothing from it, and the core library stays dependency-free either way.

The server runs with your privileges and is not a sandbox. See the MCP Server guide for the full tool list, the safety model and the rest of the options.

Install from source

git clone https://github.com/JeanExtreme002/PyMemoryEditor.git
cd PyMemoryEditor
pip install -e ".[dev]"

The dev extra installs the test toolchain (pytest, pytest-xdist, pytest-qt, hypothesis, mypy, etc.) — see CONTRIBUTING.md for the development workflow.

Verifying the installation

import PyMemoryEditor
print(PyMemoryEditor.__version__)

If that prints a version number, you're ready to go — head to the Quick Start.

Platform-specific notes

:class: note

Works out of the box. To attach to **protected processes** (system services,
elevated apps), run your terminal **as Administrator**.

:class: note

Access depends on `ptrace_scope` and process ownership. If the target is **not**
a child of the caller and `ptrace_scope=1` (the common default), you'll see a
`PermissionError`. Run as root, or relax it:

    sudo sysctl kernel.yama.ptrace_scope=0

:class: note

Opening **another** process requires the Python binary to be signed with the
`com.apple.security.cs.debugger` entitlement (or SIP disabled and root).
**Opening the current process** always works — handy for self-inspection and
experimentation.

For the long version, see Platform Notes.