{"id":13477944,"url":"https://github.com/pyutils/line_profiler","last_synced_at":"2025-05-08T23:34:51.810Z","repository":{"id":37390868,"uuid":"227227463","full_name":"pyutils/line_profiler","owner":"pyutils","description":"Line-by-line profiling for Python","archived":false,"fork":false,"pushed_at":"2025-05-04T23:06:48.000Z","size":2166,"stargazers_count":2946,"open_issues_count":55,"forks_count":129,"subscribers_count":14,"default_branch":"main","last_synced_at":"2025-05-08T22:19:19.138Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pyutils.png","metadata":{"files":{"readme":"README.rst","changelog":"CHANGELOG.rst","contributing":null,"funding":null,"license":"LICENSE.txt","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,"zenodo":null}},"created_at":"2019-12-10T22:26:33.000Z","updated_at":"2025-05-08T06:58:51.000Z","dependencies_parsed_at":"2023-02-11T22:45:41.118Z","dependency_job_id":"fffb2b1b-09c7-4e77-9fb1-1536edcc19d2","html_url":"https://github.com/pyutils/line_profiler","commit_stats":{"total_commits":251,"total_committers":43,"mean_commits":5.837209302325581,"dds":0.6932270916334662,"last_synced_commit":"d3de63ccf4e5b689cb4e0275916b57e8bc4a7624"},"previous_names":[],"tags_count":24,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pyutils%2Fline_profiler","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pyutils%2Fline_profiler/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pyutils%2Fline_profiler/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pyutils%2Fline_profiler/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pyutils","download_url":"https://codeload.github.com/pyutils/line_profiler/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253155128,"owners_count":21862637,"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":[],"created_at":"2024-07-31T16:01:50.127Z","updated_at":"2025-05-08T23:34:51.785Z","avatar_url":"https://github.com/pyutils.png","language":"Python","readme":"line_profiler and kernprof\n--------------------------\n\n|Pypi| |ReadTheDocs| |Downloads| |CircleCI| |GithubActions| |Codecov|\n\n\nThis is the official ``line_profiler`` repository. The most recent version of\n`line-profiler \u003chttps://pypi.org/project/line_profiler/\u003e`_ on pypi points to\nthis repo.\nThe original `line_profiler \u003chttps://github.com/rkern/line_profiler/\u003e`_ package\nby `@rkern \u003chttps://github.com/rkern/\u003e`_ is unmaintained.\nThis fork is the official continuation of the project.\n\n+---------------+--------------------------------------------+\n| Github        | https://github.com/pyutils/line_profiler   |\n+---------------+--------------------------------------------+\n| Pypi          | https://pypi.org/project/line_profiler     |\n+---------------+--------------------------------------------+\n| ReadTheDocs   | https://kernprof.readthedocs.io/en/latest/ |\n+---------------+--------------------------------------------+\n\n----\n\n\n``line_profiler`` is a module for doing line-by-line profiling of functions.\nkernprof is a convenient script for running either ``line_profiler`` or the Python\nstandard library's cProfile or profile modules, depending on what is available.\n\nThey are available under a `BSD license`_.\n\n.. _BSD license: https://raw.githubusercontent.com/pyutils/line_profiler/master/LICENSE.txt\n\n.. contents::\n\n\nQuick Start (Modern)\n====================\n\nThis guide is for versions of line profiler starting at ``4.1.0``.\n\nTo profile a python script:\n\n* Install line_profiler: ``pip install line_profiler``.\n\n* In the relevant file(s), import line profiler and decorate function(s) you\n  want to profile with ``@line_profiler.profile``.\n\n* Set the environment variable ``LINE_PROFILE=1`` and run your script as normal.\n  When the script ends a summary of profile results, files written to disk, and\n  instructions for inspecting details will be written to stdout.\n\nFor more details and a short tutorial see `Line Profiler Basic Usage \u003chttps://kernprof.readthedocs.io/en/latest/#line-profiler-basic-usage\u003e`_.\n\n\nQuick Start (Legacy)\n====================\n\nThis section is the original quick-start guide, and may eventually be removed\nfrom the README. This will work with current and older (pre ``4.1.0``) versions\nof line profiler.\n\nTo profile a python script:\n\n* Install line_profiler: ``pip install line_profiler``.\n\n* Decorate function(s) you want to profile with @profile. The decorator will be made automatically available on run.\n\n* Run ``kernprof -lv script_to_profile.py``.\n\nInstallation\n============\n\nReleases of ``line_profiler`` can be installed using pip::\n\n    $ pip install line_profiler\n\nInstallation while ensuring a compatible IPython version can also be installed using pip::\n\n    $ pip install line_profiler[ipython]\n\nTo check out the development sources, you can use Git_::\n\n    $ git clone https://github.com/pyutils/line_profiler.git\n\nYou may also download source tarballs of any snapshot from that URL.\n\nSource releases will require a C compiler in order to build `line_profiler`.\nIn addition, git checkouts will also require Cython. Source releases\non PyPI should contain the pregenerated C sources, so Cython should not be\nrequired in that case.\n\n``kernprof`` is a single-file pure Python script and does not require\na compiler.  If you wish to use it to run cProfile and not line-by-line\nprofiling, you may copy it to a directory on your ``PATH`` manually and avoid\ntrying to build any C extensions.\n\nAs of 2021-06-04 Linux (x86_64 and i686), OSX (10_9_x86_64), and Win32 (win32,\nand amd64) binaries are available on pypi.\n\nThe last version of line profiler to support Python 2.7 was 3.1.0 and the last\nversion to support Python 3.5 was 3.3.1.\n\n.. _git: http://git-scm.com/\n.. _Cython: http://www.cython.org\n.. _build and install: http://docs.python.org/install/index.html\n\n\nline_profiler\n=============\n\nThe current profiling tools supported in Python only time\nfunction calls. This is a good first step for locating hotspots in one's program\nand is frequently all one needs to do to optimize the program. However,\nsometimes the cause of the hotspot is actually a single line in the function,\nand that line may not be obvious from just reading the source code. These cases\nare particularly frequent in scientific computing. Functions tend to be larger\n(sometimes because of legitimate algorithmic complexity, sometimes because the\nprogrammer is still trying to write FORTRAN code), and a single statement\nwithout function calls can trigger lots of computation when using libraries like\nnumpy. cProfile only times explicit function calls, not special methods called\nbecause of syntax. Consequently, a relatively slow numpy operation on large\narrays like this, ::\n\n    a[large_index_array] = some_other_large_array\n\nis a hotspot that never gets broken out by cProfile because there is no explicit\nfunction call in that statement.\n\nLineProfiler can be given functions to profile, and it will time the execution\nof each individual line inside those functions. In a typical workflow, one only\ncares about line timings of a few functions because wading through the results\nof timing every single line of code would be overwhelming. However, LineProfiler\ndoes need to be explicitly told what functions to profile. The easiest way to\nget started is to use the ``kernprof`` script. ::\n\n    $ kernprof -l script_to_profile.py\n\n``kernprof`` will create an instance of LineProfiler and insert it into the\n``__builtins__`` namespace with the name ``profile``. It has been written to be\nused as a decorator, so in your script, you decorate the functions you want\nto profile with @profile. ::\n\n    @profile\n    def slow_function(a, b, c):\n        ...\n\nThe default behavior of ``kernprof`` is to put the results into a binary file\nscript_to_profile.py.lprof . You can tell ``kernprof`` to immediately view the\nformatted results at the terminal with the [-v/--view] option. Otherwise, you\ncan view the results later like so::\n\n    $ python -m line_profiler script_to_profile.py.lprof\n\nFor example, here are the results of profiling a single function from\na decorated version of the pystone.py benchmark (the first two lines are output\nfrom ``pystone.py``, not ``kernprof``)::\n\n    Pystone(1.1) time for 50000 passes = 2.48\n    This machine benchmarks at 20161.3 pystones/second\n    Wrote profile results to pystone.py.lprof\n    Timer unit: 1e-06 s\n\n    File: pystone.py\n    Function: Proc2 at line 149\n    Total time: 0.606656 s\n\n    Line #      Hits         Time  Per Hit   % Time  Line Contents\n    ==============================================================\n       149                                           @profile\n       150                                           def Proc2(IntParIO):\n       151     50000        82003      1.6     13.5      IntLoc = IntParIO + 10\n       152     50000        63162      1.3     10.4      while 1:\n       153     50000        69065      1.4     11.4          if Char1Glob == 'A':\n       154     50000        66354      1.3     10.9              IntLoc = IntLoc - 1\n       155     50000        67263      1.3     11.1              IntParIO = IntLoc - IntGlob\n       156     50000        65494      1.3     10.8              EnumLoc = Ident1\n       157     50000        68001      1.4     11.2          if EnumLoc == Ident1:\n       158     50000        63739      1.3     10.5              break\n       159     50000        61575      1.2     10.1      return IntParIO\n\n\nThe source code of the function is printed with the timing information for each\nline. There are six columns of information.\n\n    * Line #: The line number in the file.\n\n    * Hits: The number of times that line was executed.\n\n    * Time: The total amount of time spent executing the line in the timer's\n      units. In the header information before the tables, you will see a line\n      \"Timer unit:\" giving the conversion factor to seconds. It may be different\n      on different systems.\n\n    * Per Hit: The average amount of time spent executing the line once in the\n      timer's units.\n\n    * % Time: The percentage of time spent on that line relative to the total\n      amount of recorded time spent in the function.\n\n    * Line Contents: The actual source code. Note that this is always read from\n      disk when the formatted results are viewed, *not* when the code was\n      executed. If you have edited the file in the meantime, the lines will not\n      match up, and the formatter may not even be able to locate the function\n      for display.\n\nIf you are using IPython, there is an implementation of an %lprun magic command\nwhich will let you specify functions to profile and a statement to execute. It\nwill also add its LineProfiler instance into the __builtins__, but typically,\nyou would not use it like that.\n\nFor IPython 0.11+, you can install it by editing the IPython configuration file\n``~/.ipython/profile_default/ipython_config.py`` to add the ``'line_profiler'``\nitem to the extensions list::\n\n    c.TerminalIPythonApp.extensions = [\n        'line_profiler',\n    ]\n\nOr explicitly call::\n\n    %load_ext line_profiler\n\nTo get usage help for %lprun, use the standard IPython help mechanism::\n\n    In [1]: %lprun?\n\nThese two methods are expected to be the most frequent user-level ways of using\nLineProfiler and will usually be the easiest. However, if you are building other\ntools with LineProfiler, you will need to use the API. There are two ways to\ninform LineProfiler of functions to profile: you can pass them as arguments to\nthe constructor or use the ``add_function(f)`` method after instantiation. ::\n\n    profile = LineProfiler(f, g)\n    profile.add_function(h)\n\nLineProfiler has the same ``run()``, ``runctx()``, and ``runcall()`` methods as\ncProfile.Profile as well as ``enable()`` and ``disable()``. It should be noted,\nthough, that ``enable()`` and ``disable()`` are not entirely safe when nested.\nNesting is common when using LineProfiler as a decorator. In order to support\nnesting, use ``enable_by_count()`` and ``disable_by_count()``. These functions will\nincrement and decrement a counter and only actually enable or disable the\nprofiler when the count transitions from or to 0.\n\nAfter profiling, the ``dump_stats(filename)`` method will pickle the results out\nto the given file. ``print_stats([stream])`` will print the formatted results to\nsys.stdout or whatever stream you specify. ``get_stats()`` will return LineStats\nobject, which just holds two attributes: a dictionary containing the results and\nthe timer unit.\n\n\nkernprof\n========\n\n``kernprof`` also works with cProfile, its third-party incarnation lsprof, or the\npure-Python profile module depending on what is available. It has a few main\nfeatures:\n\n    * Encapsulation of profiling concerns. You do not have to modify your script\n      in order to initiate profiling and save the results. Unless if you want to\n      use the advanced __builtins__ features, of course.\n\n    * Robust script execution. Many scripts require things like __name__,\n      __file__, and sys.path to be set relative to it. A naive approach at\n      encapsulation would just use execfile(), but many scripts which rely on\n      that information will fail. kernprof will set those variables correctly\n      before executing the script.\n\n    * Easy executable location. If you are profiling an application installed on\n      your PATH, you can just give the name of the executable. If kernprof does\n      not find the given script in the current directory, it will search your\n      PATH for it.\n\n    * Inserting the profiler into __builtins__. Sometimes, you just want to\n      profile a small part of your code. With the [-b/--builtin] argument, the\n      Profiler will be instantiated and inserted into your __builtins__ with the\n      name \"profile\". Like LineProfiler, it may be used as a decorator, or\n      enabled/disabled with ``enable_by_count()`` and ``disable_by_count()``, or\n      even as a context manager with the \"with profile:\" statement.\n\n    * Pre-profiling setup. With the [-s/--setup] option, you can provide\n      a script which will be executed without profiling before executing the\n      main script. This is typically useful for cases where imports of large\n      libraries like wxPython or VTK are interfering with your results. If you\n      can modify your source code, the __builtins__ approach may be\n      easier.\n\nThe results of profile script_to_profile.py will be written to\nscript_to_profile.py.prof by default. It will be a typical marshalled file that\ncan be read with pstats.Stats(). They may be interactively viewed with the\ncommand::\n\n    $ python -m pstats script_to_profile.py.prof\n\n\nSuch files may also be viewed with graphical tools. A list of 3rd party tools\nbuilt on ``cProfile`` or ``line_profiler`` are as follows:\n\n* `pyprof2calltree \u003cpyprof2calltree_\u003e`_: converts profiling data to a format\n  that can be visualized using kcachegrind_ (linux only), wincachegrind_\n  (windows only, unmaintained), or  qcachegrind_.\n\n* `Line Profiler GUI \u003cqt_profiler_gui_\u003e`_: Qt GUI for line_profiler.\n\n* `SnakeViz \u003cSnakeViz_\u003e`_: A web viewer for Python profiling data.\n\n* `SnakeRunner \u003cSnakeRunner_\u003e`_: A fork of RunSnakeRun_, ported to Python 3.\n\n* `Pycharm plugin \u003cpycharm_line_profiler_plugin_\u003e`_: A PyCharm plugin for line_profiler.\n\n* `Spyder plugin \u003cspyder_line_profiler_plugin_\u003e`_: A plugin to run line_profiler from within the Spyder IDE.\n\n* `pprof \u003cweb_profiler_ui_\u003e`_: A render web report for ``line_profiler``.\n\n.. _qcachegrind: https://sourceforge.net/projects/qcachegrindwin/\n.. _kcachegrind: https://kcachegrind.github.io/html/Home.html\n.. _wincachegrind: https://github.com/ceefour/wincachegrind\n.. _pyprof2calltree: http://pypi.python.org/pypi/pyprof2calltree/\n.. _SnakeViz: https://github.com/jiffyclub/snakeviz/\n.. _SnakeRunner: https://github.com/venthur/snakerunner\n.. _RunSnakeRun: https://pypi.org/project/RunSnakeRun/\n.. _qt_profiler_gui: https://github.com/Nodd/lineprofilergui\n.. _pycharm_line_profiler_plugin: https://plugins.jetbrains.com/plugin/16536-line-profiler\n.. _spyder_line_profiler_plugin: https://github.com/spyder-ide/spyder-line-profiler\n.. _web_profiler_ui: https://github.com/mirecl/pprof\n\n\nRelated Work\n============\n\nCheck out these other Python profilers:\n\n* `Scalene \u003chttps://github.com/plasma-umass/scalene\u003e`_: A CPU+GPU+memory sampling based profiler.\n\n* `PyInstrument  \u003chttps://github.com/joerick/pyinstrument\u003e`_: A call stack profiler.\n\n* `Yappi \u003chttps://github.com/sumerc/yappi\u003e`_: A tracing profiler that is multithreading, asyncio and gevent aware.\n\n* `profile / cProfile \u003chttps://docs.python.org/3/library/profile.html\u003e`_: The builtin profile module.\n\n* `timeit \u003chttps://docs.python.org/3/library/timeit.html\u003e`_: The builtin timeit module for profiling single statements.\n\n* `timerit \u003chttps://github.com/Erotemic/timerit\u003e`_: A multi-statements alternative to the builtin ``timeit`` module.\n\nFrequently Asked Questions\n==========================\n\n* Why the name \"kernprof\"?\n\n    I didn't manage to come up with a meaningful name, so I named it after\n    myself.\n\n* The line-by-line timings don't add up when one profiled function calls\n  another. What's up with that?\n\n    Let's say you have function F() calling function G(), and you are using\n    LineProfiler on both. The total time reported for G() is less than the time\n    reported on the line in F() that calls G(). The reason is that I'm being\n    reasonably clever (and possibly too clever) in recording the times.\n    Basically, I try to prevent recording the time spent inside LineProfiler\n    doing all of the bookkeeping for each line. Each time Python's tracing\n    facility issues a line event (which happens just before a line actually gets\n    executed), LineProfiler will find two timestamps, one at the beginning\n    before it does anything (t_begin) and one as close to the end as possible\n    (t_end). Almost all of the overhead of LineProfiler's data structures\n    happens in between these two times.\n\n    When a line event comes in, LineProfiler finds the function it belongs to.\n    If it's the first line in the function, we record the line number and\n    *t_end* associated with the function. The next time we see a line event\n    belonging to that function, we take t_begin of the new event and subtract\n    the old t_end from it to find the amount of time spent in the old line. Then\n    we record the new t_end as the active line for this function. This way, we\n    are removing most of LineProfiler's overhead from the results. Well almost.\n    When one profiled function F calls another profiled function G, the line in\n    F that calls G basically records the total time spent executing the line,\n    which includes the time spent inside the profiler while inside G.\n\n    The first time this question was asked, the questioner had the G() function\n    call as part of a larger expression, and he wanted to try to estimate how\n    much time was being spent in the function as opposed to the rest of the\n    expression. My response was that, even if I could remove the effect, it\n    might still be misleading. G() might be called elsewhere, not just from the\n    relevant line in F(). The workaround would be to modify the code to split it\n    up into two lines, one which just assigns the result of G() to a temporary\n    variable and the other with the rest of the expression.\n\n    I am open to suggestions on how to make this more robust. Or simple\n    admonitions against trying to be clever.\n\n* Why do my list comprehensions have so many hits when I use the LineProfiler?\n\n    LineProfiler records the line with the list comprehension once for each\n    iteration of the list comprehension.\n\n* Why is kernprof distributed with line_profiler? It works with just cProfile,\n  right?\n\n    Partly because kernprof.py is essential to using line_profiler effectively,\n    but mostly because I'm lazy and don't want to maintain the overhead of two\n    projects for modules as small as these. However, kernprof.py is\n    a standalone, pure Python script that can be used to do function profiling\n    with just the Python standard library. You may grab it and install it by\n    itself without ``line_profiler``.\n\n* Do I need a C compiler to build ``line_profiler``? kernprof.py?\n\n    You do need a C compiler for line_profiler. kernprof.py is a pure Python\n    script and can be installed separately, though.\n\n* Do I need Cython to build ``line_profiler``?\n\n    Wheels for supported versions of Python are available on PyPI and support\n    linux, osx, and windows for x86-64 architectures. Linux additionally ships\n    with i686 wheels for manylinux and musllinux. If you have a different CPU\n    architecture, or an unsupported Python version, then you will need to build\n    from source.\n\n* What version of Python do I need?\n\n    Both ``line_profiler`` and ``kernprof`` have been tested with Python 3.6-3.11.\n    Older versions of ``line_profiler`` support older versions of Python.\n\n\nTo Do\n=====\n\ncProfile uses a neat \"rotating trees\" data structure to minimize the overhead of\nlooking up and recording entries. LineProfiler uses Python dictionaries and\nextension objects thanks to Cython. This mostly started out as a prototype that\nI wanted to play with as quickly as possible, so I passed on stealing the\nrotating trees for now. As usual, I got it working, and it seems to have\nacceptable performance, so I am much less motivated to use a different strategy\nnow. Maybe later. Contributions accepted!\n\n\nBugs and Such\n=============\n\nBugs and pull requested can be submitted on GitHub_.\n\n.. _GitHub: https://github.com/pyutils/line_profiler\n\n\nChanges\n=======\n\nSee `CHANGELOG`_.\n\n.. _CHANGELOG: CHANGELOG.rst\n\n\n.. |CircleCI| image:: https://circleci.com/gh/pyutils/line_profiler.svg?style=svg\n    :target: https://circleci.com/gh/pyutils/line_profiler\n.. |Travis| image:: https://img.shields.io/travis/pyutils/line_profiler/master.svg?label=Travis%20CI\n   :target: https://travis-ci.org/pyutils/line_profiler?branch=master\n.. |Appveyor| image:: https://ci.appveyor.com/api/projects/status/github/pyutils/line_profiler?branch=master\u0026svg=True\n   :target: https://ci.appveyor.com/project/pyutils/line_profiler/branch/master\n.. |Codecov| image:: https://codecov.io/github/pyutils/line_profiler/badge.svg?branch=master\u0026service=github\n   :target: https://codecov.io/github/pyutils/line_profiler?branch=master\n.. |Pypi| image:: https://img.shields.io/pypi/v/line_profiler.svg\n   :target: https://pypi.python.org/pypi/line_profiler\n.. |Downloads| image:: https://img.shields.io/pypi/dm/line_profiler.svg\n   :target: https://pypistats.org/packages/line-profiler\n.. |GithubActions| image:: https://github.com/pyutils/line_profiler/actions/workflows/tests.yml/badge.svg?branch=main\n   :target: https://github.com/pyutils/line_profiler/actions?query=branch%3Amain\n.. |ReadTheDocs| image:: https://readthedocs.org/projects/kernprof/badge/?version=latest\n    :target: http://kernprof.readthedocs.io/en/latest/\n","funding_links":[],"categories":["Python","System Monitoring \u0026 Profiling","Benchmarking","Python生态圈Dev\u0026Ops工具与服务","Python specific"],"sub_categories":["Typehint"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpyutils%2Fline_profiler","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpyutils%2Fline_profiler","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpyutils%2Fline_profiler/lists"}