Pymem

Common errors

• Pymem.exceptions.PymemError: Could not find process 'XYZ.exe'.

  cause The specified process name was not found running on the system.
  fix Ensure the target application is running and its exact executable name (e.g., 'notepad.exe', 'csgo.exe') is provided. Verify there are no typos. Use `process.get_pid_by_name()` to confirm existence before creating a `Pymem` object.

• PermissionError: [WinError 5] Access is denied.

  cause The Python script does not have sufficient privileges to open or interact with the target process's memory.
  fix Run your Python script as an administrator. Right-click your Python IDE or command prompt/PowerShell icon and select 'Run as administrator'.

• AttributeError: module 'pymem' has no attribute 'Pymem'

  cause This typically occurs when trying `import pymem` and then using `pymem.Pymem()`. The `Pymem` class is directly under the `pymem` package.
  fix Change your import statement to `from pymem import Pymem`. Then you can create an instance directly as `pm = Pymem("process.exe")`.

Warnings

• gotcha Pymem is exclusively designed for Windows operating systems. It relies heavily on the Windows API and will not function on Linux, macOS, or other platforms.
  Fix: Ensure your development and deployment environment is Windows. For cross-platform memory manipulation, consider alternative approaches or OS-specific solutions.
• gotcha Many memory access operations (e.g., opening system processes, writing to protected memory regions) require elevated permissions. Running your Python script as an administrator is often necessary to avoid 'Access is denied' errors.
  Fix: Run your Python script with administrative privileges (right-click -> 'Run as administrator' on Windows, or use an elevated command prompt/PowerShell).
• breaking Pymem explicitly states `requires_python <4.0.0,>=3.8`. It is not compatible with Python 4.0.0 or higher, and officially supports Python 3.8 up to 3.12. Using it with unsupported Python versions may lead to unexpected errors or crashes.
  Fix: Ensure you are using a Python interpreter version within the `3.8` to `3.12` range. Avoid Python 3.13+ or any future 4.x versions.
• gotcha Incorrect memory writes can lead to target application crashes, data corruption, or even system instability. Pymem provides direct access with minimal safety checks at the memory level.
  Fix: Exercise extreme caution when writing to memory. Always verify addresses and data types. Consider backing up data or running tests in isolated environments first.
• gotcha The target process might not be found, or it might terminate unexpectedly. This leads to `PymemError: Could not find process` or `Could not open process` exceptions.
  Fix: Always wrap Pymem operations in `try...except PymemError` blocks. Verify the process name is correct and the application is actively running before attempting to open it. Re-attempt opening the process if it's transient.

Install

• pip install pymem Install Pymem

Imports

• Pymem
  wrong:

  import pymem; pm = pymem.Pymem()

  correct:

  from pymem import Pymem

  The main class is 'Pymem', directly import it from the 'pymem' package.

Quickstart

This quickstart demonstrates how to open a target process (notepad.exe), retrieve its Process ID (PID) and base memory address, and attempt to read a few bytes from it. It's crucial that the target process is running and the Python script has sufficient permissions (e.g., run as administrator) to interact with it.

import os
import time
from pymem import Pymem, process
from pymem.exception import PymemError

# NOTE: Pymem is Windows-specific and often requires administrator privileges.
# For this example, we'll try to find 'notepad.exe'.
# Make sure Notepad is running before executing this code.

process_name = "notepad.exe"
p = None

try:
    # Find the process ID of notepad.exe
    pid = process.get_pid_by_name(process_name)
    print(f"Found {process_name} with PID: {pid}")

    # Open the process
    p = Pymem(process_name)
    print(f"Successfully opened process {process_name}.")

    # Example: Reading the base address (typically the module's base address)
    # This is often used to calculate offsets to specific memory locations.
    base_address = p.base_address
    print(f"Base address of {process_name}: {hex(base_address)}")

    # For a more meaningful example, one would typically search for a known pattern
    # or address relative to the base address and then read/write data.
    # As a simple demonstration, let's just confirm we can access some memory.
    # Reading a few bytes from the base address itself (usually code):
    try:
        first_bytes = p.read_bytes(base_address, 8)
        print(f"First 8 bytes at base address: {first_bytes.hex()}")
    except PymemError as e:
        print(f"Could not read from base address (might be protected): {e}")

finally:
    if p:
        p.close_process()
        print(f"Closed process handle for {process_name}.")
    else:
        print(f"Could not open process {process_name}. Ensure it's running and you have permissions.")