Guide · Open source

How to use loguru: install, log messages and add files

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

Loguru is a Python library for writing log messages from your code. It works with a single import, so you can start logging without first configuring handlers or formatters. This guide shows you how to install it, log messages, send logs to a file with rotation and cleanup, and decide whether it fits your project.

LoguruDelgan/loguru · ★ 24.2k · MIT Install options & downloads

Quick start

1Install the package. Run pip install loguru in your Python environment.
2Import the logger. Add from loguru import logger at the top of your file.
3Log a message. Call logger.debug, logger.info or another level method with your message.
4Add a file sink. Call logger.add with a string path such as a log file name.
5Set rotation or retention. Pass rotation or retention arguments to add() to control file size, age and cleanup.
6Handle threads or processes. Use enqueue=True on sinks when several processes write to the same file.

Install loguru with pip

Loguru is installed from PyPI with the package manager pip. The README lists Python as the prerequisite, with a badge showing Python 3.5+ and PyPy support.

pip install loguru

Log your first message with one import

The main concept of Loguru is that there is one and only one logger. It is pre-configured and outputs to stderr to begin with, so you do not need any setup before logging. Import it and call a level method such as debug.

The logger is the single object you use in your code.
The default output goes to stderr, and you can change that later.

from loguru import logger

logger.debug("That's it, beautiful and simple logging!")

Add sinks and formats with add()

To change where logs go or how they look, use the add() function. It registers a sink, which is the destination for log messages. A sink can be a simple function, a string path, a file-like object, a coroutine function or a built-in Handler.

To start fresh, call logger.remove() to remove the previously added handlers, including the default stderr handler.

format sets the layout of each message.
level sets the minimum level that is recorded.
filter limits which messages reach the sink.
remove() removes a handler using the identifier returned by add().

logger.add(sys.stderr, format="{time} {level} {message}", filter="my_module", level="INFO")

Write logs to a file with rotation, retention and compression

If you pass a string path as the sink, Loguru writes to a file. The path can include a time placeholder. You can also configure rotation to start a new file, retention to remove older logs, and compression to compress files when they are closed.

rotation="500 MB" rotates a file that gets too big.
rotation="12:00" creates a new file each day at noon.
rotation="1 week" rotates a file once it is too old.
retention="10 days" cleans up logs after that time.
compression="zip" compresses files at closure.

logger.add("file_1.log", rotation="500 MB")
logger.add("file_2.log", rotation="12:00")
logger.add("file_3.log", rotation="1 week")
logger.add("file_X.log", retention="10 days")
logger.add("file_Y.log", compression="zip")

Format messages and log exceptions

Loguru uses braces-style formatting, the same style as str.format(), so you pass values as arguments or named fields. To log an error with its traceback, the catch() decorator or context manager makes sure errors in your function are sent to the logger.

Use {} placeholders instead of % formatting.
Use @logger.catch on a function so errors inside it are logged.

logger.info("We discovered {} is the answer to {question}", 42, question="everything")

@logger.catch
def my_function(x, y, z):
    return 1 / (x + y + z)

Use loguru with threads and multiple processes

Sinks added to the logger are thread-safe by default. They are not multiprocess-safe, but you can pass enqueue=True to ensure log integrity across processes. The same argument can be used for async logging. Coroutine sinks should be awaited with complete().

logger.add("somefile.log", enqueue=True)

What people use it for

Logging from a short Python script to the terminal with readable output.
Writing application logs to a file that rotates when it gets too large.
Deleting old log files automatically with a retention period.
Catching and logging exceptions raised inside threads or the main program.
Compressing closed log files with zip to save disk space.

Frequently asked questions

How do I install loguru?

Install it from PyPI with pip install loguru. The README lists Python as the prerequisite, with a badge showing Python 3.5+ and PyPy support.

Is loguru free to use?

Loguru is released under the MIT licence, as stated in the project's licence information. Check the LICENSE file in the repository for the full terms.

Is loguru better than the standard logging module?

Loguru works out of the box with a single import and adds file rotation, retention, compression, colors and exception logging that the standard logging module takes more work to set up. The standard library is the better choice if your project must use only built-in modules or if you need fine control over every handler.

Does loguru work with multiprocessing?

Sinks are thread-safe by default but not multiprocess-safe. Pass enqueue=True to add() to keep log messages intact when several processes write logs.

What are the alternatives to loguru?

The comparable projects named for this item are the Python standard library logging module, structlog and Logbook. Pick the standard library if you need no third-party dependencies, or structlog for structured logging.

Can I use loguru in a non-Python project?

No. Loguru is a library for Python code, so it does not apply to projects written in other languages.

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

Loguru suits Python developers who want readable logs, file rotation and cleanup with little setup, including scripts and multithreaded or multiprocess projects that use enqueue. Projects that must stay on the standard library only, or teams that need fine control over every standard handler, should pick the standard logging module or another option such as structlog.

Install options & downloads