Guide · Open source

How to use icecream: install it and debug Python with ic()

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

IceCream is a free, MIT-licensed Python library, installed with pip, that replaces print() statements when you debug. Its main function, ic(), prints an expression's text next to its value, formatted and syntax highlighted. This guide shows you how to install it, inspect variables and execution, and control its output so you can debug with less effort.

IceCreamgruns/icecream · ★ 10.1k · MIT Install options & downloads

Quick start

1Install the package. Run pip install icecream in a terminal. You need Python 3.
2Import ic. Add from icecream import ic at the top of the file where you want to debug.
3Replace print() with ic(). Pass the variable or expression you would have printed directly to ic().
4Trace execution. Call ic() with no arguments to see the filename, line number and parent function.
5Turn output off when you are done. Call ic.disable() to silence output and ic.enable() to restore it, leaving the calls in place.

Install IceCream with pip

IceCream is a Python library, so you need Python 3 installed. Install the package with pip from your terminal.

Prerequisite: Python 3
The package name on PyPI is icecream

$ pip install icecream

Inspect variables and expressions with ic()

Import ic and pass it a variable or expression. ic() prints the text of what you passed along with its value, so you do not have to type the label yourself. Data structures are pretty printed and the output is syntax highlighted.

In the README example, calling ic(foo(123)) inside a function that returns i + 333 prints the expression text and its result on one line.

from icecream import ic

def foo(i):
    return i + 333

ic(foo(123))

Trace which code runs with an empty ic() call

Call ic() with no arguments to see where execution passes. It prints the calling filename, line number, and parent function. This helps when you want to know which branch of an if statement ran or in what order functions were called.

The README's sample output shows lines such as the filename, line number and function name, one per call.

from icecream import ic

def foo():
    ic()
    first()

    if expression:
        ic()
        second()
    else:
        ic()
        third()

Keep ic() calls in code without changing behavior

ic() returns its arguments, so you can wrap existing code in it. The README example passes a value into ic() inside another call, and the value still reaches the function.

You can also turn all ic() output off with ic.disable() and back on with ic.enable(). Calls remain in the code, and they still return their arguments while disabled.

ic.disable() silences output without removing calls
ic.enable() turns output back on

from icecream import ic

ic(1)

ic.disable()
ic(2)

ic.enable()
ic(3)

Change the output format and add context

ic.configureOutput() controls the output. It accepts a custom prefix, an outputFunction, an argToStringFunction, includeContext and contextAbsPath. The default prefix is 'ic| '.

includeContext=True adds the filename, line number and parent function to each line. contextAbsPath=True prints absolute file paths instead of filenames, which the README notes helps when files share names and lets some editors such as VSCode open the file from the output.

prefix: change the text before each line
outputFunction: send the output somewhere other than stderr
argToStringFunction: control how values are turned into text
includeContext: add filename, line number and parent function
contextAbsPath: print absolute paths when context is on

from icecream import ic

ic.configureOutput(includeContext=True)

Use ic.format() with a logger or make ic() optional in production

ic.format() works like ic() but returns the output as a string instead of writing it to stderr. The README suggests passing that string to Python's logging module when you need log levels, and notes that IceCream does not provide built-in log levels.

To keep ic() out of production, the README shows a fallback import. If IceCream is not installed, ic is replaced with a small function that returns its arguments, so the code still runs.

IceCream has no built-in log levels; the README points to the logging module via ic.format()
The fallback import lets code run where icecream is not installed

import logging
from icecream import ic

foo = 'bar'
logging.debug(ic.format(foo))

What people use it for

Printing a variable's value and its expression text while debugging a function
Finding which branch of an if statement runs by placing empty ic() calls
Wrapping an existing function argument in ic() without changing what the code returns
Adding file and line context to output when several files share the same name
Sending debug output to a logger with ic.format() in a Python project

Frequently asked questions

Is icecream free to use?

IceCream is licensed under the MIT licence, which the README describes as permissive. The source does not list prices, so the licence is the relevant information here.

What do I need to install icecream?

The README lists Python 3 as the prerequisite and installs the package with pip install icecream. It also says IceCream supports Python 3 and PyPy3.

Can I use icecream in production code?

The README says IceCream is meant for debugging and suggests a standard logger for production logging via ic.format(). It notes that built-in log levels are not provided. You can use the fallback import so production code runs without the package installed.

How do I turn off icecream output without deleting the ic() calls?

Call ic.disable() to stop output and ic.enable() to start it again. The README says ic() still returns its arguments while disabled, so existing code keeps working.

How is icecream different from print()?

According to the README, ic() prints both the expression and its value, pretty prints data structures, syntax highlights output, and can add filename, line number and parent function. print() does not do these things by default. The README does not give a benchmark, so the typing speed claim in its feature list is the author's.

Can icecream be used outside Python?

No. IceCream is a Python library, so it is not suitable for non-Python projects.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

IceCream suits Python developers who use print() to debug and want output that shows expressions, context and can be switched off without deleting calls. It is not a logging system, so pick the standard logging module or another logger for production logs or when you need log levels. Use it for debugging only, and skip it for non-Python work.

Install options & downloads