.svg){kind=icon}
Version
- GraalVM for JDK 23 (Latest)
- GraalVM for JDK 24 (Early Access)
- GraalVM for JDK 21
- GraalVM for JDK 17
- Archives
- Dev Build
Tooling Support for Python
Debugging #
GraalPy provides the standard Python debugger pdb.
Refer to the official PDB documentation for usage.
The built-in breakpoint() function uses pdb by default.
GraalPy also comes with built-in support for graphical debugging through Chrome’s developer tools.
To enable the debugger, pass the --inspect command-line option.
You can inspect variables, set watch expressions, interactively evaluate code snippets, and so on.
- Run a Python script using the command-line option
--inspect:graalpy --inspect my_script.py - You should see output similar to:
Debugger listening on ws://127.0.0.1:9229/VrhCaY7wR5tIqy2zLsdFr3f7ixY3QB6kVQ0S54_SOMo For help, see: https://www.graalvm.org/tools/chrome-debugger E.g. in Chrome open: devtools://devtools/bundled/js_app.html?ws=127.0.0.1:9229/VrhCaY7wR5tIqy2zLsdFr3f7ixY3QB6kVQ0S54_SOMo -
Open your Chrome browser and enter the URL provided. Now you can inspect the stack, variables, evaluate variables, and selected expressions in a tooltip, and so on. For example:
Profiling #
GraalPy provides three main profiling capabilities: a CPU sampler, a CPU tracer, and a memory tracer.
These are described below. (For details, use the graalpy --help:tools command.)
CPU Sampler #
Use the --cpusampler command-line option to take a CPU sample. For example:
graalpy --cpusampler my_script.py
You should see output similar to:
CPU Sampler Output (Click to expand)
--------------------------------------------------------------------------------------------------------------------------------------------------------------
Sampling Histogram. Recorded 564 samples with period 10ms. Missed 235 samples.
Self Time: Time spent on the top of the stack.
Total Time: Time spent somewhere on the stack.
--------------------------------------------------------------------------------------------------------------------------------------------------------------
Thread[main,5,main]
Name || Total Time || Self Time || Location
--------------------------------------------------------------------------------------------------------------------------------------------------------------
parse_starttag || 1090ms 19.3% || 570ms 10.1% || <install-dir>/lib/python3.10/html/parser.py~300-347:11658-13539
match || 190ms 3.4% || 190ms 3.4% || <venv-dir>/lib/python3.10/site-packages/soupsieve/css_parser.py~320-323:9862-10026
_replace_cdata_list_attribute_values || 190ms 3.4% || 190ms 3.4% || <venv-dir>/lib/python3.10/site-packages/bs4/builder/__init__.py~295-331:11245-13031
goahead || 1430ms 25.4% || 150ms 2.7% || <install-dir>/lib/python3.10/html/parser.py~133-250:4711-9678
check_for_whole_start_tag || 130ms 2.3% || 130ms 2.3% || <install-dir>/lib/python3.10/html/parser.py~351-382:13647-14758
<module> || 800ms 14.2% || 130ms 2.3% || <venv-dir>/lib/python3.10/site-packages/soupsieve/css_parser.py~1-1296:0-47061
...
--------------------------------------------------------------------------------------------------------------------------------------------------------------
CPU Tracer #
Use the --cputracer --cputracer.TraceStatements command-line options to trace CPU usage. For example:
graalpy --cputracer --cputracer.TraceStatements my_script.py
You should see output similar to:
CPU Tracer Output (Click to Expand)
--------------------------------------------------------------------------------------------------------------------
Tracing Histogram. Counted a total of 1135 element executions.
Total Count: Number of times the element was executed and percentage of total executions.
Interpreted Count: Number of times the element was interpreted and percentage of total executions of this element.
Compiled Count: Number of times the compiled element was executed and percentage of total executions of this element.
--------------------------------------------------------------------------------------------------------------------
Name | Total Count | Interpreted Count | Compiled Count | Location
--------------------------------------------------------------------------------------------------------------------
get_newfunc_typeid | 110 9.7% | 110 100.0% | 0 0.0% | capi.c~596:0
PyTruffle_PopulateType | 110 9.7% | 110 100.0% | 0 0.0% | capi.c~721:0
PyTruffle_AllocMemory | 86 7.6% | 86 100.0% | 0 0.0% | obmalloc.c~77:0
PyTruffle_AllocateType | 66 5.8% | 66 100.0% | 0 0.0% | capi.c~874:0
PyMem_RawMalloc | 66 5.8% | 66 100.0% | 0 0.0% | obmalloc.c~170:0
initialize_type_structure | 50 4.4% | 50 100.0% | 0 0.0% | capi.c~181:0
_Py_TYPE | 45 4.0% | 45 100.0% | 0 0.0% | object_shared.c~55:0
PyType_GetFlags | 41 3.6% | 41 100.0% | 0 0.0% | typeobject_shared.c~44:0
get_tp_name | 37 3.3% | 37 100.0% | 0 0.0% | capi.c~507:0
...
--------------------------------------------------------------------------------------------------------------------
Memory Tracer
Use the --memtracer --memtracer.TraceStatements command-line options to trace memory usage. For example:
graalpy --experimental-options --memtracer --memtracer.TraceStatements my_script.py
You should see output similar to:
Memory Tracer Output (Click to Expand)
----------------------------------------------------------------------------
Location Histogram with Allocation Counts. Recorded a total of 565 allocations.
Total Count: Number of allocations during the execution of this element.
Self Count: Number of allocations in this element alone (excluding sub calls).
----------------------------------------------------------------------------
Name | Self Count | Total Count | Location
----------------------------------------------------------------------------
PyTruffle_PopulateType | 440 77.9% | 440 77.9% | capi.c~721:0
PyType_Ready | 61 10.8% | 68 12.0% | typeobject.c~463:0
_PyObject_MakeTpCall | 20 3.5% | 24 4.2% | object.c~155:0
PyUnicode_FromString | 11 1.9% | 11 1.9% | capi.c~2161:0
PyErr_NewException | 11 1.9% | 11 1.9% | capi.c~1537:0
_PyUnicode_AsASCIIString | 6 1.1% | 6 1.1% | capi.c~2281:0
PyDict_New | 4 0.7% | 4 0.7% | capi.c~1505:0
PyTuple_New | 4 0.7% | 4 0.7% | capi.c~2097:0
PyUnicode_FromStringAndSize | 3 0.5% | 3 0.5% | unicodeobject.c~171:0
...
----------------------------------------------------------------------------
Coverage #
GraalPy provides its own implementation of the Coverage.py tool to measure code coverage of Python programs.
Enable it using the --coverage command-line option, as shown below.
(For details, use the graalpy --help:tools command.)
graalpy --coverage my_script.py
You should see output similar to:
CPU Sampler Output (Click to expand)
------------------------------------------------------------------------------------------------------------------------------------------------
Code coverage histogram.
Shows what percent of each element was covered during execution
------------------------------------------------------------------------------------------------------------------------------------------------
Path | Statements | Lines | Roots
------------------------------------------------------------------------------------------------------------------------------------------------
<venv-dir>/lib/python3.10/site-packages/_distutils_hack/__init__.py | 0.00% | 0.00% | 0.00%
<venv-dir>/lib/python3.10/site-packages/bs4/__init__.py | 56.10% | 56.14% | 55.26%
<venv-dir>/lib/python3.10/site-packages/bs4/builder/__init__.py | 79.12% | 78.84% | 50.00%
<venv-dir>/lib/python3.10/site-packages/bs4/builder/_html5lib.py | 2.41% | 2.46% | 2.38%
<venv-dir>/lib/python3.10/site-packages/bs4/builder/_htmlparser.py | 69.08% | 68.67% | 83.33%
<venv-dir>/lib/python3.10/site-packages/bs4/builder/_lxml.py | 3.72% | 3.78% | 4.00%
<venv-dir>/lib/python3.10/site-packages/bs4/css.py | 32.73% | 31.48% | 15.38%
<venv-dir>/lib/python3.10/site-packages/bs4/dammit.py | 65.46% | 65.29% | 24.14%
<venv-dir>/lib/python3.10/site-packages/bs4/element.py | 44.15% | 43.13% | 31.08%
<venv-dir>/lib/python3.10/site-packages/bs4/formatter.py | 73.49% | 74.36% | 66.67%
<venv-dir>/lib/python3.10/site-packages/certifi/__init__.py | 100.00% | 100.00% | 100.00%
<venv-dir>/lib/python3.10/site-packages/certifi/core.py | 33.33% | 33.33% | 25.00%
<venv-dir>/lib/python3.10/site-packages/charset_normalizer/__init__.py | 100.00% | 100.00% | 100.00%
<venv-dir>/lib/python3.10/site-packages/charset_normalizer/api.py | 11.87% | 11.94% | 16.67%
<venv-dir>/lib/python3.10/site-packages/charset_normalizer/assets/__init__.py | 100.00% | 100.00% | 100.00%
<venv-dir>/lib/python3.10/site-packages/charset_normalizer/cd.py | 12.81% | 13.54% | 4.35%
<venv-dir>/lib/python3.10/site-packages/charset_normalizer/constant.py | 100.00% | 100.00% | 100.00%
<venv-dir>/lib/python3.10/site-packages/charset_normalizer/legacy.py | 25.00% | 25.00% | 50.00%
<venv-dir>/lib/python3.10/site-packages/charset_normalizer/md.py | 22.05% | 20.37% | 17.24%
<venv-dir>/lib/python3.10/site-packages/charset_normalizer/models.py | 38.46% | 38.50% | 9.30%
<venv-dir>/lib/python3.10/site-packages/charset_normalizer/utils.py | 26.79% | 26.89% | 3.33%
<venv-dir>/lib/python3.10/site-packages/charset_normalizer/version.py | 100.00% | 100.00% | 100.00%
<venv-dir>/lib/python3.10/site-packages/idna/__init__.py | 100.00% | 100.00% | 100.00%
<install-dir>/lib/python3.10/collections/abc.py | 100.00% | 100.00% | 100.00%
<install-dir>/lib/python3.10/contextlib.py | 40.80% | 37.99% | 31.71%
<install-dir>/lib/python3.10/copy.py | 36.36% | 36.41% | 21.43%
<install-dir>/lib/python3.10/copyreg.py | 3.20% | 3.20% | 7.69%
<install-dir>/lib/python3.10/csv.py | 25.17% | 23.91% | 25.00%
<install-dir>/lib/python3.10/datetime.py | 30.32% | 30.01% | 14.74%
<install-dir>/lib/python3.10/email/__init__.py | 42.86% | 42.86% | 20.00%
<install-dir>/lib/python3.10/email/_encoded_words.py | 35.11% | 34.44% | 14.29%
<install-dir>/lib/python3.10/email/_parseaddr.py | 12.64% | 12.15% | 10.71%
<install-dir>/lib/python3.10/email/_policybase.py | 55.22% | 54.69% | 39.29%
<install-dir>/lib/python3.10/email/base64mime.py | 35.00% | 35.00% | 20.00%
<install-dir>/lib/python3.10/typing.py | 49.86% | 48.93% | 34.60%
<install-dir>/lib/python3.10/urllib/__init__.py | 100.00% | 100.00% | 100.00%
<install-dir>/lib/python3.10/warnings.py | 21.29% | 20.77% | 25.00%
<install-dir>/lib/python3.10/weakref.py | 37.93% | 36.78% | 23.68%
<install-dir>/lib/python3.10/zipfile.py | 17.86% | 17.23% | 11.03%
<src-dir>/my_script.py | 100.00% | 100.00% | 100.00%
------------------------------------------------------------------------------------------------------------------------------------------------
Trace #
The standard Python trace module is also provided.
Note: This works in the same way as CPython. The programmatic API also works, with some limitations: it does not currently track calls, only line counts and called functions.
For example, the command
graalpy -m trace -c -s text_styler.py Welcome to GraalPy!
Give example output
CPU Sampler Output (Click to expand)
_ __ __ __
| | / /__ / /________ ____ ___ ___ / /_____
| | /| / / _ \/ / ___/ __ \/ __ `__ \/ _ \ / __/ __ \
| |/ |/ / __/ / /__/ /_/ / / / / / / __/ / /_/ /_/ /
|__/|__/\___/_/\___/\____/_/ /_/ /_/\___/ \__/\____/
______ ______ __
/ ____/________ _____ _/ / __ \__ __/ /
/ / __/ ___/ __ `/ __ `/ / /_/ / / / / /
/ /_/ / / / /_/ / /_/ / / ____/ /_/ /_/
\____/_/ \__,_/\__,_/_/_/ \__, (_)
/____/
lines cov% module (path)
9 100% __about__ (<venv-dir>/lib/python3.10/site-packages/pkg_resources/_vendor/packaging/__about__.py)
51 100% __future__ (<install-dir>/lib/python3.10/__future__.py)
1 100% __init__ (<venv-dir>/lib/python3.10/site-packages/pyfiglet/fonts/__init__.py)
27 100% _adapters (<install-dir>/lib/python3.10/importlib/_adapters.py)
25 100% _common (<install-dir>/lib/python3.10/importlib/_common.py)
44 100% _manylinux (<venv-dir>/lib/python3.10/site-packages/pkg_resources/_vendor/packaging/_manylinux.py)
20 100% _musllinux (<venv-dir>/lib/python3.10/site-packages/pkg_resources/_vendor/packaging/_musllinux.py)
66 100% _osx_support (<install-dir>/lib/python3.10/_osx_support.py)
43 100% _parseaddr (<install-dir>/lib/python3.10/email/_parseaddr.py)
62 100% _policybase (<install-dir>/lib/python3.10/email/_policybase.py)
20 100% _structures (<venv-dir>/lib/python3.10/site-packages/pkg_resources/_vendor/packaging/_structures.py)
105 100% abc (<install-dir>/lib/python3.10/importlib/abc.py)
18 100% actions (<venv-dir>/lib/python3.10/site-packages/pkg_resources/_vendor/pyparsing/actions.py)
41 100% appdirs (<venv-dir>/lib/python3.10/site-packages/pkg_resources/_vendor/appdirs.py)
59 100% base64 (<install-dir>/lib/python3.10/base64.py)
14 100% base64mime (<install-dir>/lib/python3.10/email/base64mime.py)
11 100% bisect (<install-dir>/lib/python3.10/bisect.py)
124 100% calendar (<install-dir>/lib/python3.10/calendar.py)
94 100% charset (<install-dir>/lib/python3.10/email/charset.py)
122 100% common (<venv-dir>/lib/python3.10/site-packages/pkg_resources/_vendor/pyparsing/common.py)
40 100% context (<venv-dir>/lib/python3.10/site-packages/pkg_resources/_vendor/jaraco/context.py)
3 100% contextlib (<install-dir>/lib/python3.10/contextlib.py)
91 100% copy (<install-dir>/lib/python3.10/copy.py)
1497 100% core (<venv-dir>/lib/python3.10/site-packages/pkg_resources/_vendor/pyparsing/core.py)
108 100% dataclasses (<install-dir>/lib/python3.10/dataclasses.py)
31 100% datetime (<install-dir>/lib/python3.10/datetime.py)
9 100% encoders (<install-dir>/lib/python3.10/email/encoders.py)
2493 100% entities (<install-dir>/lib/python3.10/html/entities.py)
58 100% errors (<install-dir>/lib/python3.10/email/errors.py)
49 100% exceptions (<venv-dir>/lib/python3.10/site-packages/pkg_resources/_vendor/pyparsing/exceptions.py)
5 100% expat (<install-dir>/lib/python3.10/xml/parsers/expat.py)
41 100% feedparser (<install-dir>/lib/python3.10/email/feedparser.py)
45 100% functools (<venv-dir>/lib/python3.10/site-packages/pkg_resources/_vendor/jaraco/functools.py)
69 100% gettext (<install-dir>/lib/python3.10/gettext.py)
56 100% header (<install-dir>/lib/python3.10/email/header.py)
162 100% helpers (<venv-dir>/lib/python3.10/site-packages/pkg_resources/_vendor/pyparsing/helpers.py)
1 100% inspect (<install-dir>/lib/python3.10/inspect.py)
47 100% linecache (<install-dir>/lib/python3.10/linecache.py)
95 100% markers (<venv-dir>/lib/python3.10/site-packages/pkg_resources/_vendor/packaging/markers.py)
192 100% more (<venv-dir>/lib/python3.10/site-packages/pkg_resources/_vendor/more_itertools/more.py)
204 100% optparse (<install-dir>/lib/python3.10/optparse.py)
14 100% os (<install-dir>/lib/python3.10/os.py)
167 100% parse (<install-dir>/lib/python3.10/urllib/parse.py)
19 100% parser (<install-dir>/lib/python3.10/email/parser.py)
242 100% pathlib (<install-dir>/lib/python3.10/pathlib.py)
66 100% pkgutil (<install-dir>/lib/python3.10/pkgutil.py)
137 100% platform (<install-dir>/lib/python3.10/platform.py)
102 100% plistlib (<install-dir>/lib/python3.10/plistlib.py)
79 100% pprint (<install-dir>/lib/python3.10/pprint.py)
54 100% queue (<install-dir>/lib/python3.10/queue.py)
21 100% quopri (<install-dir>/lib/python3.10/quopri.py)
32 100% quoprimime (<install-dir>/lib/python3.10/email/quoprimime.py)
101 100% random (<install-dir>/lib/python3.10/random.py)
43 100% recipes (<venv-dir>/lib/python3.10/site-packages/pkg_resources/_vendor/more_itertools/recipes.py)
51 100% requirements (<venv-dir>/lib/python3.10/site-packages/pkg_resources/_vendor/packaging/requirements.py)
46 100% resources (<install-dir>/lib/python3.10/importlib/resources.py)
155 100% results (<venv-dir>/lib/python3.10/site-packages/pkg_resources/_vendor/pyparsing/results.py)
79 100% selectors (<install-dir>/lib/python3.10/selectors.py)
30 100% signal (<install-dir>/lib/python3.10/signal.py)
94 100% socket (<install-dir>/lib/python3.10/socket.py)
143 100% specifiers (<venv-dir>/lib/python3.10/site-packages/pkg_resources/_vendor/packaging/specifiers.py)
50 100% string (<install-dir>/lib/python3.10/string.py)
118 100% subprocess (<install-dir>/lib/python3.10/subprocess.py)
96 100% sysconfig (<install-dir>/lib/python3.10/sysconfig.py)
67 100% tags (<venv-dir>/lib/python3.10/site-packages/pkg_resources/_vendor/packaging/tags.py)
119 100% tempfile (<install-dir>/lib/python3.10/tempfile.py)
35 100% testing (<venv-dir>/lib/python3.10/site-packages/pkg_resources/_vendor/pyparsing/testing.py)
7 100% text_styler (<src-dir>/text_styler.py)
51 100% textwrap (<install-dir>/lib/python3.10/textwrap.py)
2 100% threading (<install-dir>/lib/python3.10/threading.py)
32 100% tokenize (<install-dir>/lib/python3.10/tokenize.py)
43 100% traceback (<install-dir>/lib/python3.10/traceback.py)
703 100% typing (<install-dir>/lib/python3.10/typing.py)
238 100% unicode (<venv-dir>/lib/python3.10/site-packages/pkg_resources/_vendor/pyparsing/unicode.py)
76 100% util (<venv-dir>/lib/python3.10/site-packages/pkg_resources/_vendor/pyparsing/util.py)
20 100% utils (<venv-dir>/lib/python3.10/site-packages/pkg_resources/_vendor/packaging/utils.py)
1 100% version (<venv-dir>/lib/python3.10/site-packages/pyfiglet/version.py)
16 100% warnings (<install-dir>/lib/python3.10/warnings.py)
127 100% weakref (<install-dir>/lib/python3.10/weakref.py)
432 100% zipfile (<install-dir>/lib/python3.10/zipfile.py)
Using PyCharm with GraalPy #
You can use GraalPy in PyCharm to create a virtual environment, install packages, and develop and run your Python application.
-
Install
graalpy. (For more information, see Installing GraalPy.) -
Install PyCharm. (For more information, see Install PyCharm.)
-
Create, or open, a Python project. (For more information, see Create a Python project, or Open, reopen, and close projects, respectively.)
-
Create a new venv virtual environment for your Python project. (For more information, see Create a virtualenv environment.)
-
Install packages by following the PyCharm instructions. (For more information, see Install, uninstall, and upgrade packages.)
-
Use the PyCharm menu items to run your Python application. Alternatively, use the terminal emulator to run the
graalpycommand.
Using Visual Studio Code with GraalPy #
You can use GraalPy in Visual Studio (VS) Code to create a virtual environment, install packages, and develop and run your Python application.
-
Install
graalpy. (For more information, see Installing GraalPy.) -
Install VS Code and the Python Extension, following the instructions here: Install Visual Studio Code and the Python Extension.
-
Create, or open, a Python file.
-
Create a new venv virtual environment for your Python project. (For more information, see Creating environments.)
-
Install packages by following the VS Code instructions. (For more information, see Install and use packages.)
-
Use the VS Code menu items to run your Python application. (For more information, see Run Hello World.) Alternatively, use a VS Code terminal emulator to run the
graalpycommand. -
You cannot use VS Code to debug your Python application. Instead, open a VS Code terminal emulator and follow these instructions: Debugging a Python Application.