Python os.truncate Function

Last modified April 11, 2025

This comprehensive guide explores Python’s os.truncate function, which modifies file size by truncating or extending it. We’ll cover usage scenarios, permission requirements, and practical examples.

Basic Definitions

The os.truncate function changes the size of a file to the specified length. If the file is extended, new bytes are filled with zeros.

Key parameters: path (file to modify), length (new size in bytes). Requires write permission on the file. Works on regular files, not directories.

Truncating a File to Smaller Size

The most common use of os.truncate is reducing file size by discarding content beyond the specified length. This example demonstrates basic truncation.

basic_truncate.py

import os

Create a sample file

file_path = “data.txt” with open(file_path, “w”) as f: f.write(“This is some sample text for truncation demonstration.”)

Check original size

original_size = os.path.getsize(file_path) print(f"Original size: {original_size} bytes")

Truncate to 20 bytes

os.truncate(file_path, 20) new_size = os.path.getsize(file_path) print(f"New size: {new_size} bytes")

Verify content

with open(file_path) as f: print(f"Content: ‘{f.read()}’")

This creates a file, then truncates it to 20 bytes. The remaining content will be the first 20 bytes of the original text.

Note that truncation happens immediately at the filesystem level, without needing to reopen the file.

Extending a File with Zeros

When specifying a length larger than the current file size, os.truncate extends the file by padding with null bytes. This example shows file extension.

extend_file.py

import os

file_path = “empty.dat”

Create empty file

with open(file_path, “w”): pass

Extend file to 1KB (1024 bytes)

os.truncate(file_path, 1024) size = os.path.getsize(file_path) print(f"File size after extension: {size} bytes")

Verify content is null bytes

with open(file_path, “rb”) as f: content = f.read(16) # Read first 16 bytes print(f"First 16 bytes: {content}")

This creates an empty file, then extends it to 1024 bytes. The new space is filled with zeros. Binary mode is used to read the null bytes.

File extension is useful for preallocating space or creating sparse files.

Truncating Open File Descriptors

os.ftruncate works similarly but operates on an open file descriptor instead of a path. This example shows both functions for comparison.

fd_truncate.py

import os

file_path = “log.txt”

Using os.truncate with path

with open(file_path, “w”) as f: f.write(“Initial content for truncation test”)

os.truncate(file_path, 10) print(f"After path truncate: {os.path.getsize(file_path)} bytes")

Using os.ftruncate with file descriptor

with open(file_path, “r+”) as f: fd = f.fileno() os.ftruncate(fd, 5) print(f"After fd truncate: {os.path.getsize(file_path)} bytes")

Both functions achieve the same result but take different parameters. os.ftruncate requires an open file descriptor.

The file must be opened in a mode that allows writing for os.ftruncate.

Error Handling

os.truncate can raise various exceptions. This example demonstrates proper error handling for common scenarios.

error_handling.py

import os import errno

file_path = “protected.txt”

try: # Attempt to truncate a non-existent file os.truncate(“nonexistent.txt”, 100) except FileNotFoundError: print(“Error: File not found”)

try: # Attempt to truncate without permissions os.truncate("/root/protected.txt", 100) except PermissionError: print(“Error: Permission denied”)

try: # Attempt to truncate a directory os.truncate("/tmp", 100) except IsADirectoryError: print(“Error: Cannot truncate a directory”)

try: # Invalid length os.truncate(file_path, -1) except OSError as e: if e.errno == errno.EINVAL: print(“Error: Invalid length specified”)

This shows handling for file not found, permission issues, directory truncation, and invalid length parameters. Each case raises a different exception.

Always validate inputs and handle potential errors when working with filesystem operations.

Combining with Other File Operations

os.truncate can be combined with other file operations for more complex workflows. This example shows integration with file reading.

combined_operations.py

import os

file_path = “data.bin”

Create binary file with some data

with open(file_path, “wb”) as f: f.write(b"\x01\x02\x03\x04\x05\x06\x07\x08")

Truncate to remove last 4 bytes

os.truncate(file_path, 4)

Read remaining content

with open(file_path, “rb”) as f: content = f.read() print(f"Remaining bytes: {content}") print(f"Size after truncate: {len(content)} bytes")

Extend file and verify

os.truncate(file_path, 8) with open(file_path, “rb”) as f: content = f.read() print(f"Extended bytes: {content}") print(f"Size after extension: {len(content)} bytes")

This creates a binary file, truncates it, then extends it while verifying the content at each step. The null bytes added during extension are visible.

Binary mode is essential when working with non-text data or examining the actual bytes added during extension.

Performance Considerations

This example benchmarks os.truncate against alternative methods of file size modification to demonstrate performance characteristics.

performance_test.py

import os import timeit

file_path = “large_file.bin” size_mb = 10 # 10MB file test_size = 5 # Truncate to 5MB

def create_large_file(): with open(file_path, “wb”) as f: f.seek(size_mb * 1024 * 1024 - 1) f.write(b"\0")

def method_truncate(): os.truncate(file_path, test_size * 1024 * 1024)

def method_write(): with open(file_path, “r+”) as f: f.truncate(test_size * 1024 * 1024)

Setup

create_large_file()

Benchmark

truncate_time = timeit.timeit(method_truncate, number=100) write_time = timeit.timeit(method_write, number=100)

print(f"os.truncate average: {truncate_time/100:.6f}s") print(f"file.truncate average: {write_time/100:.6f}s")

Cleanup

os.remove(file_path)

This creates a large file, then compares truncation methods. os.truncate is generally faster as it operates at the filesystem level.

The performance difference becomes more significant with larger files and frequent truncation operations.

Security Considerations

• Permission requirements: Write permission on the file is required

• Data loss: Truncation permanently removes file content

• Race conditions: File may change between size check and truncation

• Symbolic links: Follows symlinks by default (use os.path.realpath)

• Cross-platform: Behavior consistent across Unix and Windows

Best Practices

• Backup important data: Before performing destructive operations

• Check file type: Verify it’s a regular file before truncating

• Handle errors: Implement proper exception handling

• Document size changes: Log truncation operations for audit

• Consider alternatives: For some cases, file.truncate() may be better

Source References

• Python os.truncate Documentation

• Linux truncate(2) man page

Author

My name is Jan Bodnar, and I am a passionate programmer with extensive programming experience. I have been writing programming articles since 2007. To date, I have authored over 1,400 articles and 8 e-books. I possess more than ten years of experience in teaching programming.

List all Python tutorials.