{"id":17169801,"url":"https://github.com/naftulikay/heap-percent","last_synced_at":"2026-04-17T02:31:11.885Z","repository":{"id":142455440,"uuid":"94276077","full_name":"naftulikay/heap-percent","owner":"naftulikay","description":"Calculator for a heap size percentage based on the system RAM and a range.","archived":false,"fork":false,"pushed_at":"2018-02-12T21:21:57.000Z","size":17,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"develop","last_synced_at":"2026-04-04T00:39:04.524Z","etag":null,"topics":["jvm","maximum-heap-size","memory-management","python","python27","python3","python35","python36","ram"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/naftulikay.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-06-14T01:45:24.000Z","updated_at":"2017-06-14T20:19:12.000Z","dependencies_parsed_at":null,"dependency_job_id":"e7e855d8-41b4-43e0-ab4d-2528cda62b2a","html_url":"https://github.com/naftulikay/heap-percent","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/naftulikay/heap-percent","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/naftulikay%2Fheap-percent","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/naftulikay%2Fheap-percent/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/naftulikay%2Fheap-percent/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/naftulikay%2Fheap-percent/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/naftulikay","download_url":"https://codeload.github.com/naftulikay/heap-percent/tar.gz/refs/heads/develop","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/naftulikay%2Fheap-percent/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31912316,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-16T18:22:33.417Z","status":"online","status_checked_at":"2026-04-17T02:00:06.879Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["jvm","maximum-heap-size","memory-management","python","python27","python3","python35","python36","ram"],"created_at":"2024-10-14T23:27:24.138Z","updated_at":"2026-04-17T02:31:11.656Z","avatar_url":"https://github.com/naftulikay.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# heap-percent [![Build Status][svg-travis]][travis]\n\nA utility for calculating the maximum heap size by system RAM, an absolute minimum RAM needed, and a maximum heap size\nto not exceed. The algorithm in its entirety, operating on bytes, looks like this:\n\n```python\n@classmethod\ndef best_heap_size(cls, total_ram, percent, min_allowed_ram, max_allowed_ram):\n    # do math right; multiply total ram in bytes by the percentage (limited to 1-100) multiplied by 0.01 to shift\n    ideal_size = int(total_ram * float(max(1, min(100, percent)) * 0.01))\n\n    if min_allowed_ram \u003e= total_ram:\n        min_allowed_gb, total_ram_gb = (((Units.BYTE * min_allowed_ram) / (Units.GIBIBYTE * 1))).magnitude, \\\n            ((Units.BYTE * total_ram) / (Units.GIBIBYTE * 1)).magnitude\n        raise InsufficientRamException(\"System RAM ({:02.02f}GiB) is less than minimum allowed RAM ({:02.02f}GiB)\"\n            .format(total_ram_gb, min_allowed_gb))\n\n    return HeapSize(min(max(ideal_size, min_allowed_ram), max_allowed_ram))\n```\n\nEssentially, this allows to set a cap on the high heap size so as to avoid larger pointer memory space, allows to\nset a cap on minimum RAM that the application _must_ have, and allows specifying a percentage to determine how much\nof system RAM (capped at the max) should be dedicated to the heap of a given (typically JVM) process.\n\n## Usage\n\nCommand-line usage:\n\n```\nusage: heap-percent [-h] [--min MIN] [--max MAX] [-t TOTAL] -p PERCENT\n\ndelivers the calculated amount of ram to use for a process\n\noptional arguments:\n  -h, --help            show this help message and exit\n  --min MIN, --min-allowed-ram MIN\n                        The minimum allowed RAM for the process; defaults to\n                        2GiB, set to zero if you want it to run no matter\n                        what.\n  --max MAX, --max-allowed-ram MAX\n                        The maximum allowed RAM for the process; defaults to\n                        30GiB, set to a very high number if you don't care\n                        about maximum heap size, ie 100TiB.\n  -t TOTAL, --total TOTAL\n                        The total system RAM; will be detected if not set.\n  -p PERCENT, --percent PERCENT\n                        The RAM percentage to attempt to occupy.\n\nsizes may be integers in bytes, or may have the following case-insensitive\nsuffixes for size: b, k, kb, kib,m, mb, mib, g, gb, gib, t, tb, tib.\n```\n\nIf an impossible situation arises, the error will be logged to standard output and the process will exit with a return\ncode of 2. Basically, this can only happen in the following cases:\n\n 1. Your system RAM is less than your `--min` allowed RAM.\n 1. Your ideal heap size is less than your `--min` allowed RAM. This can happen when the total system RAM divided by\n    `--percent` is less than `--min` allowed RAM.\n\n### From the Trenches\n\nTry to occupy 90% of system RAM, with a minimum heap size of 5GiB.:\n\n```\n[vagrant@devel vagrant]$ bin/heap-percent --min 5GiB -p 90\nERROR: System RAM (0.97GiB) is less than minimum allowed RAM (5.00GiB)\n[vagrant@devel vagrant]$ echo $?\n2\n```\n\nTry to occupy 60% of specified total system RAM, being 64 GiB, with a minimum size of 2 GiB and a maximum size of 30\nGiB:\n\n```\n[vagrant@devel vagrant]$ bin/heap-percent --min 2GiB --max 30GiB --total 64GiB --percent 60\n30720m\n```\n\nThis can be used directly with `-Xms` and `-Xmx` to determine a flexible heap size based on the current environment.\n\n## Installation\n\nInstallation is best done using `pip` and a GitHub upstream due to PyPI's unreliability.\n\nUser install:\n\n```\npip install --user git+https://github.com/naftulikay/heap-percent\n```\n\nSystem install:\n\n```\nsudo pip install git+https://github.com/naftulikay/heap-percent\n```\n\nPin to a tag name:\n\n```\npip install --user git+https://github.com/naftulikay/heap-percent@v0.1.0\n```\n\n## License\n\nMIT, please see `./LICENSE`.\n\n\n [svg-travis]: https://travis-ci.org/naftulikay/heap-percent.svg?branch=develop\n [travis]: https://travis-ci.org/naftulikay/heap-percent\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnaftulikay%2Fheap-percent","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnaftulikay%2Fheap-percent","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnaftulikay%2Fheap-percent/lists"}