Pages

Topics

Tools

↑↓navigate↵openescclose
All guides

Python FileNotFoundError: Causes and Fixes

Learn why Python raises FileNotFoundError, how to handle it with try/except, and how pathlib helps you avoid path mistakes.

~6 min readPython
#FileNotFoundError#Python exception handling#pathlib#file I/O
Illustration of a magnifying glass over a folder with a missing file icon, representing Python FileNotFoundError

Python raises FileNotFoundError when a file operation targets a path that does not exist. This error appears in scripts, web applications, and data pipelines, often because the working directory differs from the expected location or because a file was removed between a check and an access. Understanding the root cause is the first step toward writing reliable file-handling code.

What Causes FileNotFoundError in Python

The error is a subclass of OSError and is raised by built-in functions like open() and standard-library functions like os.remove() and os.rename() when the referenced path cannot be found. The most common triggers are:

  • A typo in the filename or directory name.
  • The file exists but is located in a different directory than the one Python is searching.
  • The current working directory (CWD) is not what the developer assumes.
  • The file was deleted or moved after the program started.
  • Permissions prevent the process from seeing the file, although that often raises PermissionError instead.

The error message includes the path that failed, for example:

text
FileNotFoundError: [Errno 2] No such file or directory: 'data.csv'

This message tells you the exact path Python tried to open. If the path is relative, it is resolved against the current working directory.

The Role of the Current Working Directory

Python resolves relative paths against the process's current working directory. When you run a script from the command line, the CWD is usually the directory where you typed the command, not necessarily the directory containing the script. This mismatch is a frequent source of FileNotFoundError.

Consider this project structure:

code
project/ scripts/ load_data.py data/ input.csv

If you run python scripts/load_data.py from the project directory, the CWD is project. A relative path like 'data/input.csv' works. But if you run the script from inside scripts with python load_data.py, the same relative path resolves to scripts/data/input.csv, which does not exist.

To make the script independent of where it is invoked, build paths relative to the script's location using __file__:

python
from pathlib import Path script_dir = Path(__file__).resolve().parent data_file = script_dir / ".." / "data" / "input.csv"

This approach keeps the path correct as long as the file structure remains intact.

Handling FileNotFoundError with try/except

The most direct way to handle a missing file is to catch the exception. This is appropriate when the file's absence is an expected condition, such as a user-supplied path or an optional configuration file.

python
import json try: with open("config.json") as f: config = json.load(f) except FileNotFoundError: config = {}

Catching the error lets you provide a fallback or a clear message. However, you should not catch it blindly. If the file is essential and its absence indicates a broken installation, it may be better to let the exception propagate so the failure is visible.

When you catch FileNotFoundError, you can also inspect the errno attribute to identify the standard error code. For example, errno.ENOENT is the code for "No such file or directory." Use the path in the error message or the exception's filename attribute when diagnosing the cause.

Using pathlib to Avoid Path Mistakes

The pathlib module, introduced in Python 3.4, provides an object-oriented way to handle filesystem paths. It eliminates many string-concatenation errors and makes path operations more readable.

python
from pathlib import Path path = Path("data") / "input.csv" if path.exists(): with path.open() as f: content = f.read() else: print(f"File {path} not found.")

The / operator joins path components safely, and Path.exists() checks whether the path points to an existing file or directory. pathlib also offers Path.is_file() to verify that the path is a file and not a directory.

Using pathlib does not prevent FileNotFoundError by itself; you still need to check existence or handle the exception. But it reduces the chance of constructing an incorrect path in the first place.

Checking File Existence Before Access

A common pattern is to check whether a file exists before opening it:

python
import os if os.path.exists("data.csv"): with open("data.csv") as f: data = f.read() else: print("File not found.")

This works, but it introduces a race condition: the file could be deleted between the exists() check and the open() call. In a single-threaded script this is unlikely, but in a multi-threaded or multi-process environment it is possible. For critical operations, prefer a try/except block because it handles the race condition gracefully.

Another subtle issue is that os.path.exists() returns False for broken symbolic links, even if the link itself exists. If you need to distinguish between a missing file and a broken link, use os.path.lexists(), or check Path.is_symlink() to detect the link itself.

Handling Missing Files in Production Code

In production systems, FileNotFoundError often indicates a configuration problem or a deployment error. A robust approach is to log the error with enough context and then take an appropriate action, such as retrying with a different path or alerting an operator.

python
import logging logger = logging.getLogger(__name__) try: with open("/etc/app/settings.yaml") as f: settings = yaml.safe_load(f) except FileNotFoundError as e: logger.error("Configuration file missing: %s", e.filename) raise

Raising the exception after logging preserves the original error for the caller. This is better than swallowing the exception and silently using defaults, which can hide serious problems.

If the file is optional, you can log a warning and continue. If it is required, you should fail fast. The decision depends on the business logic, not on the exception itself.

Common Pitfalls and Edge Cases

Several edge cases can cause FileNotFoundError even when you think the path is correct:

  • Trailing whitespace: A filename like "data.txt " (with a trailing space) is different from "data.txt". This often happens when reading filenames from user input or a configuration file.
  • Case sensitivity: Case sensitivity depends on the filesystem, not just the operating system. Linux filesystems are often case-sensitive by default. macOS and Windows filesystems are usually case-insensitive, but case-sensitive configurations exist. "Data.csv" and "data.csv" may or may not be different files.
  • Unicode normalization: macOS often stores filenames in NFD normalization, while a Python string may be in NFC. This can make a file appear missing if the name contains accented characters.
  • Symlinks: A broken symbolic link raises FileNotFoundError when you try to open it, even though the link itself exists. Use Path.is_symlink() to detect this case.
  • Directory vs. file: Opening a directory with open() raises IsADirectoryError, which is a subclass of OSError but not FileNotFoundError. Check with Path.is_file() if you expect a regular file.

When dealing with user-supplied paths, validate them early and provide clear error messages. For example:

python
from pathlib import Path user_path = Path(input("Enter file path: ")).expanduser() if not user_path.is_file(): raise SystemExit(f"No such file: {user_path}")

Using expanduser() expands ~ to the user's home directory, which is useful when users type a path that begins with ~.

When to Let the Exception Propagate

Not every FileNotFoundError should be caught. If the file is a core dependency of your application, catching it and continuing with a default value can lead to subtle bugs later. For example, a missing model file in a machine learning service should stop the service startup rather than silently using an empty model.

In such cases, let the exception propagate and handle it at a higher level, such as a global exception handler or a CLI entry point. This makes the failure visible and actionable.

A practical rule is: catch FileNotFoundError only when you have a concrete fallback behavior. If you do not know what to do without the file, do not catch it.

Using contextlib.suppress for Optional Files

When a file is truly optional and you want to ignore its absence, contextlib.suppress provides a concise way to do so:

python
import os from contextlib import suppress with suppress(FileNotFoundError): os.remove("temp_cache.pkl")

This is equivalent to a try/except block with pass, but it reads more cleanly. Use it only when ignoring the error is the intended behavior, not as a way to hide bugs.

Path Resolution and Environment

In containerized applications, the working directory is often set by the Dockerfile or orchestration tool. A path that works locally may fail in production because the CWD differs. Always prefer absolute paths derived from environment variables or configuration files, and avoid relying on the CWD for critical files.

For example, you can use an environment variable to specify the data directory:

python
import os from pathlib import Path data_dir = Path(os.environ.get("DATA_DIR", "data")) file_path = data_dir / "input.csv"

This makes the behavior explicit and testable. When you run tests, you can set DATA_DIR to a temporary directory, and in production you can point it to a mounted volume.

FileNotFoundError is not just a beginner's mistake; it is a runtime condition that every Python developer must handle deliberately. By understanding how paths are resolved, using pathlib for clarity, and choosing the right error-handling strategy, you can make your file operations robust across different environments.

Try matching browser tools

All tools

Small utilities that fit Python work — they run entirely in this browser tab, so nothing you paste leaves your device.

All Python guides

More in Python

All Python guides

The guides filed next to this one in Python, in library order.