Creating Directory Hierarchies in Python: Using os.makedirs and the exist_ok Option

When outputting files, ensuring the destination directory (folder) exists beforehand is necessary.

The Python standard library os module provides two functions for creating directories: os.mkdir() and os.makedirs(). os.makedirs() is particularly useful because it creates deep hierarchies at once.

This article explains the basic usage of os.makedirs() and how to avoid errors when a directory already exists.

1. Creating Deep Hierarchies at Once: os.makedirs()

Using os.makedirs() automatically creates all intermediate directories (parent directories) in the specified path if they do not exist (recursive creation).

Syntax:

import os

os.makedirs(path_to_create)

Specific Usage Example:

Here is an example of creating a deep hierarchy at once, such as making a “logs” folder inside a “data” folder, which is inside a “project” folder.

import os

# Path of the hierarchy structure to create
# (Create project/data/logs under current directory)
log_dir_path = os.path.join("project", "data", "logs")

print(f"Target: {log_dir_path}")

try:
    # Create the entire hierarchy at once
    os.makedirs(log_dir_path)
    print("Directory created.")
except FileExistsError:
    print("Directory already exists.")

Execution Result: The project folder, the data folder inside it, and the logs folder inside that are all created.

2. Preventing Errors When the Directory Already Exists (exist_ok=True)

By default, if the directory to be created already exists, a FileExistsError occurs, stopping the program.

However, in practice, the desired behavior is often “create if missing, do nothing if it exists.” Since Python 3.2, specifying the argument exist_ok=True allows the process to continue without error even if the directory exists.

import os

# Backup directory
backup_dir = "backup_storage"

# Specify exist_ok=True
# No error if it already exists; creates it if it does not
os.makedirs(backup_dir, exist_ok=True)

print(f"Preparation for '{backup_dir}' is complete.")

Using this option eliminates the need for a try-except block to catch FileExistsError, making the code more concise.

3. Difference from os.mkdir()

A similar function, os.mkdir(), exists, but this specializes in “creating only one level.”

• os.makedirs("a/b/c"): Creates a, b, and c.
• os.mkdir("a/b/c"): The parent directory a/b must already exist. If not, a FileNotFoundError occurs.

import os

# Example where mkdir fails without parent directory
target = os.path.join("new_folder", "sub_folder")

try:
    os.mkdir(target)
except FileNotFoundError:
    print("Error: Cannot create with mkdir because parent directory does not exist.")

Summary

• os.makedirs(path): Recursively creates directories including parents. This is usually the convenient choice.
• exist_ok=True: Specifying this prevents errors if the directory already exists (Recommended).
• os.mkdir(path): Creates only the bottom-most directory. The parent directory must exist.