How do I remove/delete a folder that is not empty in Python?

To delete a non-empty folder/directory in Python, you must recursively remove all files and subdirectories within it. The shutil module provides a robust method (rmtree()) to handle this. Below is a detailed guide with examples, error handling, and edge-case solutions.

Method 1: Using shutil.rmtree() (Standard Approach)

Step 1: Import shutil

import shutil
import os  # Optional for path validation

Step 2: Delete the Folder

folder_path = "/path/to/your/directory"

try:
    # Delete the folder and all contents
    shutil.rmtree(folder_path)
    print(f"Successfully deleted '{folder_path}'.")
except Exception as e:
    print(f"Error: {e}")

Method 2: Advanced Error Handling

Handle specific errors like missing folders, permission issues, or locked files.

folder_path = "/path/to/directory"

try:
    if os.path.exists(folder_path):
        shutil.rmtree(folder_path)
        print(f"Deleted '{folder_path}'.")
    else:
        print("Folder does not exist.")
except PermissionError:
    print(f"Permission denied for '{folder_path}'. Close programs using it.")
except OSError as e:
    print(f"Error: {e.strerror}")

Method 3: Handle Read-Only Files (Windows)

On Windows, read-only files may block deletion. Use onerror to reset permissions:

def remove_readonly(func, path, _):
    """Clear the readonly bit and retry the deletion."""
    os.chmod(path, 0o777)  # Make writable
    func(path)

try:
    shutil.rmtree(folder_path, onerror=remove_readonly)
except Exception as e:
    print(f"Error: {e}")

Method 4: Modern Approach with pathlib (Python 3.4+)

Use the object-oriented pathlib module:

from pathlib import Path

folder = Path("/path/to/directory")

if folder.exists():
    try:
        shutil.rmtree(folder)
        print(f"Deleted '{folder}'.")
    except Exception as e:
        print(f"Error: {e}")
else:
    print("Folder does not exist.")

Method 5: Retry for Stubborn Files

Automatically retry deletion if files are temporarily locked (common on Windows):

import time

def delete_folder(path, retries=3, delay=1):
    """Retry deletion if files are locked."""
    for _ in range(retries):
        try:
            shutil.rmtree(path)
            print(f"Deleted '{path}'.")
            return
        except PermissionError:
            print(f"Retrying deletion of '{path}'...")
            time.sleep(delay)
    print(f"Failed to delete '{path}' after {retries} attempts.")

delete_folder(folder_path, retries=5, delay=0.5)

Key Parameters for shutil.rmtree()

Parameter	Description
path	Path to the directory to delete.
ignore_errors	If True, suppress errors (default: False).
onerror	Callback function to handle errors during deletion (e.g., reset permissions).

Common Scenarios & Fixes

Scenario 1: Folder Does Not Exist

if os.path.exists(folder_path):
    shutil.rmtree(folder_path)
else:
    print("Folder not found.")

Scenario 2: Files in Use (Windows/Mac/Linux)

• Windows: Close programs using the files (e.g., Excel, Word).
• Linux/Mac: Use lsof to identify processes locking files.

Scenario 3: Symbolic Links

shutil.rmtree() deletes symlinks but not their targets. To preserve targets:

# Check if a path is a symlink before deletion
if os.path.islink(folder_path):
    os.unlink(folder_path)  # Delete symlink only
else:
    shutil.rmtree(folder_path)

Full Example: Safe Folder Deletion

import shutil
import os

def safe_delete(path):
    """Safely delete a non-empty folder with error handling."""
    try:
        if not os.path.exists(path):
            raise FileNotFoundError(f"Path '{path}' does not exist.")

        # Check if it's a directory
        if not os.path.isdir(path):
            raise ValueError(f"'{path}' is not a directory.")

        # Delete the folder
        shutil.rmtree(path, onerror=remove_readonly)
        print(f"Deleted '{path}'.")
    except Exception as e:
        print(f"Deletion failed: {e}")

def remove_readonly(func, path, _):
    """Reset read-only flag on Windows."""
    os.chmod(path, 0o777)
    func(path)

# Usage
safe_delete("/path/to/your/directory")

Summary

• Basic Deletion: Use shutil.rmtree() for most cases.
• Error Handling: Catch PermissionError, FileNotFoundError, and OSError.
• Edge Cases: Use onerror for read-only files or retry logic for locked files.
• Safety: Double-check paths to avoid accidental data loss.