Install & Compatibility
Where this runs
tested against v262.8665.186 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.930s · 47.5MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 6.6s · import 0.788s · 48MB
46MB installed
● package 46MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
settrace
✓ from pydevd import settrace
✗ from pydevd_pycharm.pydevd import settrace
This example demonstrates how to set up remote debugging with `pydevd-pycharm`. It instructs the Python process to connect to a PyCharm debugger server running on a specified host and port. This is typically used when debugging code running in a separate environment (e.g., a Docker container, remote server) from your PyCharm IDE. Ensure your PyCharm IDE is configured to listen for remote debug connections on the specified host and port.
import os
from pydevd_pycharm.pydevd import settrace
# Configure PyCharm for remote debugging first (Run -> Edit Configurations -> Python Remote Debug).
# Get the host and port from your PyCharm setup.
# The host should be the IP address of the machine running PyCharm (e.g., your local machine's IP).
# The port is what PyCharm is listening on (e.g., 51235).
PYCHARM_DEBUG_HOST = os.environ.get('PYCHARM_DEBUG_HOST', 'localhost')
PYCHARM_DEBUG_PORT = int(os.environ.get('PYCHARM_DEBUG_PORT', '51235')) # Check PyCharm config for actual port
print(f"Attempting to connect to PyCharm debugger at {PYCHARM_DEBUG_HOST}:{PYCHARM_DEBUG_PORT}...")
try:
# suspend=False means the program will not wait for the debugger connection at this point.
# settrace() will attempt to connect and continue execution if it fails.
settrace(
host=PYCHARM_DEBUG_HOST,
port=PYCHARM_DEBUG_PORT,
suspend=False, # Set to True if you want execution to pause until debugger connects
stdoutToServer=True,
stderrToServer=True
)
print("Debugger connection established (or attempted).")
except Exception as e:
print(f"Failed to connect to debugger: {e}")
# Your application logic continues here
def my_function():
message = "This line can be a breakpoint in PyCharm."
print(message)
return message
if __name__ == '__main__':
my_function()
Debug
Known issues
gotchaMost users do not need to install `pydevd-pycharm` manually via pip. PyCharm bundles and manages its own version internally. Manual installation is primarily for remote debugging scenarios where the target environment (e.g., a server, Docker container) does not have PyCharm installed.fixOnly install this package directly if you are setting up remote debugging and need to inject the debugger client into an environment. Otherwise, rely on your PyCharm installation.
affects: All versions
breakingThe internal communication protocol and API parameters for `settrace` can change between major PyCharm/IDEA releases. An older `pydevd-pycharm` client might not be fully compatible with a newer PyCharm IDE, and vice-versa, leading to debugging issues or failures to connect.fixEnsure the `pydevd-pycharm` version installed in your remote environment is compatible with your PyCharm IDE version. Typically, upgrading `pydevd-pycharm` in your remote environment to match your IDE's recent version is the solution.
affects: All versions, especially across major PyCharm IDE releases.
gotchaRemote debugging requires careful network configuration. Firewall rules, network access control lists (ACLs), or incorrect IP addresses/ports can prevent the debugger client from connecting to the PyCharm IDE. Common issues include 'Connection refused' or 'Timeout' errors.fixVerify that your PyCharm IDE is listening on the correct host/port. Ensure there are no firewalls blocking traffic between the debugged application and the IDE. Use the actual IP address of the PyCharm machine, not 'localhost', if they are on different machines or within Docker networks.
affects: All versions
gotchaRunning code under a debugger, especially with `stdoutToServer=True` or `stderrToServer=True`, can introduce noticeable performance overhead. This is generally expected for debugging tools but can be significant in performance-critical applications.fixDisable debugger features that are not strictly needed (e.g., `stdoutToServer`, `stderrToServer` if console output isn't critical to debug) or remove `settrace` calls entirely for production environments. Only debug when necessary.
affects: All versions
Upgrade
Version history
262.8665.186latest on PyPI · released Jul 9, 2026
Audit
Dependencies
No dependency data recorded yet.