How do I create a directory, and any missing parent directories in Python?

Here’s a detailed guide to creating directories (including nested parent directories) in Python, with examples, error handling, and best practices:

1. Using os.makedirs()

The os module provides a low-level way to create directories recursively.

Basic Usage:

import os

# Create directory and parents if they don't exist
os.makedirs("path/to/directory", exist_ok=True)

Parameters:

• name: Path of the directory (string).
• mode (optional): Permissions (default: 0o777), e.g., 0o755 for rwxr-xr-x.
• exist_ok: If True, suppresses errors if the directory exists (default: False).

Examples:

• Create a directory with specific permissions:

  os.makedirs("logs/app", mode=0o755, exist_ok=True)

• Without exist_ok (raises error if directory exists):

  try:
      os.makedirs("existing_dir")  # Fails if directory exists
  except FileExistsError:
      print("Directory already exists!")

2. Using pathlib.Path.mkdir() (Python 3.4+)

The modern pathlib module offers an object-oriented approach.

Basic Usage:

from pathlib import Path

# Define the directory path
dir_path = Path("path/to/directory")

# Create directory and parents
dir_path.mkdir(parents=True, exist_ok=True)

Parameters:

• parents: Create parent directories if missing (default: False).
• exist_ok: Skip errors if the directory exists (default: False).
• mode: Permissions (same as os.makedirs).

Examples:

• Create a directory with parents and permissions:

  dir_path = Path("data/2023/logs")
  dir_path.mkdir(parents=True, exist_ok=True, mode=0o755)

• Handle errors without exist_ok:

  try:
      Path("existing_dir").mkdir(parents=True)
  except FileExistsError:
      print("Directory already exists!")

3. Key Differences

Feature	os.makedirs()	pathlib.Path.mkdir()
Syntax	Function-based	Object-oriented
Path Handling	Uses strings	Uses Path objects
Error Handling	Manual try/except	Built-in exist_ok
Cross-Platform Paths	Requires manual handling (e.g., / vs \)	Automatically handles OS differences

4. Error Scenarios & Solutions

Permission Denied:

try:
    os.makedirs("/root/protected_dir")  # Requires admin privileges
except PermissionError:
    print("You don't have permission to create this directory!")

Invalid Path Characters:

try:
    Path("invalid/name:*?<>|").mkdir(parents=True)
except OSError as e:
    print(f"Invalid path: {e}")

Race Conditions:

• Use exist_ok=True to avoid issues if another process creates the directory after your existence check.

5. Best Practices

1. Prefer pathlib for readability and cross-platform compatibility.
2. Always use exist_ok=True unless you need strict control over directory existence.
3. Set Permissions Carefully:

• Avoid overly permissive modes like 0o777 unless necessary.

1. Handle Exceptions:

   try:
       Path("important_data").mkdir(parents=True, exist_ok=True)
   except Exception as e:
       print(f"Failed to create directory: {e}")

6. Real-World Examples

Initialize a Project Structure:

from pathlib import Path

project_path = Path("my_project")
subdirs = [
    "data/raw",
    "data/processed",
    "src/utils",
    "logs"
]

for subdir in subdirs:
    (project_path / subdir).mkdir(parents=True, exist_ok=True)

Create User-Specific Directories:

user_id = "alice"
user_dir = Path(f"users/{user_id}/documents")
user_dir.mkdir(parents=True, exist_ok=True)

7. Notes

• Symbolic Links: If a parent directory is a symlink, os.makedirs and pathlib will follow it.
• Windows vs. Unix: pathlib automatically uses \ on Windows and / on Unix.
• Spaces/Special Characters:

  Path("dir with spaces").mkdir(exist_ok=True)  # Handles spaces
  Path("special_chars_#%&").mkdir(exist_ok=True)  # Handles most special chars

By using os.makedirs or pathlib.Path.mkdir, you can robustly create directories in Python while handling edge cases like missing parents, permissions, and race conditions.