Release v4.2.1


konch is a CLI and configuration utility for the Python shell, optimized for simplicity and productivity.

  • Automatically import any object upon startup
  • Simple, per-project configuration in a single file (it’s just Python code)
  • No external dependencies
  • Uses IPython, BPython, or ptpython if available, and falls back to built-in interpreter
  • Automatically load IPython extensions

Example Use Cases

  • If you’re building a web app, you can have all your models in your shell namespace without having to import them individually. You can also run any necessary database or app setup.
  • If you’re building a Python package, you can automatically import all of its modules.
  • In a live demo, skip the imports.
  • Immediately have test objects to work with in interactive sessions.


$ pip install -U konch

Supports Python 3 (tested on 3.6 and 3.7). There are no external dependencies.


If you are using Python 2, konch<4.0 will be installed with the above command.


$ konch init [<config_file>]

creates a .konchrc file in your current directory.

.konchrc is a Python file that calls the konch.config(config_dict) function. See the Configuration section for a listing of options.

Here is an example .konchrc file that includes some functions from the requests library in its context.

# .konchrc
import konch
import requests

        "context": [requests.get, requests.post, requests.put, requests.delete],
        "banner": "A humanistic HTTP shell",

This would produce the following shell:

konch with requests

See also

For more examples, see the example_rcfiles directory.


.konchrc files created with konch init are automatically authorized.


You can override the default file contents of .konchrc by creating a ~/.konchrc.default file in your home directory.

$ konch edit [<config_file>]

opens the current config file in your editor. Automatically authorizes the file when editing is finished.

Checks the KONCH_EDITOR, VISUAL and EDITOR environment variables (in that order) to determine which editor to use.

$ konch [-f <config_file>]

runs the shell. Uses .konchrc as the configuration file, by default.

$ konch -s <shell>

overrides the default shell. Choose between ipy, bpy, py, ptpy, ptipy, or auto.

$ konch allow [<config_file>]

authorizes a config file. You MUST authorize new or edited config files before executing them. This is a security mechanism to prevent execution of untrusted code.

By default, the auth file is stored in ~/.local/share/konch_auth. You can change the location by setting the KONCH_AUTH_FILE environment variable.

$ konch deny [<config_file>]

removes authorization for a config file.

$ konch -n <name>

selects a named config.

Named configs allow you to have multiple configurations in the same .konchrc file.

# .konchrc
import konch
import os
import sys
import requests
import flask

# The default config
konch.config({"context": [os, sys]})

konch.named_config("http", {"context": [requests.get, requests.post]})

    "flask", {"context": [flask.Flask, flask.url_for, flask.render_template]}

To use the flask config, you would run:

$ konch -n flask

You can also pass multiple names to named_config:

# konch -n flask
# OR
# konch -n fl
    ["flask", "fl"], {"context": [flask.Flask, flask.url_for, flask.render_template]}


  • context: A dictionary or list of objects that will be be available in your shell session. May also be a callable that returns a dictionary or list.
  • shell: Default shell. May be 'ipy', 'bpy', 'ptpy', 'ptipy', 'py', or 'auto' (default). You can also pass a Shell class directly, such as konch.IPythonShell, konch.BPythonShell, konch.PtPythonShell, konch.PtIPythonShell, konch.PythonShell, or konch.AutoShell.
  • banner: Custom banner text.
  • prompt: The input prompt (not supported with BPython).
  • output: (IPython and ptipython only) The output prompt.
  • context_format: Format to display context. May be 'full', 'short', hide, or a function that receives the context dictionary as input and returns a string.
  • ipy_extensions: (IPython and ptipython only) IPython extensions to load at startup.
  • ipy_autoreload: (IPython and ptipython only) Whether to enable the IPython autoreload extension.
  • ipy_colors: (IPython only) Color scheme.
  • ipy_highlighting_style: (IPython only) Syntax highlighting style.
  • ptpy_vi_mode: (ptpython and ptipython only) Whether to enable vim bindings.

Setup and Teardown Functions

You can optionally define setup() and/or teardown() functions which will execute immediately before and after running the shell, respectively.

from pathlib import Path
import shutil
import konch

def setup():

def teardown():

konch.config({"context": [Path]})

IPython Extras

konch provides a few IPython-specific options.

Loading Extensions

The ipy_extensions option is used to automatically load IPython extensions at startup.

import konch

        # ...
        "shell": "ipython",
        "ipy_extensions": ["autoreload", "rpy2.ipython"],


The ipy_autoreload option enables and initializes the IPython autoreload extension at startup.

import konch

        # ...
        "shell": "ipython",
        # Automatically reload modules
        "ipy_autoreload": True,

This is equivalent to running:

% load_ext autoreload
% autoreload 2


The ipy_colors and ipy_highlighting_style options are used to configure colors in the IPython shell. ipy_colors sets the color of tracebacks and object info (the output of e.g. zip?). ipy_highlighting_style sets colors for syntax highlighting.

import konch

        # ...
        "shell": "ipython",
        # 'linux' is optimized for dark terminal backgrounds
        "ipy_colors": "linux",
        "ipy_highlighting_style": "monokai",

See the IPython docs for more information and valid values for these options: https://ipython.readthedocs.io/en/stable/config/details.html#terminal-colors

ptpython support

konch supports both ptpython and ptipython. If either is installed in your current environment, running konch will run the available shell.

konch provides a few ptpython-specific options.

To use ptpython’s vi-style bindings, set the ptpy_vi_mode option in your .konchrc. You can also use the ipy_extensions option to load IPython extensions at startup (must be using ptipython).

import konch

        # ...
        "shell": "ptipython",
        "ptpy_vi_mode": True,
        "ipy_extensions": ["autoreload"],

Using .konchrc.local

If you’re distributing your .konchrc in a git repo, you may want to allow collaborators to extend your configuration in an unversioned .konchrc.local file.

First, add .konchrc.local to .gitignore.

# .gitignore


Then add the following to your .konchrc:

# .konchrc

from pathlib import Path

# konch.config(...)

if Path(".konchrc.local").exists():
    konch.use_file(".konchrc.local", trust=True)


The context in .konchrc.local will be merged with the context in .konchrc.


Passing trust=True allows .konchrc.local to be edited without requiring approval. This is safe if (and only if) .konchrc.local is not added to source control.


setup() and teardown() cannot be used in .konchrc.local.

Programmatic Usage

Want to use konch within a Python script? konch exposes many of its high-level functions.

import konch
from mypackage import cheese

# Start the shell
konch.start(context={"cheese": cheese}, shell=konch.AutoShell)

To use a config file:

import konch


Get command-line arguments using konch.parse_args(). konch uses docopt for arguments parsing.

import konch
from myapp import app, db

args = konch.parse_args()
if args["--name"] == "db":
    # ...expensive database setup...
    konch.start(context={"db": db, "app": app})
    konch.start(context={"app": app})

You can also use shell objects directly:

import konch

my_shell = konch.AutoShell(context={"foo": 42}, banner="My foo shell")

Integrating with setuptools / python setup.py shell

You can integrate konch into your setuptools-based project using the following Command class.

# setup.py
import shlex
from setuptools import Command

class Shell(Command):
    user_options = [
        ("name=", "n", "Named config to use."),
        ("shell=", "s", "Shell to use."),
        ("file=", "f", "File path of konch config file to execute."),

    def initialize_options(self):
        self.name = None
        self.shell = None
        self.file = None

    def finalize_options(self):

    def run(self):
        import konch

        argv = []
        for each in ("name", "shell", "file"):
            opt = getattr(self, each)
            if opt:

    # ...,
    cmdclass={"shell": Shell}

You can now run:

$ python setup.py shell

You can also pass a string of arguments:

$ python setup.py shell -a "--shell ipy"
“Praise the Magic Conch!”