ptpython

library3.0.32pypypi✓ verified 26d ago

ptpython is an advanced, cross-platform Python REPL (Read-Eval-Print Loop) built on top of the prompt_toolkit library. It provides features like syntax highlighting, autocompletion, multiline editing, mouse support, and customizable key bindings (Emacs and Vi modes). Currently at version 3.0.32, it sees fairly frequent updates, often with several patch releases per month.

testing

pip install ptpython

github ↗package ↗changelog ↗

INSTALL

IMPORT

SIG · PTPYTHON

ptpython

testingpythonv3.0.32

Install

4.4s avg

Import

693ms

Disk

73MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v3.0.32 · 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

musl

py 3.10–3.910 runs

installs and imports cleanly · install 0.0s · import 0.735s · 80.9MB

glibc

py 3.10–3.910 runs

installs and imports cleanly · install 4.4s · import 0.650s · 81MB

73MB installed

● package 73MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

embed

✓ from ptpython.repl import embed

Used to embed the ptpython REPL directly into a Python application or script. It's common to pass `globals()` and `locals()` to make current scope variables available.

run_config

✓ from ptpython.repl import run_config

Used to explicitly load a configuration file when embedding the REPL, as configuration files are otherwise ignored in embedded mode.

To start a `ptpython` shell, simply run `ptpython` in your terminal. To embed it in a Python script for debugging or interactive sessions, use `ptpython.repl.embed()`. You should pass `globals()` and `locals()` to `embed()` to make the current scope available inside the REPL.

import os from ptpython.repl import embed def main(): print("Entering embedded ptpython REPL...") my_variable = "Hello from host script" # Pass globals() and locals() to make variables accessible in the REPL embed(globals(), locals()) print("Exited embedded ptpython REPL.") if __name__ == "__main__": # Or simply run from command line: # $ ptpython main()

ptpython --version

Debug

Known issues

breakingPython 3.7 support was dropped in version 3.0.30. Users on Python 3.7 or older must use an earlier ptpython version (e.g., ptpython 2.0.5 for Python < 3.6, or a 2.x version for Python 3.7).

fix

Upgrade to Python 3.8 or newer, or pin ptpython to <3.0.30.

affects: >=3.0.30

gotchaWhen embedding the REPL using `ptpython.repl.embed()`, configuration files (e.g., `~/.config/ptpython/config.py`) are ignored by default. This can lead to unexpected behavior if you rely on custom settings.

fix

Explicitly load your configuration using `from ptpython.repl import run_config; run_config(repl, config_path)` within your `configure` callback passed to `embed()`.

affects: All versions

breakingSince version 3.0.24, the `--asyncio` flag is explicitly required to activate the asyncio REPL when running `ptpython` from the command line. Previously, asyncio mode might have been implicitly active under certain conditions.

fix

Ensure you explicitly pass `--asyncio` when you intend to use the asyncio-enabled REPL for top-level await or other async features.

affects: >=3.0.24

gotchaVersion 3.0.28 introduced a custom `exit` function that can be called without parentheses (i.e., just `exit`) to return from the REPL when embedded. While convenient, users accustomed to always calling `exit()` might find this behavior unexpected.

fix

Be aware that both `exit` and `exit()` will work to leave the embedded REPL.

affects: >=3.0.28

gotchaIn version 3.0.32, the default code theme ('default-ansi') switched to using ANSI colors instead of RGB. This can alter the appearance of syntax highlighting depending on your terminal emulator's color configuration, potentially affecting contrast.

fix

If the default theme's colors are unsatisfactory, you can configure a custom color scheme in your `config.py` file or select a different theme if available.

affects: >=3.0.32

Errors

Common errors & fixes

ImportError: cannot import name 'PathCompleter'

This error typically occurs due to an incompatibility between the installed versions of `ptpython` and its dependency, `prompt_toolkit`, where `PathCompleter` was moved or removed in a newer `prompt_toolkit` version.

fix

Downgrade `prompt_toolkit` to a compatible version, or upgrade `ptpython` to a version that supports your `prompt_toolkit` version. Often, reinstalling `ptpython` in a clean virtual environment resolves such dependency conflicts.

ModuleNotFoundError: No module named 'some_module'

`ptpython` is running in a Python environment where the required module (`some_module`) is not installed, or `ptpython` is not using the expected Python interpreter (e.g., system Python instead of a virtual environment where the module is installed).

fix

Ensure you have activated the correct virtual environment before launching `ptpython`, or install the missing module using `pip install some_module` within the environment that `ptpython` is using. You can inspect `sys.path` within the `ptpython` REPL to verify the paths being searched for modules.

Ctrl-S forward search doesn't work and freezes my terminal.

This is not a Python error but a terminal control flow issue; Ctrl-S (XOFF) is a common key binding in some terminal emulators that pauses output, often leading to a frozen terminal.

fix

Disable flow control in your terminal by running the command `stty -ixon`. This command is usually executed in your shell before starting `ptpython`.

AttributeError: 'X' object has no attribute 'Y'

You are attempting to access an attribute or call a method (`Y`) on an object (`X`) that does not possess that specific attribute or method. This is a common Python runtime error resulting from typos, incorrect object types, or trying to use a feature that doesn't exist for a given object type.

fix

Review your code to confirm the object (`X`) is of the expected type and that the attribute or method (`Y`) you are trying to access exists and is spelled correctly. In `ptpython`, you can use `dir(X)` to see available attributes or `help(X)` to view documentation for the object.

Upgrade

Version history

3.0.32latest on PyPI · released Nov 20, 2025

Audit

Dependencies

prompt_toolkitrequiredCore UI toolkit for building interactive command line applications, ptpython is built on top of it.

jedirequiredUsed for code completion and introspection.

pygmentsrequiredUsed for syntax highlighting.

appdirsrequiredUsed for determining platform-specific configuration file locations.

ipythonoptionalOptional dependency for using ptipython, which integrates ptpython with IPython's features.

Agent activity

12 hits · last 30 days

node

Resources

githubhttps://github.com/prompt-toolkit/ptpython ↗

packagehttps://pypi.org/project/ptpython/ ↗

changeloghttps://github.com/prompt-toolkit/ptpython/blob/master/CHANGELOG ↗