Skip to main content

An embeddable, remote-capable Python shell

Project description


Telepythy is a desktop Python shell inspired by DreamPie with some notable additional features, such as remote interpreters. It is designed to streamline a prototyping workflow.


  • Combines the flow of a REPL with the expressiveness of an editor
  • UI based on Qt 6
  • Syntax highlighting based on Pygments
  • Embeddable service with no third-party dependencies
  • Remote connections (as client or server via TCP)
  • Seamless swapping between multiple interpreter profiles


  • UI requires Python 3 on Linux/Windows/OSX (tested: 3.6/3.7/3.9 on Linux/Windows)
  • Embeddable service supports Python 2 and 3 on all platforms (tested: 2.7/3.6/3.7/3.9 on Linux/Windows)



Windows (You can make it look like default IDLE if you want)



There are many Python shells:

They are all good in their own ways. I frequently use the standard Python shell, because it is always there. But when I have been able to install my preference for my most common use cases (prototyping and debugging), my choice was always DreamPie.

Unfortunately, it looks as if all development stopped sometime before 2016, and the last official release was in 2012. I looked into creating a fork to add the features I was interested in, but the effort to modernize (i.e. Python 3) and refactor an unfamiliar and complex code-base was more than I cared to invest in. Starting a new project seemed much more fun.

So, I decided to start from scratch, and Telepythy is the result.


The most reliable way to install telepythy across platforms is with pipx:

$ pipx install telepythy

This will install Telepythy in an isolated environment for the current user, and should work on Windows, Linux, and OSX (untested).

For Windows users, you can download an installer here.


Once Telepythy and its dependencies have been installed, you can start the UI with:

$ telepythy-gui
# or
$ python -m telepythy.gui

NOTE: At this early state, it may be helpful to use the --verbose (-v or -vv) flag to track what Telepythy is doing (especially if reporting a bug).


Style and font options can be configured with the UI. Manually editing the config file is currently the only way to persist any other options.

The config file is located according to the results of platformdirs.user_config_dir() (e.g. ~/.config/telepythy/telepythy.cfg on Linux, C:\Users\<username>\AppData\Local\telepythy\telepythy.cfg on Windows).

Virtual Environments

Any virtual environments discovered in ~/.virtualenvs will be accessible automatically in the Profiles menu.


To embed a Telepythy service in your code, you can use any of the following functions:

import telepythy

# start a server thread

# or start a client thread (with optional arguments)
telepythy.start_client(locals={'bar': False}, address='localhost:1337')

# or start a client/server directly (blocking)

See the <telepythy>/examples directory from the repository for examples on how to embed the service into existing code.

Local Interpreters

To add a custom local interpreter, you must create a profile referencing the path for the interpreter in the config file:

<profile-name>.command = "<command-for-interpreter>"

Remote Interpreters

The remote service needs to be accessible by whichever interpreter you intend to use. A minimal, service-only package can be installed from PyPI:

$ pip install telepythy-service

It can then be started using one of the following commands:

$ telepythy-svc [-c,--connect] '<host>:<port>'
$ telepythy-svc [-s,--serve] '<interface>:<port>'
# or
$ python -m telepythy ...

With no options, a server will start listening on the default interface and port: localhost:7373.

To use Telepythy with a remote service, you must create a profile to either connect to a remote port, or serve on a port, in the config file.

To add a connect profile:

<profile-name>.connect = "<host>:<port>"

To add a serve profile:

<profile-name>.serve = "<interface>:<port>"

You can then use the profile by selecting it in the UI, or with the --profile command-line option:

$ telepythy-gui [-p,--profile] <profile-name>


work in progress


There are no security measures in place within Telepythy to secure your source code in transit. The UI controller connects to the embedded service using a regular TCP connection. By default, the UI starts a server listening on localhost and executes a Python process that connects to it. In the future, the default may change to use UNIX domain sockets on Linux, and named pipes on Windows. An option for SSL is possible for those willing to manage certificates. However, securing communications in transit will always remain a responsibility of the user.

For connections across machines, I recommend using SSH port forwarding. <- (If you're still reading, this is something you should know about.)


Telepythy is very much a work in progress. Here are some features that might be queued up for future releases (in no particular order):

  • Better completion (next on the docket)
  • Embedded documentation (i.e. docstring popups)
  • Smart copy/paste
  • Profile configuration UI
  • UNIX domain sockets
  • SSL sockets
  • Session autosave/import/export
  • Localization (at least Spanish)

If you experience bugs or have additional feature suggestions, please don't hesistate to create an issue. Note that I work on this project in my free time and I don't expect to work on features that I don't personally find useful. I do prioritize bugs, and welcome pull requests.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distributions

No source distribution files available for this release.See tutorial on generating distribution archives.

Built Distribution

telepythy-0.5.3-py3-none-any.whl (71.1 kB view hashes)

Uploaded py3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page