How to Create Directories in Python: Absolute Beginners Tutorial

Python gives you two standard ways to create directories: the os module, which has been available since early Python, and pathlib, introduced in Python 3.4 as a more modern, object-oriented alternative. This tutorial covers both from the ground up.

When a Python script needs to save output files, organize data, or prepare a project layout, it often needs to create directories at runtime. Understanding which tool to reach for — and what errors to expect — is one of those foundational skills that shows up constantly in real code.

What is a Directory in Python?

A directory is a folder on your file system. Python uses the term interchangeably with "folder" in its documentation. When you create a directory in Python, you are instructing the operating system to reserve a named location in the file system where files and other directories can be stored.

Python does not have a built-in keyword for directory operations. Instead, the standard library provides two modules that handle file system work: os and pathlib. You need to import at least one of them before creating any directories.

Creating a Single Directory with os.mkdir()

os.mkdir() is the most direct way to create a single directory. It accepts a path string and creates exactly one new directory at that location. If any part of the parent path does not already exist, Python raises FileNotFoundError. If the directory already exists, Python raises FileExistsError.

import os

# Create a single directory named "output" in the current working directory
os.mkdir("output")
print("Directory created.")

Directory created.

If output already exists when this code runs, Python will raise FileExistsError: [Errno 17] File exists: 'output'. The solution is to check first or use exist_ok, which is covered in the next section.

Handling errors with os.mkdir()

Wrapping the call in a try-except block lets your script continue gracefully when the directory is already present or when permissions prevent creation.

import os

try:
    os.mkdir("output")
    print("Directory created successfully.")
except FileExistsError:
    print("Directory already exists — skipping creation.")
except PermissionError:
    print("Permission denied. Cannot create directory here.")
except OSError as e:
    print(f"OS error: {e}")

What you will see the first time you run this (when output does not yet exist):

Directory created successfully.

What you will see every time after that (when output already exists):

Directory already exists — skipping creation.

Creating Nested Directories with os.makedirs()

os.makedirs() is the recursive version of os.mkdir(). When you pass a path like "data/reports/2026", Python creates all three directories in a single call — even if none of them exist yet. This is equivalent to the shell command mkdir -p.

import os

# Creates data/, data/reports/, and data/reports/2026 — all in one call
os.makedirs("data/reports/2026")
print("All directories created.")

Expected output:

All directories created.

After running this, your working directory will contain a new data/ folder, inside which is reports/, inside which is 2026/. Run it a second time without exist_ok=True and you will see FileExistsError: [Errno 17] File exists: 'data/reports/2026'. That is what the next section solves.

The exist_ok parameter

By default, os.makedirs() raises FileExistsError if the target directory already exists, exactly like os.mkdir(). Passing exist_ok=True tells Python to silently skip creation when the directory is already present — no exception, no fuss.

import os

# Safe to call even if the directory already exists
os.makedirs("data/reports/2026", exist_ok=True)
print("Directory is ready.")

Expected output — every time you run it, whether the directory exists or not:

Directory is ready.

The Modern Approach: pathlib.Path.mkdir()

The pathlib module, introduced in Python 3.4, provides a Path class that represents file system paths as objects rather than plain strings. This makes path construction, inspection, and manipulation more readable and cross-platform by default.

The method for creating a directory with pathlib is Path.mkdir(). It accepts two keyword arguments that correspond directly to the behavior of os.makedirs(): parents and exist_ok.

from pathlib import Path

# Create a single directory
p = Path("output")
p.mkdir()

# Create nested directories, no error if they already exist
nested = Path("data/reports/2026")
nested.mkdir(parents=True, exist_ok=True)
print("Directories ready.")

Expected output:

Directories ready.

Notice that parents=True in pathlib corresponds to the recursive behavior of os.makedirs(). Without parents=True, Path.mkdir() behaves like os.mkdir() and raises FileNotFoundError if any parent directory is missing.

The Path class has a built-in method for checking whether a path exists and is a directory. This can be useful before performing operations that require the directory to be present.

from pathlib import Path

p = Path("output")

# Create only if absent
if not p.is_dir():
    p.mkdir()
    print("Created output/")
else:
    print("output/ already exists.")

"The aim of this library is to provide a simple hierarchy of classes to handle filesystem paths and the common operations users do over them." — Antoine Pitrou, PEP 428 — The pathlib module (Python Software Foundation, 2012)

One important version detail: exist_ok was added to os.makedirs() in Python 3.2, but it was not added to Path.mkdir() until Python 3.5. If you are writing code that must target Python 3.4 specifically, use os.makedirs() with exist_ok=True rather than Path.mkdir(exist_ok=True). In any Python 3.5 or later environment — which is everything in current practice — both work identically.

Both os.mkdir() and Path.mkdir() accept an optional mode parameter that specifies the permission bits for the new directory. The default is 0o777, which is then modified by the process's current umask.

import os
from pathlib import Path

# Create a directory readable/writable/executable only by the owner (Unix)
os.mkdir("private_data", mode=0o700)

# Same with pathlib
Path("secure_logs").mkdir(mode=0o700, exist_ok=True)

The Python documentation explicitly warns that os.makedirs() will become confused if any path element in the chain is .. (the parent-directory reference, equivalent to os.pardir). The confusion arises because os.makedirs() strips path components one at a time from the right to find what it needs to create, and a .. component causes that traversal to produce incorrect results. For example, os.makedirs("a/b/../c") may attempt to create paths in the wrong order or raise errors unexpectedly. This is an officially documented limitation that has been present since the function was introduced. The fix is to normalize the path before passing it: use Path("a/b/../c").resolve() or os.path.abspath("a/b/../c"), both of which expand the path to its canonical form first.

os module vs. pathlib — side-by-side comparison

The table below compares the two approaches across key scenarios. Click any row to see a short explanation.

Absolute Paths vs Relative Paths

Every example so far has used a name like "output" or "data/reports/2026" — these are relative paths. A relative path is resolved from the process's current working directory, which is wherever your terminal was when you ran the script, not where the script file lives on disk. An absolute path starts from the filesystem root (/ on Unix, a drive letter on Windows) and means the same thing no matter where you run it from.

import os
from pathlib import Path

# Find out where Python thinks you currently are
print(os.getcwd())       # e.g. /home/user/projects
print(Path.cwd())        # same thing, as a Path object

# Relative path — resolved from cwd at runtime
os.makedirs("output/logs", exist_ok=True)
# If cwd is /home/user/projects this creates /home/user/projects/output/logs

# Absolute path — always the same regardless of cwd
os.makedirs("/tmp/myapp/logs", exist_ok=True)

Python handles spaces in directory names without any special syntax. You do not need to escape spaces or use quotes beyond the normal Python string rules. The only place spaces cause friction is when you reference the directory from a shell command — there you would need to quote the path. Inside Python code itself, spaces in directory names are just ordinary characters in a string.

import os
from pathlib import Path

# Spaces in names work fine in Python — no escaping needed
os.makedirs("my project/output files", exist_ok=True)

# pathlib handles it just as easily
Path("my project/output files").mkdir(parents=True, exist_ok=True)

# The / operator in pathlib also handles spaces correctly
base = Path("my project")
(base / "output files").mkdir(parents=True, exist_ok=True)

os.path.exists() vs os.path.isdir() — an important distinction

Many beginners reach for os.path.exists() to check whether a path is safe to use as a directory. This is a subtle bug waiting to happen. os.path.exists() returns True for anything at that path — a file, a directory, a symlink, a named pipe. os.path.isdir() returns True only when the path exists and is specifically a directory. If a file named output already exists and your code checks os.path.exists("output") before deciding whether to create the directory, it will skip creation, then fail later when it tries to write files into a path that is actually a file.

import os
from pathlib import Path

# Imagine "output" already exists as a FILE (not a directory)
os.path.exists("output")   # True  — but it's a file!
os.path.isdir("output")    # False — correctly identifies it is not a directory

Path("output").exists()    # True  — same issue
Path("output").is_dir()    # False — correct

# The safest approach: skip the check entirely and use exist_ok=True.
# exist_ok=True still raises OSError if a *file* is in the way,
# which is exactly the behavior you want.
os.makedirs("output", exist_ok=True)  # Raises OSError if "output" is a file

Creating a directory is only the first step. A complete understanding of directory operations in Python means knowing how to list its contents, write files into it, rename or move it, and remove it when it is no longer needed.

Listing directory contents

os.listdir() returns a plain list of name strings with no guaranteed order. Path.iterdir() returns an iterator of Path objects — more useful when you need to do anything with the items beyond printing their names, because you get type-checking methods like .is_dir() and .is_file() directly on each result.

import os
from pathlib import Path

# os.listdir() — list of name strings, no guaranteed order
names = os.listdir("output")
print(names)  # ['report.txt', 'data.csv', 'archive']

# Path.iterdir() — iterator of Path objects, sorted here for readability
p = Path("output")
for item in sorted(p.iterdir()):
    kind = "DIR " if item.is_dir() else "FILE"
    print(f"  {kind}  {item.name}")

Writing a file into a newly created directory

The most common next step after creating a directory is writing a file into it. With pathlib, this is a single readable chain: create the directory, build the file path with the / operator, then call .write_text() or use open() normally.

from pathlib import Path

output_dir = Path("output/reports")
output_dir.mkdir(parents=True, exist_ok=True)

# Write a text file directly into the new directory
report = output_dir / "summary.txt"
report.write_text("Report generated.\n", encoding="utf-8")

# Or use open() the standard way
with open(output_dir / "log.txt", "w", encoding="utf-8") as f:
    f.write("Log entry.\n")

print(f"Files written to {output_dir.resolve()}")

Renaming and moving a directory

To rename a directory in the same parent, use Path.rename() or os.rename(). To move it to a different location — including across drives — use shutil.move(). The key difference: os.rename() is atomic but only works within the same filesystem. shutil.move() handles cross-device moves by falling back to copy-then-delete, making it the safe universal choice.

import shutil
from pathlib import Path

# Rename within the same parent — returns the new Path object (Python 3.8+)
old = Path("output")
new = old.rename("output_archive")

# Move to a different location, including across filesystems
shutil.move(new, Path("/tmp/backup/output_archive"))

Deleting a directory

Python provides three deletion tools. os.rmdir() and Path.rmdir() remove a single empty directory — both raise OSError if any files or subdirectories remain inside. os.removedirs() walks upward through the path removing empty parents until it hits one that is not empty. shutil.rmtree() deletes a directory and everything inside it recursively. It has no undo — nothing goes to a trash folder.

import os
import shutil
from pathlib import Path

# Remove a single EMPTY directory
os.rmdir("empty_folder")       # raises OSError if not empty
Path("empty_folder").rmdir()   # same rule — must be empty

# Remove a chain of empty parent directories upward
os.removedirs("parent/child/grandchild")

# Remove a directory AND everything inside it — PERMANENT, no undo
shutil.rmtree("output_v1")

# Safer pattern: check before deleting recursively
target = Path("output_v1")
if target.is_dir():
    shutil.rmtree(target)
    print(f"Deleted {target}")

On Windows, paths use backslash (\) as the separator; on macOS and Linux they use forward slash (/). Hardcoding either separator in string literals is a fast way to create code that only works on one platform. The pathlib / operator always produces the correct separator for the current OS automatically.

from pathlib import Path
import os

# Works identically on Windows, macOS, and Linux
target = Path("data") / "reports" / "2026"
target.mkdir(parents=True, exist_ok=True)

# os.path.join() is the os-module equivalent — also cross-platform
os.makedirs(os.path.join("data", "reports", "2026"), exist_ok=True)

# Avoid hardcoded separators — these break on the wrong platform:
# os.makedirs("data\\reports\\2026")  # fails on Unix
# os.makedirs("data/reports/2026")    # works on both but pathlib is cleaner

Here is a complete, production-ready pattern that combines all five steps using pathlib:

from pathlib import Path

def ensure_directory(path_str: str) -> Path:
    """Create a directory (and any parents) if it does not exist.
    Returns the Path object on success.
    """
    p = Path(path_str)
    try:
        p.mkdir(parents=True, exist_ok=True)
    except PermissionError as e:
        raise RuntimeError(f"Permission denied: cannot create {p}") from e
    return p

# Usage
output_dir = ensure_directory("data/reports/2026")
print(f"Ready: {output_dir}")
print(f"Is a directory: {output_dir.is_dir()}")

Guided Exercise: Build a Project Folder Structure from Scratch

This exercise walks you through every step of building a real directory structure using Python — from opening a blank file to verifying the result. Follow each step in order on your own machine. By the end, you will have created a six-folder project layout, written a file into it, verified it exists, and cleaned up after yourself.

Step 1 — Create a new Python file

Open your text editor or terminal. Create a new file called build_project.py in any folder you can easily find — your Desktop or a practice/ folder works well. Leave it empty for now.

Step 2 — Check where you are before you start

Add the following to build_project.py and run it first:

from pathlib import Path

# Step 2: Confirm where your script will create folders
print("Working directory:", Path.cwd())

Run it: python3 build_project.py

Expected output (the exact path will be your own):

Working directory: /Users/yourname/practice

This confirms Python will create your folders relative to that location. If you see a path you did not expect, cd to the folder containing build_project.py before continuing.

Step 3 — Create the full directory tree in one call

Replace the contents of build_project.py with the code below, then run it:

from pathlib import Path

# Step 3: Create the full project directory tree
base = Path("my_project")

folders = [
    base / "data" / "raw",
    base / "data" / "processed",
    base / "output" / "reports",
    base / "logs",
]

for folder in folders:
    folder.mkdir(parents=True, exist_ok=True)
    print(f"  Created: {folder}")

print("Done.")

Expected output:

  Created: my_project/data/raw
  Created: my_project/data/processed
  Created: my_project/output/reports
  Created: my_project/logs
Done.

Open your file manager (or run find my_project in the terminal) and you will see the full nested tree. Run the script a second time — you will see the same output and no errors, because exist_ok=True makes the operation safe to run repeatedly.

Step 4 — Verify the structure in code

Add a verification step that confirms each folder exists before you try to use it:

from pathlib import Path

base = Path("my_project")

# Step 4: Verify each folder exists and is a directory
for folder in sorted(base.rglob("*")):
    if folder.is_dir():
        print(f"  OK  {folder}")

Expected output:

  OK  my_project/data
  OK  my_project/data/processed
  OK  my_project/data/raw
  OK  my_project/logs
  OK  my_project/output
  OK  my_project/output/reports

Step 5 — Write a file into the project

from pathlib import Path

base = Path("my_project")

# Step 5: Write a README into the project root
readme = base / "README.txt"
readme.write_text("My project folder. Created with Python.\n", encoding="utf-8")
print(f"Wrote: {readme}")
print(f"Contents: {readme.read_text(encoding='utf-8')}")

Expected output:

Wrote: my_project/README.txt
Contents: My project folder. Created with Python.

Step 6 — List all contents including files

from pathlib import Path

base = Path("my_project")

# Step 6: List everything — files and folders
for item in sorted(base.rglob("*")):
    kind = "[DIR] " if item.is_dir() else "[FILE]"
    print(f"  {kind} {item}")

Expected output:

  [FILE] my_project/README.txt
  [DIR]  my_project/data
  [DIR]  my_project/data/processed
  [DIR]  my_project/data/raw
  [DIR]  my_project/logs
  [DIR]  my_project/output
  [DIR]  my_project/output/reports

Step 7 — Clean up (optional)

When you are finished practicing, run this to delete the entire my_project tree:

import shutil
from pathlib import Path

# Step 7: Remove the entire project tree (permanent — no undo)
target = Path("my_project")
if target.is_dir():
    shutil.rmtree(target)
    print(f"Deleted {target} and all its contents.")
else:
    print(f"{target} does not exist — nothing to delete.")

Expected output:

Deleted my_project and all its contents.

Real-World Directory Patterns You Won't Find Everywhere

The three core functions cover most cases, but production Python code regularly needs patterns beyond a bare mkdir call. Here are the ones that distinguish scripts that work reliably from scripts that fail in the field.

Temporary directories that clean themselves up

When your code needs a scratch space that must not persist after the script exits — for intermediate build artifacts, test fixtures, or untrusted data — use tempfile.TemporaryDirectory from the standard library. It creates a uniquely named directory in the system's temp location and deletes it automatically when the context manager exits, even if an exception is raised.

import tempfile
from pathlib import Path

with tempfile.TemporaryDirectory() as tmp:
    tmp_path = Path(tmp)
    # Do work inside the temp directory
    work_file = tmp_path / "intermediate.txt"
    work_file.write_text("processing...", encoding="utf-8")
    print(f"Working in: {tmp_path}")
    # tmp_path is automatically deleted when the 'with' block exits
    # even if an exception occurs inside it

print("Temp directory has been removed.")

Ensuring a project directory tree exists at startup

Scripts that write output files often need to guarantee a set of directories exists before they begin. The pattern below is idiomatic in CLI tools, data pipelines, and test setups. Calling it once at startup is safer than scattering mkdir calls throughout the code, because any permission failure surfaces early and clearly rather than mid-run.

from pathlib import Path

# Define your project layout as a list
REQUIRED_DIRS = [
    "output/reports",
    "output/logs",
    "output/tmp",
    "data/raw",
    "data/processed",
]

def init_workspace(base: Path = Path(".")) -> None:
    """Create all required directories if they don't already exist."""
    for rel in REQUIRED_DIRS:
        target = base / rel
        try:
            target.mkdir(parents=True, exist_ok=True)
        except PermissionError as e:
            raise RuntimeError(f"Cannot create required directory {target}: {e}") from e
    print(f"Workspace initialized under {base.resolve()}")

init_workspace()

Atomic directory creation: detecting a truly new directory

There is one scenario where you specifically do not want exist_ok=True: when your application's logic depends on knowing whether it was the process that created the directory, as opposed to finding a directory that already existed. This comes up in distributed systems, job schedulers, and file-based locking. Without exist_ok=True, os.mkdir() raises FileExistsError only when the directory already exists — making it a single-call ownership signal.

import os

JOB_LOCK_DIR = "/tmp/myjob.lock"

try:
    os.mkdir(JOB_LOCK_DIR)
    # Only this process reaches here — it "owns" the lock
    print("Lock acquired. Running exclusive job...")
    # ... do exclusive work ...
except FileExistsError:
    print("Another process is already running. Exiting.")
finally:
    # Clean up the lock directory when done
    try:
        os.rmdir(JOB_LOCK_DIR)
    except OSError:
        pass  # Already removed or never created

"The os module provides a portable way of using operating system dependent functionality." — Python Software Foundation, os module documentation

This directory-as-lock pattern works because on all POSIX-compliant systems and on modern Windows, mkdir is atomic at the kernel level: exactly one process succeeds, and all others get an error. It is not a replacement for proper inter-process locking libraries in complex systems, but for simple scripts it is a well-understood and dependency-free approach.

Getting the directory a script lives in

A frequent beginner stumbling block is creating a directory relative to the wrong path. When a Python script runs, its working directory is wherever the terminal was when the script was invoked — not where the script file lives. To create a directory next to the script file itself, resolve the script's own location using __file__.

from pathlib import Path

# Path to the directory this script lives in
script_dir = Path(__file__).parent.resolve()

# Create an "output" folder next to the script, not next to wherever
# the terminal happens to be when the script runs
output_dir = script_dir / "output"
output_dir.mkdir(exist_ok=True)

print(f"Output will be written to: {output_dir}")

Python Learning Summary Points

1. os.mkdir() creates a single directory and requires all parent directories to exist already. It raises FileExistsError if the directory is already present and FileNotFoundError if a parent is missing.
2. os.makedirs() creates a full directory path including any missing intermediate directories — equivalent to mkdir -p. Passing exist_ok=True makes the call safe to run repeatedly without raising an error. The exist_ok parameter was added in Python 3.2.
3. pathlib's Path.mkdir(parents=True, exist_ok=True) is the modern, object-oriented equivalent. It is preferred in contemporary Python code because Path objects integrate naturally with the rest of the pathlib API. Under the hood in CPython, Path.mkdir() calls os.mkdir() directly. The exist_ok parameter on Path.mkdir() was added in Python 3.5.
4. The mode parameter sets Unix permission bits, but the final permissions are mode & ~umask — a bitwise AND with the umask complement, not plain subtraction. If the parent directory has a default ACL set, the umask is bypassed entirely and the ACL is inherited instead. On Windows, mode has no effect except for 0o700 handling, backported to Python 3.8 through 3.12 as a fix for CVE-2024-4030. Since Python 3.7, the mode argument in os.makedirs() only applies to the leaf directory — intermediate directories use the process default. Before Python 3.4.1, passing exist_ok=True to makedirs() would still raise an error if the existing directory's mode did not match the requested mode; this behavior was removed in 3.4.1 (bpo-21082) because it could not be implemented safely.
5. Always handle PermissionError separately. A missing directory is recoverable; a permissions failure requires a different response. Avoid passing paths containing .. to os.makedirs() — the official documentation explicitly warns that the function will become confused by parent-directory traversal components; normalize first with Path.resolve().
6. Using exist_ok=True is safer than checking with is_dir() first, because the check-then-create pattern introduces a TOCTOU race condition. exist_ok=True makes the operation atomic from Python's perspective.
7. For temporary scratch space, use tempfile.TemporaryDirectory as a context manager — it guarantees cleanup on exit even when exceptions occur. For directories that must persist, use Path(__file__).parent.resolve() to anchor paths to the script location rather than the terminal's working directory.
8. Relative paths resolve from the current working directory — use os.getcwd() or Path.cwd() to see where that is. Absolute paths resolve the same way every time. Always use os.path.isdir() or Path.is_dir() rather than os.path.exists() when checking for a directory specifically.
9. To delete a directory, use os.rmdir() or Path.rmdir() for empty directories, and shutil.rmtree() for recursive deletion. To rename, use Path.rename() or os.rename(). To move across filesystems, use shutil.move(). Use pathlib's / operator or os.path.join() to build paths — never hardcode separators.

Knowing when to use os.mkdir() versus os.makedirs() versus Path.mkdir() comes down to one question: do you need to create intermediate directories, and are you working in a code base that already uses pathlib for path handling? If intermediate directories may not exist, always choose the recursive option and always pass exist_ok=True unless you specifically need to detect an existing directory as an error condition.

Sources

Every technical claim in this article is verifiable against the following primary sources:

• Python Software Foundation. os — Miscellaneous operating system interfaces. Python 3 documentation. docs.python.org/3/library/os.html
• Python Software Foundation. pathlib — Object-oriented filesystem paths. Python 3 documentation. docs.python.org/3/library/pathlib.html
• Pitrou, Antoine. PEP 428 — The pathlib module — object-oriented filesystem paths. Python Software Foundation, 2012. peps.python.org/pep-0428/
• Python Software Foundation. What's New In Python 3.4. Python documentation. docs.python.org/dev/whatsnew/3.4.html
• CPython project. Lib/pathlib.py. GitHub. github.com/python/cpython
• Python Software Foundation. tempfile — Generate temporary files and directories. Python 3 documentation. docs.python.org/3/library/tempfile.html
• Python Software Foundation. shutil — High-level file operations. Python 3 documentation. docs.python.org/3/library/shutil.html