Skip to main content
https://raw.githubusercontent.com/lmacken/pyrasite/develop/docs/logo.png

pyrasite

https://github.com/lmacken/pyrasite/actions/workflows/ci.yml/badge.svg?branch=develop https://img.shields.io/pypi/v/pyrasite?style=flat

Tools for injecting arbitrary code into running Python processes.

homepage:

https://github.com/lmacken/pyrasite

documentation:

https://pyrasite.readthedocs.io/

download:

https://pypi.org/project/pyrasite/

source:

https://github.com/lmacken/pyrasite

issues:

https://github.com/lmacken/pyrasite/issues

Requirements

  • gdb (version 7.3+)

  • A Linux system whose ptrace policy allows attaching to the target process. See ptrace_scope below.

Installation

pipx install pyrasite

or, for the optional memory viewer:

pip install "pyrasite[memory-viewer]"

Compatibility

Pyrasite runs on CPython 3.9 through 3.15. Injection works between versions as well, so you can run Pyrasite under one Python and inject into a process running another. Both the pyrasite client and the target process must be CPython.

ptrace_scope

Recent Linux distributions restrict ptrace so that a process may only be attached to by its ancestors. If /proc/sys/kernel/yama/ptrace_scope is non-zero you will see a warning. You can either allow attaching globally:

echo 0 | sudo tee /proc/sys/kernel/yama/ptrace_scope

or let the target process opt in by calling prctl(PR_SET_PTRACER, PR_SET_PTRACER_ANY). On Fedora, SELinux may also need:

sudo setsebool -P deny_ptrace=off

For multi-threaded programs pyrasite queues the payload with Py_AddPendingCall so that it runs on a thread that already holds the GIL. If the target is blocked in C and never executes Python bytecode, use --inject-method direct instead.

Usage

pyrasite <pid> hello.py
pyrasite <pid> - <<'EOF'
import sys
print(sys.version)
EOF
pyrasite <pid> <(echo 'print("hello")')

The payload is read by the pyrasite process and embedded in the gdb command, so the target does not need read access to the payload file. This also means pipes and process substitution work. Standard payloads can be selected by name (see pyrasite --list-payloads).

Testing

pip install -e ".[dev]"
pytest
ruff check .
ruff format --check .

To run the suite against every supported interpreter with uv:

uv python install 3.9 3.10 3.11 3.12 3.13 3.14 3.15
tox

To test injecting from one interpreter into all of the others, set PYRASITE_TEST_INTERPRETERS to a colon-separated list of interpreter paths before running pytest.

pyrasite-gui

The graphical interface is maintained separately at https://github.com/lmacken/pyrasite-gui.

Authors

Created by Luke Macken with the help of David Malcolm and many other contributors. Logo by Adam Saunders.

Licenses

Code

https://www.gnu.org/graphics/gplv3-127x51.png

Metadata

Release files for pyrasite 2.2.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for pyrasite 2.2.0
File Size Uploaded Provenance Actions
pyrasite-2.2.0.tar.gz 56.7 kB Without provenance Details for pyrasite-2.2.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for pyrasite 2.2.0
File Interpreter ABI Platform Actions
pyrasite-2.2.0-py3-none-any.whl Python 3 none any Details for pyrasite-2.2.0-py3-none-any.whl

Total release size: 110.8 kB

Release files / pyrasite-2.2.0.tar.gz

Download URL pyrasite-2.2.0.tar.gz
Size 56.7 kB
Tags Source
SHA-256 checksum
How to use checksums
eef3cb8154db28286011165e35a0d1659359599fa3309cf4082c3794942b1742
BLAKE2b-256 checksum
How to use checksums
efb78a561f1af024daf0102b4bfac3e85fb03e3b2079480a2087eb56de9b1449
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.15.2

Release files / pyrasite-2.2.0-py3-none-any.whl

Download URL pyrasite-2.2.0-py3-none-any.whl
Size 54.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
4e0e4388032fe6911c70c8dde97be8fb3604061c663d52ce48abd67a93fd8ce8
BLAKE2b-256 checksum
How to use checksums
d1c7bb0805546fd715e84fa0a226e26178f40bb12ae7ffc6e6e9b952997f7b4f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.15.2

Security for pyrasite 2.2.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page