charmd 0.2.3

CLI to start a PyCharm debug session and then run a Python target in-process

charmd

A PyCharm debug session helper that starts a debug server and then runs your Python target in the same process.

Why charmd?

PyCharm's debugger is powerful, but debugging scripts with different arguments or configurations typically means editing Run Configurations through the IDE. This becomes cumbersome when:

• You need to debug one-off commands with unique CLI arguments
• You're testing different script variations or parameter combinations
• You want the simplicity of command-line debugging (like pdb or debugpy) with PyCharm's full IDE debugging experience

charmd eliminates this friction by letting you debug any Python command directly from the terminal.

---

TOC

• Requirements
• Quick Start
• Locating or Installing pydevd-pycharm
  • Use the library from your PyCharm installation
  • Install using pip
• Configuration File
  • File Location
  • Creating the Configuration File
    • Automatic Generation
    • Manual Creation
  • Configuration Options
  • File Format
  • Configuration Precedence
  • Example Workflow
• Installation
  • From PyPI (Recommended)
  • From Wheel File
  • From Source (Clone Repository)
  • Verifying Installation
  • Uninstalling

---

Requirements

• Python 3.8 or higher
• pydevd-pycharm package (see Locating or Installing pydevd-pycharm below)

Note: charmd does not automatically install pydevd-pycharm as a dependency. This is intentional, as PyCharm installations ship with their own preferred version of the library that should be used for debugging. See Locating or Installing pydevd-pycharm below.

Quick start

⚠️ Important: Before running any charmd command, ensure that:

• PyCharm's Python Debug Server is running and listening on the configured host and port (default: localhost:5678)
• You set breakpoints in your code where you want to pause execution

See PyCharm's Debug Documentation for more information.

usage

charmd [debug-options ...] [--] (-m module | -c command | pyfile) [args ...]

Note: charmd is good at distinguishing debug options from the target specification. In cases where they may be ambiguity, you can use -- to clearly specify the start of the target specification.

examples

charmd -m mypkg.mymod arg1
charmd -c "print('hello')"
charmd -- script.py arg1 arg2

debug options

  -h, --help             Show this help message and exit
  --version              Show program's version number and exit

  --host HOST            PyCharm debug server host (default: localhost)
  --port PORT            PyCharm debug server port (default: 5678)
  --suspend              Suspend on start (default: False)

  --stdout-to-server     Redirect stdout to debug server (default: True)
  --no-stdout-to-server  Do not redirect stdout to debug server

  --stderr-to-server     Redirect stderr to debug server (default: True)
  --no-stderr-to-server  Do not redirect stderr to debug server

  --pydevd-path PATH     Path to the pydevd-pycharm module directory.

  --conf-init            Create a charmd.conf file with current settings and exit.

Locating or Installing pydevd-pycharm

charmd requires the pydevd-pycharm library to communicate with PyCharm's debug server. You can either locate an existing installation (if PyCharm is installed) or install a compatible version via pip.

Option 1: Use the library from your PyCharm installation

If you have PyCharm installed, you can point charmd to the bundled pydevd-pycharm.egg file in your PyCharm installation directory:

Linux/Windows:

<PyCharm directory>/debug-egg/pydevd-pycharm.egg

MacOS:

<PyCharm directory>/Contents/debug-eggs/pydevd-pycharm.egg

For example, on MacOS:

/Applications/PyCharm.app/Contents/debug-eggs/pydevd-pycharm.egg

Configure charmd to use this path via the pydevd_path setting in your configuration file or the --pydevd-path command-line option.

Option 2: Install using pip

If PyCharm is not installed on your system, install the pydevd-pycharm package matching your PyCharm version:

pip install pydevd-pycharm~=<version of PyCharm on the local machine>

For example, if your PyCharm version is 242.20224.428:

pip install pydevd-pycharm~=242.20224.428

To find your PyCharm version, go to PyCharm → About PyCharm (or Help → About on some platforms).

For more information, see the JetBrains Remote Debugging documentation.

Configuration File

charmd supports a configuration file for setting default debug options on a per-project basis. This eliminates the need to specify common options on the command line for every invocation.

File Location

The configuration file must be named charmd.conf and placed in the current working directory (the directory from which you run charmd).

Creating the Configuration File

Option 1: Automatic Generation

Use the --conf-init flag to generate a configuration file with your current settings:

charmd --host 192.168.1.100 --port 5679 --suspend --conf-init

This creates a charmd.conf file in the current directory with the specified settings.

Option 2: Manual Creation

Create a charmd.conf file manually with your preferred text editor:

# charmd configuration file
# Lines starting with '#' are comments.

host = localhost
port = 5678
suspend = false
stdout_to_server = true
stderr_to_server = true
#pydevd_path = /path/to/pydevd_pycharm

Configuration Options

All command-line debug options can be configured in the file:

Option	Type	Default	Description
host	string	localhost	PyCharm debug server host
port	integer	5678	PyCharm debug server port
suspend	boolean	false	Suspend execution on start
stdout_to_server	boolean	true	Redirect stdout to debug server
stderr_to_server	boolean	true	Redirect stderr to debug server
pydevd_path	string	(none)	Path to pydevd-pycharm module directory

File Format

• Key-value pairs: Use key = value syntax
• Comments: Lines starting with # are ignored
• Whitespace: Leading and trailing whitespace is trimmed
• Quotes: Values can be quoted with single or double quotes to preserve internal whitespace

  host = "my host with spaces"
  pydevd_path = '/Applications/PyCharm.app/Contents/debug-eggs'
  

• Boolean values: Accepted values are true, false, 1, 0, yes, no, y, n, on, off (case-insensitive)

Configuration Precedence

Settings are applied in the following order (later sources override earlier ones):

1. Built-in defaults (e.g., host=localhost, port=5678)
2. Configuration file (charmd.conf in current directory)
3. Command-line arguments (highest priority)

This allows you to set project-wide defaults in charmd.conf and override them on a per-invocation basis when needed.

Example Workflow

# Set up project-specific debug configuration
cd /path/to/myproject
charmd --host 192.168.1.100 --port 5679 --conf-init

# Now run with config file defaults
charmd -- myscript.py

# Override specific settings when needed
charmd --suspend -- myscript.py

Installation

From PyPI (Recommended)

Install the latest stable version from PyPI using pip:

pip install charmd

To install for the current user only:

pip install --user charmd

To upgrade an existing installation:

pip install --upgrade charmd

From Wheel File

Wheel (.whl) files are available as release assets on the GitHub releases page. Download the desired version and install it directly:

pip install charmd-*.whl

Replace * with the specific version number, or use the exact filename.

From Source (Clone Repository)

Standard Installation

Clone the repository and install using pip:

git clone https://github.com/tekwizely/python-charmd.git
cd python-charmd
pip install .

Editable/Development Installation

For development work, install in editable mode so changes take effect immediately:

git clone https://github.com/tekwizely/python-charmd.git
cd python-charmd
pip install -e .

This allows you to modify the source code and test changes without reinstalling.

Running Without Installation

You can also run charmd directly from the cloned repository without installing:

git clone https://github.com/tekwizely/python-charmd.git
cd python-charmd
python charmd.py [options]
# or
python -m charmd [options]

Verifying Installation

After installation, verify that charmd is properly installed:

charmd --version

Or:

python -m charmd --version

Uninstalling

To remove charmd:

pip uninstall charmd

---

License

The tekwizely/python-charmd project is released under the MIT License. See LICENSE file.