github // pypi // issues

Configures your Python shell

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 dependencies
  • Uses IPython and BPython if available, and falls back to built-in interpreter
  • Can have multiple configurations per project using named configs

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 2 and 3 (tested on 2.6, 2.7, 3.2, 3.3, 3.4). There are no other dependencies.


$ konch

runs the shell.

$ konch init

creates a .konchrc file in your current directory.

.konchrc is just a Python file that calls the konch.config(config_dict) function.

You can pass any of the following options:

  • context: A dictionary or list of objects that will be immediately available to you in your shell session.
  • shell: Default shell. May be 'ipy', 'bpy', 'py', or 'auto' (default). You can also pass a Shell class directly, such as konch.IPythonShell, konch.BPythonShell, konch.PythonShell, or konch.AutoShell.
  • banner: Custom banner text.
  • prompt: The input prompt (not supported with BPython).
  • hide_context: If True, don’t show the context variables in the banner. Defaults to False.

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

# .konchrc
import konch
import requests

    'context': {
        'httpget': requests.get,
        'httppost': requests.post,
        'httpput': requests.put,
        'httpdelete': requests.delete
    'banner': 'A humanistic HTTP shell'

Now, when you run konch again:

konch with requests

See also

For more examples, see the example_rcfiles directory.

$ konch edit

opens the current config file in your editor.

$ 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
    'context': [os, sys]

konch.named_config('http', {
    'context': {
        'httpget': requests.get,
        'httppost': requests.post

konch.named_config('flask', {
    'context': {
        'request': flask.request,
        'Flask': flask.Flask,
        'url_for': flask.url_for

To use the flask config, you would run:

$ konch -n flask

$ konch -s <shell>

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

$ konch -f <file>

starts a session using <file> as its config file instead of the default .konchrc.

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
        'cheese': cheese

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...
        'db': db,
        'app': app
        'app': app

You can also use shell objects directly:

import konch

my_shell = konch.AutoShell(context={'foo': 42}, banner='My foo shell')
“Praise the Magic Conch!”
Fork me on GitHub