CoreMesh

Python Logging Examples: From Basic Setup to Rotating Files

A cheat sheet of standard-library logging patterns with runnable code, from a one-line script setup to dictConfig, tracebacks and size- or time-based log rotation.

Checked against the official docs on Oct 25, 2026.

Python Logging Examples: From Basic Setup to Rotating Files

These Python logging examples cover what most programs need: a one-line basicConfig() for scripts, a named logger per module, handlers and formatters, a full dictConfig() setup, exceptions with tracebacks, and log files that rotate. Everything uses the standard library logging module, and the runnable examples print their real output.

Python logging cheat sheet

Task Code
Quick setup for a script logging.basicConfig(level=logging.INFO)
One logger per module logger = logging.getLogger(__name__)
Log with arguments logger.info("user %s logged in", user_id)
Log an exception with traceback logger.exception("upload failed") inside except
Traceback at another level logger.warning("retrying", exc_info=True)
Add a call stack logger.info("checkpoint", stack_info=True)
Add your own fields logger.info("paid", extra={"order_id": 42})
Timestamps in the format format="%(asctime)s %(levelname)s %(name)s: %(message)s"
Log to a file basicConfig(filename="app.log", encoding="utf-8")
Replace an earlier setup basicConfig(..., force=True)
Rotate by size RotatingFileHandler("app.log", maxBytes=1_000_000, backupCount=5)
Rotate at midnight TimedRotatingFileHandler("app.log", when="midnight", backupCount=7)
Quiet one subsystem logging.getLogger("myapp.http").setLevel(logging.WARNING)
Library code logging.getLogger(__name__).addHandler(logging.NullHandler())
Whole config from a dict logging.config.dictConfig(CONFIG)
Skip expensive debug work if logger.isEnabledFor(logging.DEBUG): ...

The levels, from the Logging HOWTO:

Level Value Use it for
DEBUG 10 Detail you only want while diagnosing a problem
INFO 20 Confirmation that things work as expected
WARNING 30 Something unexpected, but the program still works
ERROR 40 A function couldn't do its job
CRITICAL 50 The program itself may not be able to continue

The default level is WARNING. If you log through a logger without configuring anything, info() and debug() calls are dropped, and warnings and above go to a "handler of last resort" that writes the bare message to sys.stderr. The module-level functions such as logging.warning() instead call basicConfig() for you when the root logger has no handlers, so their output gets the default WARNING:root: prefix. Either way, a fresh script prints warnings but swallows info messages.

basicConfig for scripts

For a script or a small tool, one basicConfig() call at startup is enough. It attaches a handler to the root logger and sets the level and format:

python
import logging
import sys

logging.basicConfig(
    level=logging.INFO,
    format="%(levelname)-8s %(name)s: %(message)s",
    stream=sys.stdout,
)

log = logging.getLogger("billing")

log.debug("not shown: below INFO")
log.info("invoice %s created for %s", 1042, "acme")
log.warning("retrying payment, attempt %d of %d", 2, 3)

# A second call does nothing while the root logger already has handlers...
logging.basicConfig(level=logging.DEBUG, format="IGNORED %(message)s", stream=sys.stdout)
log.debug("still not shown")

# ...unless you pass force=True, which removes and closes the old handlers first
logging.basicConfig(
    level=logging.DEBUG,
    format="%(levelname)s|%(name)s|%(message)s",
    stream=sys.stdout,
    force=True,
)
log.debug("now DEBUG is on and the new format applies")

Three things to take from it:

  • Pass arguments, not f-strings. log.info("invoice %s", 1042) only builds the final string if the record is actually emitted. With an f-string, the formatting work happens every time, even for dropped debug messages.
  • basicConfig() runs once. The logging module reference says it does nothing if the root logger already has handlers, unless force=True. If an import already configured logging, your call is silently ignored. force was added in Python 3.8.
  • Call it before you log. The HOWTO notes the call should come before any calls to debug(), info() and the rest, or those events may not be handled the way you want.

basicConfig() writes to sys.stderr by default. Use filename="app.log" for a file (append mode unless you pass filemode="w"), and pass encoding="utf-8" so the file's encoding doesn't depend on the platform default. stream and filename can't be combined: passing both raises ValueError.

Named loggers per module

In anything bigger than one file, give each module its own logger:

python
# myapp/db.py
import logging

logger = logging.getLogger(__name__)  # "myapp.db"


def connect(dsn):
    logger.info("connecting to %s", dsn)

Logger names form a hierarchy split on dots. myapp.db is a child of myapp, which is a child of the root logger. A new logger starts at level NOTSET, which means it defers to its parent, and records propagate up to the handlers of every ancestor. In practice that gives you a simple rule: attach handlers in one place (usually the root logger, in your entry point) and only call getLogger(__name__) everywhere else.

The names also make filtering easy. logging.getLogger("myapp.http").setLevel(logging.WARNING) quiets one noisy part of the app without touching the rest, and %(name)s in the format tells you which module produced each line.

If you're writing a library, don't configure handlers at all. The HOWTO strongly advises adding nothing other than a NullHandler to your library's loggers, because handler setup belongs to the application that uses the library.

Handlers and formatters

A logger decides whether a record is created; handlers decide where it goes; formatters decide how it looks. Each handler has its own level and formatter, so one record can go to the console in short form and to an alert channel in long form:

python
import logging
import sys

root = logging.getLogger()
root.setLevel(logging.DEBUG)

console = logging.StreamHandler(sys.stdout)
console.setLevel(logging.INFO)
console.setFormatter(logging.Formatter("console %(levelname)s %(name)s: %(message)s"))
root.addHandler(console)

alerts = logging.StreamHandler(sys.stdout)
alerts.setLevel(logging.ERROR)
alerts.setFormatter(logging.Formatter("ALERT [%(name)s:%(funcName)s] %(message)s"))
root.addHandler(alerts)

db = logging.getLogger("myapp.db")
print("myapp.db effective level:", logging.getLevelName(db.getEffectiveLevel()))


def run_query():
    db.debug("dropped: the console handler is set to INFO")
    db.info("connected to %s", "orders")
    db.error("query timed out after %s seconds", 30)


run_query()

# The classic mistake: the same handler on a child and on the root
db.addHandler(console)
db.info("this line prints twice")
db.propagate = False
db.info("with propagate=False it prints once")

The last four lines show the most common logging bug. The reference documentation warns that if you attach a handler to a logger and one or more of its ancestors, it may emit the same record multiple times. If you see every line twice, look for a second addHandler() call or a second basicConfig() in some other module.

To attach request IDs, user names or other context, pass extra. Its keys become attributes on the record, so a format string can use them, and the reference warns that they shouldn't clash with the names the logging system uses itself:

python
import logging

logging.basicConfig(format="%(asctime)s %(levelname)s [%(request_id)s] %(message)s")
log = logging.getLogger("myapp.api")
log.warning("slow response", extra={"request_id": "req-7f3a"})

Every record that goes through that formatter then needs a request_id. Either pass it on each call, or build the formatter with a fallback, logging.Formatter(fmt, defaults={"request_id": "-"}), which works on Python 3.10 and later.

The format fields you'll use most come from the LogRecord attributes:

Field Gives you
%(asctime)s Time the record was created, like 2003-07-08 16:49:45,896 by default
%(levelname)s DEBUG, INFO, WARNING, ERROR or CRITICAL
%(name)s Name of the logger
%(message)s The final message, msg % args
%(module)s, %(funcName)s, %(lineno)d Where the call was made
%(process)d, %(threadName)s Process ID and thread name
%(taskName)s asyncio task name (Python 3.12 and later)

Change the date format with datefmt, which takes time.strftime() codes, for example datefmt="%Y-%m-%d %H:%M:%S". If you log from async code, %(taskName)s tells you which task wrote each line.

Configure everything with dictConfig

Once you have more than a couple of handlers, describe the whole setup as data with logging.config.dictConfig(). The schema in the logging.config documentation has a required version key (the only valid value is 1) plus optional formatters, filters, handlers, loggers and root sections:

python
import logging
import logging.config

LOGGING = {
    "version": 1,
    "disable_existing_loggers": False,
    "formatters": {
        "short": {"format": "%(levelname)s %(name)s: %(message)s"},
        "long": {"format": "%(levelname)s %(name)s %(funcName)s:%(lineno)d %(message)s"},
    },
    "handlers": {
        "console": {
            "class": "logging.StreamHandler",
            "level": "INFO",
            "formatter": "short",
            "stream": "ext://sys.stdout",
        },
        "file": {
            "class": "logging.FileHandler",
            "level": "DEBUG",
            "formatter": "long",
            "filename": "debug.log",
            "encoding": "utf-8",
        },
    },
    "loggers": {
        "myapp": {"level": "DEBUG", "handlers": ["file"]},
    },
    "root": {"level": "WARNING", "handlers": ["console"]},
}

logging.config.dictConfig(LOGGING)

log = logging.getLogger("myapp.orders")
log.debug("only in debug.log")
log.info("order %s accepted", "A-17")
logging.getLogger("other.lib").info("dropped: root is at WARNING")

logging.shutdown()  # flush and close the file handler
with open("debug.log", encoding="utf-8") as f:
    print("debug.log contains:")
    print(f.read().rstrip())

Look at where order A-17 accepted ended up: in the file and on the console, even though the root logger is set to WARNING. A record that propagates up from myapp.orders goes straight to the ancestors' handlers, so the console handler's own INFO level is what filters it. The other.lib message is different: that logger has no level of its own, inherits WARNING from the root, and the record is never created.

A few details from that docs page that save time:

  • disable_existing_loggers defaults to True. Any non-root logger that already exists when you call dictConfig(), such as one created at import time by getLogger(__name__), gets disabled unless it or an ancestor is named in the config. Set it to False unless you want that.
  • Extra handler keys become constructor arguments. filename, encoding, maxBytes and so on go straight to the handler class. Only class is mandatory.
  • ext:// imports a real object. "ext://sys.stdout" gives the handler the actual sys.stdout stream instead of the string.

Because it's a plain dict, you can load the same structure from a JSON or YAML file. The older fileConfig() INI format still works, but the docs point out that it can't configure filters and that new features go into dictConfig().

Logging exceptions with tracebacks

Inside an except block, logger.exception() logs at ERROR level and appends the traceback. The reference says to call it only from an exception handler:

python
import logging

logger = logging.getLogger(__name__)


def import_rows(rows):
    for row in rows:
        try:
            save(row)
        except ValueError:
            logger.exception("skipping bad row %r", row)
        except Exception:
            logger.exception("import aborted")
            raise

Two related keyword arguments work on every logging call. exc_info=True adds the current exception's traceback at any level, for example logger.warning("retrying", exc_info=True), and since Python 3.5 you can also pass an exception instance. stack_info=True adds the current call stack even when no exception is being handled, which helps when you need to know who called a function.

Pick one place to report each failure. If you log an exception and then re-raise it, and the caller also logs it, the same traceback shows up twice. Log where you handle the error, or at the top level where it finally stops.

Rotating log files

A plain FileHandler grows forever. The logging.handlers documentation gives you two rotating versions:

python
import logging
from logging.handlers import RotatingFileHandler, TimedRotatingFileHandler

# By size: roll over near 5 MB, keep app.log.1 to app.log.5
by_size = RotatingFileHandler("app.log", maxBytes=5_000_000, backupCount=5, encoding="utf-8")

# By time: a new file every midnight, keep 14 old ones (use a different file)
by_time = TimedRotatingFileHandler("audit.log", when="midnight", backupCount=14, encoding="utf-8")

logging.basicConfig(level=logging.INFO, handlers=[by_size, by_time])

Give each rotating handler its own file. Two handlers that rotate the same path will rename it out from under each other.

For RotatingFileHandler, the file being written is always app.log. When it's nearly maxBytes long, it's renamed to app.log.1, older files shift up to app.log.2 and so on, and the oldest beyond backupCount is dropped. If either maxBytes or backupCount is zero, rollover never happens, so set both. To see it happen, force rotation with a tiny limit:

python
import logging
import os
from logging.handlers import RotatingFileHandler

handler = RotatingFileHandler("app.log", maxBytes=120, backupCount=2, encoding="utf-8")
handler.setFormatter(logging.Formatter("%(levelname)s %(message)s"))

log = logging.getLogger("rotation-demo")
log.setLevel(logging.INFO)
log.addHandler(handler)

for n in range(1, 21):
    log.info("event number %02d", n)
handler.close()

for name in sorted(f for f in os.listdir(".") if f.startswith("app.log")):
    with open(name, encoding="utf-8") as f:
        lines = f.read().splitlines()
    print(f"{name:10} {len(lines)} lines, first: {lines[0]!r}")

Twenty events go in, but only the newest ones survive across app.log, app.log.1 and app.log.2. Everything older is deleted at rollover, which is exactly what backupCount is for.

For TimedRotatingFileHandler, when takes "S", "M", "H", "D", "W0" to "W6" (0 is Monday) or "midnight". Add utc=True to roll over on UTC rather than local time, and atTime (a datetime.time) to choose the time of day for midnight or weekday rollover.

If an external tool such as logrotate rotates your files instead, use WatchedFileHandler. It's meant for Unix and Linux: it notices that the file changed since the last write and reopens it. The docs say it isn't appropriate on Windows, where open log files can't be moved or renamed.

Mistakes that cost the most time

  • Nothing below WARNING appears. You never configured logging, so the root logger is still at its default WARNING level. Call basicConfig(level=logging.INFO) or set levels in dictConfig().
  • Your basicConfig() is ignored. Something configured the root logger first. Use force=True, or move your call to the very start of the entry point.
  • Every line appears twice. A handler is attached to both a logger and one of its ancestors. Keep handlers on the root logger only.
  • Module loggers go quiet after dictConfig(). That's disable_existing_loggers at its default of True.
  • Debug logging is slow even when it's off. Use %s arguments instead of f-strings, and wrap genuinely expensive calls in if logger.isEnabledFor(logging.DEBUG):.

Quick answers

Should I use print() or logging?

The Logging HOWTO recommends print() for the normal console output of a command-line program and a logger's info() or debug() for events you want for status monitoring or fault investigation.

How do I set the log level from an environment variable?

On Python 3.11 and later, map the name with logging.getLevelNamesMapping(), for example level=logging.getLevelNamesMapping()[os.environ.get('LOG_LEVEL', 'INFO')], and pass it to basicConfig().

How do I stop slow log handlers from blocking my app?

Put a QueueHandler on your loggers and run the slow handlers behind a QueueListener. The listener does the work on its own thread, so the code that logs returns quickly.

When should I use warnings.warn() instead of logger.warning()?

Use warnings.warn() in library code when the caller can change their code to avoid the issue. Use logger.warning() when there's nothing the caller can do but the event should still be recorded.

Indra Wijaya

Builds and runs small AI-assisted tools and writes up what works: Claude Code, AI APIs, everyday coding and the fixes in between.

About CoreMesh