๐ฅ LitPrinter
The debug printer that replaces print(), logging and icecream
One tool for your terminal: smart debugging, a drop-in print(),
logging without logging, and beautiful tracebacks.
๐ Why LitPrinter?
| Feature |
print() |
IceCream |
logging |
LitPrinter |
| Shows variable names |
โ |
โ
|
โ |
โ
|
Replaces print() |
โ |
โ |
โ |
โ
|
| Colored markup output |
โ |
โ |
โ |
โ
|
| Auto context when useful |
โ |
โ |
โ
|
โ
|
| Pretty tracebacks |
โ |
โ |
โ |
โ
|
| Zero-import (works everywhere) |
โ |
โ |
โ |
โ
|
โก Quick Start
pip install litprinter
# No import needed! ic is automatically available
x = 42
ic(x) # ic| x: 42
ic.print("hello", x) # hello 42
ic("server started", level="info") # INFO server started
That's it. After pip install litprinter, ic is available in every Python
script โ no import required โ and so are the pretty tracebacks.
Editors: this repo ships a patched typeshed (.typeshed) so ic is typed as
a real builtin for ty, Pylance/pyright and mypy, with hover docs and
completions like print().
๐ Debugging that explains itself
def calculate(a, b):
total = a + b
ic(total) # ic| total: 30 <- name is obvious, no noise
ic(total / len(items)) # ic| [app.py:3 in calculate()] >>> total / len(items): 10.0
ic() # ic| app.py:3 in calculate() - 14:02:11.004
return total
ic(total * 2) # ic| [app.py:9] >>> total * 2: 60 <- module level: no `in <module>`
At module level (the top level of a script) there is no enclosing function, so
the context is just file:line. Inside a function it also names the function.
Context is added only when it helps:
| Call |
Context shown? |
Why |
ic(x) |
no |
the name is already printed |
ic(x + 1) |
yes |
the expression matters |
ic(items[0]) |
yes |
needs a location |
ic(f"hi {name}") |
no |
the value is self-describing |
ic() |
yes |
acts as a "where am I" breadcrumb |
Override it any time:
ic(x, includeContext=True) # force context for this call
ic(x, includeContext=False) # suppress context for this call
ic.configureOutput(contextMode="always") # 'auto' (default) | 'always' | 'never'
๐จ Rich-like rendering
Values are syntax highlighted automatically and multi-line values hang off
the first line instead of restarting at column 0:
config = {"host": "0.0.0.0", "port": 8080, "tags": ["a", "b"]}
ic(config)
ic| config: {
'host': '0.0.0.0',
'port': 8080,
'tags': ['a', 'b']
}
Colors follow the terminal: on for a TTY, off when piped to a file. Force them
with FORCE_COLOR=1, suppress with NO_COLOR=1.
๐จ๏ธ ic.print โ drop-in print() replacement
Same signature as builtin print(), so you can sed-replace print( โ ic.print(:
ic.print("plain") # plain
ic.print("a", "b", sep=" | ", end="!\n") # a | b!
ic.print("to stderr", file=sys.stderr, flush=True)
# Inline markup (Rich-style tags, zero dependencies)
ic.print("[bold red]ERROR[/bold red] connection refused")
ic.print("[on_blue] INFO [/on_blue] listening on :8080")
ic.print("styled", style="bold cyan")
# Syntax highlight non-string values
ic.print({"port": 8080, "host": "0.0.0.0"}, highlight=True)
# Disable markup if your data contains brackets
ic.print("[not markup]", markup=False)
Supported tags: bold, dim, italic, underline, strike, reverse,
blink, the 8/16 colors (red, bright_red, โฆ), backgrounds (on_blue, โฆ),
#ff8800 hex colors, rgb(255,0,0), and [/] to close.
litprinter.print is exported too, so from litprinter import print works.
๐ Logging without logging
ic() is the logger. Add level= and the line is tagged with a severity;
keyword arguments become named fields:
ic("cache miss", key="session:9f2", level="debug")
ic("connected", url=url, level="info")
ic("migration complete", level="success")
ic("retrying in 5s", attempt=2, level="warning")
ic("request failed", status=500, level="error")
ic("disk full", level="critical")
DEBUG 'cache miss', key: 'session:9f2'
INFO 'connected', url: 'https://api.internal'
OK 'migration complete'
WARN 'retrying in 5s', attempt: 2
ERROR 'request failed', status: 500
CRIT 'disk full'
Levels: debug, info, success (ok), warning (warn), error,
critical. An unknown level raises ValueError.
Two differences from ic(x):
- the
ic| prefix is replaced by the severity tag
- the
>>> context arrow is dropped โ a leveled line reads as a log record
Everything else is identical: file/line context still appears when the
expression isn't self-describing, multi-line values still hang off the first
line, and ic.disable() silences levels too. Output goes to stderr so it stays
out of your piped stdout.
Fields work without a level
Keyword arguments are just named values, so this is fine too:
ic("cache miss", key="session:9f2")
# ic| 'cache miss', key: 'session:9f2'
Three keyword names belong to the printer and are never treated as fields:
level, includeContext and contextAbsPath. Positional values are
unaffected.
ic.format(msg, level="error") returns the same line as a string without
printing it.
๐งต Inline usage
result = ic(calculate(x)) # prints AND returns the value
๐จ One theme
LitPrinter ships a single, hand-tuned theme (LitPrinterStyle). It is applied
automatically to ic() values, ic.print(..., highlight=True) and tracebacks โ
there is nothing to choose and nothing to configure.
The palette is deliberately quiet so long debugging sessions stay readable:
muted blue-gray for punctuation, calm cyan for names, warm green for strings,
soft orange for numbers, and strong red reserved for actual errors.
from litprinter import LitPrinterStyle # the only style, exposed for reference
๐ฅ Beautiful tracebacks โ installed automatically
Installing litprinter also installs the traceback handler, so every Python
process gets readable tracebacks with no setup:
โโ Traceback (most recent call last) โโโโโโโโโโ 2026-10-02 11:00:00 โโโโโโโโโโ
ZeroDivisionError: division by zero
File "app.py", line 12, in divide
10 โ payload = {"a": a, "b": b}
โฑ 12 โ return a / b
Variables:
a = 10 payload = {'a': 10, 'b': 0} [dict]
b = 0
Tune it at runtime:
from litprinter import traceback
traceback.install(
show_locals=True,
extra_lines=3,
suppress=["site-packages"], # hide library frames
max_frames=20, # cap the stack
locals_hide_sunder=True, # hide _private locals
)
traceback.uninstall() # back to the default handler
Opt out before Python starts:
LITPRINTER_NO_TRACEBACK=1 py app.py # normal traceback, ic() still available
LITPRINTER_NO_AUTOLOAD=1 py app.py # litprinter fully inert
๐ง Configuration
ic.configureOutput(
prefix="dbg| ", # custom prefix
contextMode="auto", # 'auto' | 'always' | 'never'
contextAbsPath=False, # relative paths in context
pairDelimiter=", ", # separator between debugged values
outputFunction=my_logger, # send output anywhere
)
ic.disable() # silent, but still returns values
ic.enable()
s = ic.format(x, y) # format without printing
Custom formatters
from litprinter import argumentToString
class MyClass:
def __init__(self, name):
self.name = name
@argumentToString.register(MyClass)
def format_myclass(obj):
return f"MyClass({obj.name})"
ic(MyClass("test")) # ic| MyClass(test)
๐ Migration
From IceCream:
# before
from icecream import ic
# after: nothing to do - ic is already a builtin after install
From print():
# before
print(f"user: {user['name']}")
# after - shows the expression, no f-string needed
ic(user["name"])
From logging:
# before
logger.info("connected to %s", url)
# after
ic("connected", url, level="info")
๐ API Reference
| API |
Description |
ic(*args, level=) |
Debug print, passthrough return, and the logger |
ic.print(*values, sep=, end=, file=, flush=, markup=, style=, highlight=) |
print() replacement with markup |
ic.configureOutput(...) |
Configure prefix, context, formatters, output |
ic.disable() / ic.enable() |
Toggle output (including leveled lines) |
ic.format(*args, level=) |
Format without printing |
ic.install() / ic.uninstall() |
(Un)register the builtins |
LitPrinterStyle |
The single built-in theme (a pygments.style.Style) |
argumentToString.register(Type) |
Custom value formatters |
traceback.install(...) |
Pretty tracebacks |
Aliases: LIT, litprint, lit all point at ic.
๐๏ธ Removed in 0.4.0
- The level methods โ
ic.log(), ic.debug(), ic.info(),
ic.success(), ic.warning() / ic.warn(), ic.error(), ic.critical()
and module-level litprinter.log(). Use ic(msg, level="error"). One entry
point means one thing to type and one thing to turn off.
- The bundled themes โ
litprinter.styles (19 themes), coloring.py,
set_style() / get_style() and traceback.install(theme=...). There is now
exactly one built-in theme, LitPrinterStyle.
- The bundled Rich re-implementation โ
Console, console, cprint,
Panel, Box, Text, Span, Segment and Style.
ic.print(markup=True) covers the colored-output use case; use the real
Rich for full console rendering.
๐ค Contributing
Contributions are welcome! See CONTRIBUTING.md for details.
Made with โค๏ธ by OEvortex