{"id":13460256,"url":"https://github.com/bloomberg/memray","last_synced_at":"2025-05-12T18:35:26.894Z","repository":{"id":36986960,"uuid":"479491550","full_name":"bloomberg/memray","owner":"bloomberg","description":"Memray is a memory profiler for Python","archived":false,"fork":false,"pushed_at":"2025-04-28T00:41:08.000Z","size":30556,"stargazers_count":13927,"open_issues_count":33,"forks_count":406,"subscribers_count":59,"default_branch":"main","last_synced_at":"2025-05-05T15:59:39.784Z","etag":null,"topics":["hacktoberfest","memory","memory-leak","memory-leak-detection","memory-profiler","profiler","python","python3"],"latest_commit_sha":null,"homepage":"https://bloomberg.github.io/memray/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bloomberg.png","metadata":{"files":{"readme":"README.md","changelog":"NEWS.rst","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":"docs/supported_environments.rst","governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2022-04-08T18:04:11.000Z","updated_at":"2025-05-05T12:53:25.000Z","dependencies_parsed_at":"2023-09-26T08:02:48.178Z","dependency_job_id":"94206be4-8db9-4951-81c5-21b15436a2a7","html_url":"https://github.com/bloomberg/memray","commit_stats":{"total_commits":1137,"total_committers":60,"mean_commits":18.95,"dds":0.6473175021987687,"last_synced_commit":"df48806ce175d469823ee57d86c291da778e0ee0"},"previous_names":[],"tags_count":31,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bloomberg%2Fmemray","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bloomberg%2Fmemray/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bloomberg%2Fmemray/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bloomberg%2Fmemray/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bloomberg","download_url":"https://codeload.github.com/bloomberg/memray/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253798919,"owners_count":21966170,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["hacktoberfest","memory","memory-leak","memory-leak-detection","memory-profiler","profiler","python","python3"],"created_at":"2024-07-31T10:00:38.164Z","updated_at":"2025-05-12T18:35:26.860Z","avatar_url":"https://github.com/bloomberg.png","language":"Python","readme":"\u003cp align=\"center\"\u003e\n\u003cimg src=\"https://raw.githubusercontent.com/bloomberg/memray/main/docs/_static/images/logo.png\" width=\"70%\"\u003e\n\u003c/p\u003e\n\n---\n\n[![OS Linux](https://img.shields.io/badge/OS-Linux-blue)](https://pypi.org/project/memray)\n[![OS MacOS](https://img.shields.io/badge/OS-macOS-blue)](https://pypi.org/project/memray)\n[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/memray)](https://pypi.org/project/memray)\n[![PyPI - Implementation](https://img.shields.io/pypi/implementation/memray)](https://pypi.org/project/memray)\n[![PyPI](https://img.shields.io/pypi/v/memray)](https://pypi.org/project/memray)\n[![PyPI - Downloads](https://img.shields.io/pypi/dm/memray)](https://pypistats.org/packages/memray)\n[![Conda Version](https://img.shields.io/conda/vn/conda-forge/memray.svg)](https://anaconda.org/conda-forge/memray)\n[![Tests](https://github.com/bloomberg/memray/actions/workflows/build.yml/badge.svg)](https://github.com/bloomberg/memray/actions/workflows/build.yml)\n[![Code Style](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)\n\n\u003cp align=\"center\"\u003e\u003cimg src=\"https://raw.githubusercontent.com/bloomberg/memray/main/docs/_static/images/output.png\" alt=\"Memray output\"\u003e\u003c/p\u003e\n\nMemray is a memory profiler for Python. It can track memory allocations in Python code, in native extension\nmodules, and in the Python interpreter itself. It can generate several different types of reports to help you\nanalyze the captured memory usage data. While commonly used as a CLI tool, it can also be used as a library to\nperform more fine-grained profiling tasks.\n\nNotable features:\n\n- 🕵️‍♀️ Traces every function call so it can accurately represent the call stack, unlike sampling profilers.\n- ℭ Also handles native calls in C/C++ libraries so the entire call stack is present in the results.\n- 🏎 Blazing fast! Profiling slows the application only slightly. Tracking native code is somewhat slower,\n  but this can be enabled or disabled on demand.\n- 📈 It can generate various reports about the collected memory usage data, like flame graphs.\n- 🧵 Works with Python threads.\n- 👽🧵 Works with native-threads (e.g. C++ threads in C extensions).\n\nMemray can help with the following problems:\n\n- Analyze allocations in applications to help discover the cause of high memory usage.\n- Find memory leaks.\n- Find hotspots in code that cause a lot of allocations.\n\n\u003e **Note**\n\u003e Memray only works on Linux and MacOS, and cannot be installed on other platforms.\n\n\u003cp align=\"center\"\u003e\n\u003cimg src=\"https://raw.githubusercontent.com/bloomberg/memray/main/docs/_static/images/quotes.png\" width=\"100%\"\u003e\n\u003c/p\u003e\n\n# Help us improve Memray!\n\nWe are constantly looking for feedback from our awesome community ❤️. If you\nhave used Memray to solve a problem, profile an application, find a memory leak\nor anything else, please let us know! We would love to hear about your\nexperience and how Memray helped you.\n\nPlease, consider writing your story in the [Success\nStories discussion page](https://github.com/bloomberg/memray/discussions/226).\n\nIt really makes a difference!\n\n# Installation\n\nMemray requires Python 3.7+ and can be easily installed using most common Python\npackaging tools. We recommend installing the latest stable release from\n[PyPI](https://pypi.org/project/memray/) with pip:\n\n```shell\n    python3 -m pip install memray\n```\n\nNotice that Memray contains a C extension so releases are distributed as binary\nwheels as well as the source code. If a binary wheel is not available for your system\n(Linux x86/x64 or macOS), you'll need to ensure that all the dependencies are satisfied on the\nsystem where you are doing the installation.\n\n## Building from source\n\nIf you wish to build Memray from source you need the following binary dependencies in your system:\n\n- libdebuginfod-dev (for Linux)\n- libunwind (for Linux)\n- liblz4\n\nCheck your package manager on how to install these dependencies (for example `apt-get install build-essential python3-dev libdebuginfod-dev libunwind-dev liblz4-dev` in Debian-based systems\nor `brew install lz4` in MacOS). Note that you may need to teach the compiler where to find the header and library files of the dependencies. For\nexample, in MacOS with `brew` you may need to run:\n\n```shell\nexport CFLAGS=\"-I$(brew --prefix lz4)/include\" LDFLAGS=\"-L$(brew --prefix lz4)/lib -Wl,-rpath,$(brew --prefix lz4)/lib\"\n```\n\nbefore installing `memray`. Check the documentation of your package manager to know the location of the header and library\nfiles for more detailed information.\n\nIf you are building on MacOS, you will also need to set the deployment target.\n\n```shell\nexport MACOSX_DEPLOYMENT_TARGET=10.14\n```\n\nOnce you have the binary dependencies installed, you can clone the repository and follow with the normal building process:\n\n```shell\ngit clone git@github.com:bloomberg/memray.git memray\ncd memray\npython3 -m venv ../memray-env/  # just an example, put this wherever you want\nsource ../memray-env/bin/activate\npython3 -m pip install --upgrade pip\npython3 -m pip install -e . -r requirements-test.txt -r requirements-extra.txt\n```\n\nThis will install Memray in the virtual environment in development mode (the `-e` of the last `pip install` command).\n\nIf you plan to contribute back, you should install the pre-commit hooks:\n\n```shell\npre-commit install\n```\n\nThis will ensure that your contribution passes our linting checks.\n\n# Documentation\n\nYou can find the latest documentation available [here](https://bloomberg.github.io/memray/).\n\n# Usage\n\nThere are many ways to use Memray. The easiest way is to use it as a command line tool to run your script, application, or library.\n\n```\nusage: memray [-h] [-v] {run,flamegraph,table,live,tree,parse,summary,stats} ...\n\nMemory profiler for Python applications\n\nRun `memray run` to generate a memory profile report, then use a reporter command\nsuch as `memray flamegraph` or `memray table` to convert the results into HTML.\n\nExample:\n\n    $ python3 -m memray run -o output.bin my_script.py\n    $ python3 -m memray flamegraph output.bin\n\npositional arguments:\n  {run,flamegraph,table,live,tree,parse,summary,stats}\n                        Mode of operation\n    run                 Run the specified application and track memory usage\n    flamegraph          Generate an HTML flame graph for peak memory usage\n    table               Generate an HTML table with all records in the peak memory usage\n    live                Remotely monitor allocations in a text-based interface\n    tree                Generate a tree view in the terminal for peak memory usage\n    parse               Debug a results file by parsing and printing each record in it\n    summary             Generate a terminal-based summary report of the functions that allocate most memory\n    stats               Generate high level stats of the memory usage in the terminal\n\noptional arguments:\n  -h, --help            Show this help message and exit\n  -v, --verbose         Increase verbosity. Option is additive and can be specified up to 3 times\n  -V, --version         Displays the current version of Memray\n\nPlease submit feedback, ideas, and bug reports by filing a new issue at https://github.com/bloomberg/memray/issues\n```\n\nTo use Memray over a script or a single python file you can use:\n\n```shell\npython3 -m memray run my_script.py\n```\n\nIf you normally run your application with `python3 -m my_module`, you can use the `-m` flag with `memray run`:\n\n```shell\npython3 -m memray run -m my_module\n```\n\nYou can also invoke Memray as a command line tool without having to use `-m` to invoke it as a module:\n\n```shell\nmemray run my_script.py\nmemray run -m my_module\n```\n\nThe output will be a binary file (like `memray-my_script.2369.bin`) that you can analyze in different ways. One way is to use the `memray flamegraph` command to generate a flame graph:\n\n```shell\nmemray flamegraph my_script.2369.bin\n```\n\nThis will produce an HTML file with a flame graph of the memory usage that you can inspect with your favorite browser. There are multiple other reporters that you can use to generate other types of reports, some of them generating terminal-based output and some of them generating HTML files. Here is an example of a Memray flamegraph:\n\n\u003cimg src=\"https://github.com/bloomberg/memray/blob/main/docs/_static/images/flamegraph_example.png?raw=true\" align=\"center\"/\u003e\n\n## Pytest plugin\n\nIf you want an easy and convenient way to use `memray` in your test suite, you can consider using [pytest-memray](https://github.com/bloomberg/pytest-memray). Once installed, this pytest plugin allows you to simply add `--memray` to the command line invocation:\n\n```shell\npytest --memray tests/\n```\n\nAnd will automatically get a report like this:\n\n```\npython3 -m pytest tests --memray\n=============================================================================================================================== test session starts ================================================================================================================================\nplatform linux -- Python 3.8.10, pytest-6.2.4, py-1.10.0, pluggy-0.13.1\nrootdir: /mypackage, configfile: pytest.ini\nplugins: cov-2.12.0, memray-0.1.0\ncollected 21 items\n\ntests/test_package.py .....................                                                                                                                                                                                                                      [100%]\n\n\n================================================================================================================================= MEMRAY REPORT ==================================================================================================================================\nAllocations results for tests/test_package.py::some_test_that_allocates\n\n\t 📦 Total memory allocated: 24.4MiB\n\t 📏 Total allocations: 33929\n\t 📊 Histogram of allocation sizes: |▂   █    |\n\t 🥇 Biggest allocating functions:\n\t\t- parse:/opt/bb/lib/python3.8/ast.py:47 -\u003e 3.0MiB\n\t\t- parse:/opt/bb/lib/python3.8/ast.py:47 -\u003e 2.3MiB\n\t\t- _visit:/opt/bb/lib/python3.8/site-packages/astroid/transforms.py:62 -\u003e 576.0KiB\n\t\t- parse:/opt/bb/lib/python3.8/ast.py:47 -\u003e 517.6KiB\n\t\t- __init__:/opt/bb/lib/python3.8/site-packages/astroid/node_classes.py:1353 -\u003e 512.0KiB\n```\n\nYou can also use some of the included markers to make tests\nfail if the execution of said test allocates more memory than allowed:\n\n```python\n@pytest.mark.limit_memory(\"24 MB\")\ndef test_foobar():\n    # do some stuff that allocates memory\n```\n\nTo learn more on how the plugin can be used and configured check out [the plugin documentation](https://pytest-memray.readthedocs.io).\n\n# Native mode\n\nMemray supports tracking native C/C++ functions as well as Python functions. This can be especially useful when profiling applications that have C extensions (such as `numpy` or `pandas`) as this gives a holistic vision of how much memory is allocated by the extension and how much is allocated by Python itself.\n\nTo activate native tracking, you need to provide the `--native` argument when using the `run` subcommand:\n\n```shell\nmemray run --native my_script.py\n```\n\nThis will automatically add native information to the result file and it will be automatically used by any reporter (such the flamegraph or table reporters). This means that instead of seeing this in the flamegraphs:\n\n\u003cimg src=\"https://github.com/bloomberg/memray/blob/main/docs/_static/images/mandelbrot_operation_non_native.png?raw=true\" align=\"center\"/\u003e\n\nYou will now be able to see what's happening inside the Python calls:\n\n\u003cimg src=\"https://github.com/bloomberg/memray/blob/main/docs/_static/images/mandelbrot_operation_native.png?raw=true\" align=\"center\"/\u003e\n\nReporters display native frames in a different color than Python frames. They can also be distinguished by looking at the file location in a frame (Python frames will generally be generated from files with a .py extension while native frames will be generated from files with extensions like .c, .cpp or .h).\n\n# Live mode\n\n\u003cp align=\"center\"\u003e\u003cimg src=\"https://raw.githubusercontent.com/bloomberg/memray/main/docs/_static/images/live_animated.webp\" alt=\"Memray output\"\u003e\u003c/p\u003e\n\nMemray's live mode runs a script or a module in a terminal-based interface that allows you to interactively inspect its memory usage while it runs. This is useful for debugging scripts or modules that take a long time to run or that exhibit multiple complex memory patterns. You can use the `--live` option to run the script or module in live mode:\n\n```shell\n    memray run --live my_script.py\n```\n\nor if you want to execute a module:\n\n```shell\n    memray run --live -m my_module\n```\n\nThis will show the following TUI interface in your terminal:\n\n\u003cimg src=\"https://raw.githubusercontent.com/bloomberg/memray/main/docs/_static/images/live_running.png\" align=\"center\"/\u003e\n\n## Sorting results\n\nThe results are displayed in descending order of total memory allocated by a function and the subfunctions called by it. You can change the ordering with the following keyboard shortcuts:\n\n- t (default): Sort by total memory\n\n- o: Sort by own memory\n\n- a: Sort by allocation count\n\nIn most terminals you can also click the \"Sort by Total\", \"Sort by Own\", and \"Sort by Allocations\" buttons on the footer.\n\nThe sorted column's heading is underlined.\n\n## Viewing different threads\n\nBy default, the live command will present the main thread of the program. You can look at different threads of the program by pressing the greater than and less than keys, `\u003c` and `\u003e`. In most terminals you can also click the \"Previous Thread\" and \"Next Thread\" buttons on the footer.\n\n\u003cimg src=\"https://github.com/bloomberg/memray/blob/main/docs/_static/images/live_different_thread.png?raw=true\" align=\"center\"/\u003e\n\n# API\n\nIn addition to tracking Python processes from a CLI using `memray run`, it is also possible to programmatically enable tracking within a running Python program.\n\n```py\nimport memray\n\nwith memray.Tracker(\"output_file.bin\"):\n    print(\"Allocations will be tracked until the with block ends\")\n```\n\nFor details, see the [API documentation](https://bloomberg.github.io/memray/api.html).\n\n# License\n\nMemray is Apache-2.0 licensed, as found in the [LICENSE](LICENSE) file.\n\n# Code of Conduct\n\n- [Code of Conduct](https://github.com/bloomberg/.github/blob/main/CODE_OF_CONDUCT.md)\n\nThis project has adopted a Code of Conduct. If you have any concerns about the Code, or behavior that you have experienced in the project, please contact us at opensource@bloomberg.net.\n\n# Security Policy\n\n- [Security Policy](https://github.com/bloomberg/memray/security/policy)\n\nIf you believe you have identified a security vulnerability in this project, please send an email to the project team at opensource@bloomberg.net, detailing the suspected issue and any methods you've found to reproduce it.\n\nPlease do NOT open an issue in the GitHub repository, as we'd prefer to keep vulnerability reports private until we've had an opportunity to review and address them.\n\n# Contributing\n\nWe welcome your contributions to help us improve and extend this project!\n\nBelow you will find some basic steps required to be able to contribute to the project. If you have any questions about this process or any other aspect of contributing to a Bloomberg open source project, feel free to send an email to opensource@bloomberg.net and we'll get your questions answered as quickly as we can.\n\n## Contribution Licensing\n\nSince this project is distributed under the terms of an [open source license](LICENSE), contributions that\nyou make are licensed under the same terms. In order for us to be able to accept your contributions,\nwe will need explicit confirmation from you that you are able and willing to provide them under\nthese terms, and the mechanism we use to do this is called a Developer's Certificate of Origin\n[(DCO)](https://github.com/bloomberg/.github/blob/main/DCO.md). This is very similar to the process\nused by the Linux kernel, Samba, and many other major open source projects.\n\nTo participate under these terms, all that you must do is include a line like the following as the\nlast line of the commit message for each commit in your contribution:\n\n    Signed-Off-By: Random J. Developer \u003crandom@developer.example.org\u003e\n\nThe simplest way to accomplish this is to add `-s` or `--signoff` to your `git commit` command.\n\nYou must use your real name (sorry, no pseudonyms, and no anonymous contributions).\n\n## Steps\n\n- Create an Issue, select 'Feature Request', and explain the proposed change.\n- Follow the guidelines in the issue template presented to you.\n- Submit the Issue.\n- Submit a Pull Request and link it to the Issue by including \"#\u003cissue number\u003e\" in the Pull Request summary.\n","funding_links":[],"categories":["Python","Library","Profiling","Basic Components","Python 程序","Benchmarking","Papers and books you must Read (P\u0026BUMR)","语言资源库","System Monitoring \u0026 Profiling","Profilers"],"sub_categories":["5. Miscellaneous","Python Profilers","网络服务_其他","Typehint","컴퓨터 공학 내용 ( 계량과, 계산경제 위해서 공부했던 자료들)","python"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbloomberg%2Fmemray","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbloomberg%2Fmemray","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbloomberg%2Fmemray/lists"}