Skip to content


A Python library for managing logging directories.

Source PyPI Conda CI/CD Docs Docs Status
GitHub PyPI Conda Recipe Test and Deploy Netlify Status


To install from PyPI, run:

pip install logdir

To install from Conda, run:

conda install -c conda-forge logdir

To install from source, clone this repo, cd into it, and run:

pip install .

logdir is tested on Python 3.7+. Earlier Python versions may work but are not guaranteed.


If your experiment is called My Experiment, you can create a logging directory for it with:

from logdir import LogDir

logdir = LogDir("My Experiment")

This will create a logging directory of the form ./logs/YYYY-MM-DD_HH-MM-SS_my-experiment; you can change ./logs by passing in a second argument for the root directory when initializing LogDir, i.e. LogDir("My Experiment", "./different-log-dir").

You now have access to useful methods for creating files and saving data in the directory. For example, start writing to a file new.txt in the directory with:

with logdir.pfile("new.txt").open() as file:
    file.write("Hello World!")

This takes advantage of the pfile() method, which creates a pathlib.Path to the new file. It also uses

pfile() will also create intermediate directories, so this will work even if foo/bar/ does not exist in the logging directory already:

with logdir.pfile("foo/bar/new.txt").open() as file:
    file.write("Hello World!")

There is also save_data(), which saves data to a file. JSON, YAML, TOML, and pickle files are currently supported.

logdir.save_data({"a": 1, "b": 2, "c": 3}, "file.json")

Finally, readme() adds a to the directory with multiple pieces of information. For instance, this command:

logdir.readme(date=True, git_commit=True)

Will create something like:

# My Experiment

- Date: 2020-10-04 23:04:05
- Git Commit: e3rftyt543rt5y67jhtgr4yhju

See the API for all available methods.