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.

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:
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, unlessforce=True. If an import already configured logging, your call is silently ignored.forcewas 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:
# 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:
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:
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:
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_loggersdefaults toTrue. Any non-root logger that already exists when you calldictConfig(), such as one created at import time bygetLogger(__name__), gets disabled unless it or an ancestor is named in the config. Set it toFalseunless you want that.- Extra handler keys become constructor arguments.
filename,encoding,maxBytesand so on go straight to the handler class. Onlyclassis mandatory. ext://imports a real object."ext://sys.stdout"gives the handler the actualsys.stdoutstream 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:
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")
raiseTwo 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:
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:
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
WARNINGlevel. CallbasicConfig(level=logging.INFO)or set levels indictConfig(). - Your
basicConfig()is ignored. Something configured the root logger first. Useforce=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'sdisable_existing_loggersat its default ofTrue. - Debug logging is slow even when it's off. Use
%sarguments instead of f-strings, and wrap genuinely expensive calls inif 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.
Official sources
Next guide