{"id":978,"library":"cymem","title":"cymem","description":"cymem is a Python library that provides efficient memory-management helpers for Cython. It simplifies tying C-level memory allocations (via `calloc`/`free`) to the lifecycle of Python objects, automatically freeing memory when the owning Python object is garbage collected. The core component is `cymem.Pool`, a thin wrapper around `calloc`. Currently at version 2.0.13, it maintains a regular release cadence, often aligning with new Python version support and performance enhancements like free-threading.","status":"active","version":"2.0.13","language":"python","source_language":"en","source_url":"https://github.com/explosion/cymem","tags":["Cython","memory management","low-level","C extensions","ffi"],"install":[{"cmd":"pip install cymem","lang":"bash","label":"Install with pip"}],"dependencies":[{"reason":"Required for compiling and using `cymem` in Cython projects, as `cymem` itself is a Cython library that interacts with C-level memory.","package":"Cython","optional":false}],"imports":[{"wrong":"from cymem import Pool","symbol":"about","correct":"from cymem import about"}],"quickstart":{"code":"from cymem.cymem cimport Pool\nfrom libc.stdlib cimport sizeof\n\ndef main():\n    cdef Pool mem = Pool()\n    cdef int* data1 = <int*>mem.alloc(10, sizeof(int))\n    cdef float* data2 = <float*>mem.alloc(12, sizeof(float))\n\n    # Use data1 and data2\n    data1[0] = 100\n    data2[0] = 3.14\n\n    print(f\"Data1 at index 0: {data1[0]}\")\n    print(f\"Data2 at index 0: {data2[0]}\")\n\n    # Memory is automatically freed when 'mem' (the Pool object) is garbage collected.\n    # No explicit free() calls are needed for memory allocated via Pool.\n\n# To run this, you would typically compile it with Cython:\n# cython -3 --inplace your_module.pyx\n# Then import and call main() from Python:\n# import your_module\n# your_module.main()","lang":"cython","description":"This example demonstrates how to allocate C-level memory using `cymem.Pool` within a Cython `.pyx` file. The `Pool` object handles the deallocation of all memory allocated through it when the `Pool` instance itself is garbage collected, simplifying memory management in Cython extensions."},"warnings":[{"fix":"Ensure critical sections are used for internal state access, and apply fine-grained locks or other synchronization primitives when sharing access to memory contents across threads. Do not rely on coarse-grained locks on the `Pool` instance itself for memory content synchronization.","message":"When `cymem.Pool` is used with CPython 3.13+ free-threaded builds (PEP 703), operations like `alloc()`, `free()`, and `realloc()` are thread-safe. However, reading the internal state (e.g., `addresses` dict) without explicit critical sections is not thread-safe. Users are also responsible for synchronizing access to the *contents* of the allocated memory across threads.","severity":"gotcha","affected_versions":">=2.0.12"},{"fix":"Ensure your installed Cython version is compatible with the `cymem` version. If encountering this error, try recompiling your Cython project (if you're compiling `cymem` from source or an older wheel) or updating `cymem` to a version with wheels pre-built against a compatible Cython release. It's recommended to update `pip`, `setuptools`, and `wheel` before installing to ensure the latest compatible binary wheels are used.","message":"Incompatibility between `cymem`'s compiled C++ files and the installed Cython version can lead to errors like `ValueError: cymem.cymem.Pool has the wrong size, try recompiling.` This often happens when Cython's internal structures change.","severity":"breaking","affected_versions":"<2.0.5 (older versions were more susceptible, but can still occur with mismatched builds)."},{"fix":"Carefully manage the lifetime of your `cdef` Python objects that hold `cymem.Pool` instances. Ensure that any C pointers derived from the pool are only accessed while the owning Python object and its associated `Pool` are still alive and in scope.","message":"`cymem.Pool` simplifies memory deallocation by tying it to the Python object's lifecycle. However, users must still ensure that no raw C pointers obtained from the pool outlive the Python object that owns the `Pool` instance. If the `Pool` object is garbage collected, all its managed memory is freed, invalidating any lingering pointers.","severity":"gotcha","affected_versions":"All versions"},{"fix":"If you are developing a Cython extension, ensure your source file is named `.pyx` and is compiled with Cython. If you intend to use `cymem` from Python, you typically import a *compiled* module that uses `cymem` internally, or `cymem`'s public Python API if available, using standard Python `import` statements. Do not use `cimport` in `.py` files.","message":"Attempting to use Cython-specific `cimport` syntax (e.g., `from cymem.cymem cimport Pool`) directly in a `.py` file executed by a standard Python interpreter will result in a `SyntaxError`. Cython's `cimport` is exclusively for defining types and functions within Cython source files (`.pyx`) that will be compiled, not for Python scripts.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Use `cimport` exclusively within Cython (`.pyx`) files. To use `cymem.Pool` from a Python (`.py`) file, import it like a regular Python object (e.g., `from cymem.cymem import Pool`) after the `cymem` library (or your own Cython code that `cimports` `cymem`) has been properly compiled and installed.","message":"Attempting to use Cython's `cimport` statement directly in a standard Python (`.py`) file will result in a `SyntaxError`. `cimport` is a Cython-specific keyword valid only in Cython (`.pyx`) source files, which must be compiled into a Python-loadable extension before they can be imported into Python.","severity":"breaking","affected_versions":"All versions"}],"env_vars":null,"search_vec":"'2.0.13':57 'align':65 'alloc':23 'around':52 'automat':33 'c':20,84 'c-level':19 'cadenc':63 'calloc':25,53 'collect':43 'compon':46 'core':45 'current':54 'cymem':1,2 'cymem.pool':48 'cython':15,78 'effici':9 'enhanc':73 'extens':85 'ffi':86 'free':26,34,76 'free-thread':75 'garbag':42 'helper':13 'level':21,83 'librari':6 'lifecycl':29 'like':74 'low':82 'low-level':81 'maintain':59 'manag':12,80 'memori':11,22,35,79 'memory-manag':10 'new':67 'object':32,40 'often':64 'own':38 'perform':72 'provid':8 'python':5,31,39,68 'regular':61 'releas':62 'simplifi':17 'support':70 'thin':50 'thread':77 'tie':18 'version':56,69 'via':24 'wrapper':51","created_at":"2026-03-29T08:37:16.808895+00:00","updated_at":"2026-04-16T04:43:47.090151+00:00","problems":null,"ecosystem":"pypi","meta_description":null,"install_score":0,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"2.0.13","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/explosion/cymem","docs":null,"changelog":null,"pypi":"https://pypi.org/project/cymem/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["database"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-07-03","last_verified":"2026-07-03","next_check":"2026-08-02","install_tag":"stale"}}