0
# PyExifTool
1
2
A Python library that provides a wrapper interface to communicate with Phil Harvey's ExifTool command-line application for extracting and manipulating metadata from image, video, and other media files. PyExifTool runs ExifTool in batch mode for efficient processing of multiple files and supports reading and writing EXIF, IPTC, XMP, and other metadata formats.
3
4
## Package Information
5
6
- **Package Name**: PyExifTool
7
- **Language**: Python
8
- **Installation**: `pip install PyExifTool`
9
- **Minimum Python Version**: 3.6+
10
- **External Dependency**: Requires Phil Harvey's ExifTool command-line application
11
12
## Core Imports
13
14
```python
15
import exiftool
16
```
17
18
Common pattern for helper class:
19
20
```python
21
from exiftool import ExifToolHelper
22
```
23
24
Low-level access:
25
26
```python
27
from exiftool import ExifTool
28
```
29
30
Exception handling:
31
32
```python
33
from exiftool import exceptions
34
```
35
36
## Basic Usage
37
38
```python
39
import exiftool
40
41
# Recommended approach using ExifToolHelper
42
files = ["image1.jpg", "image2.png", "video.mp4"]
43
44
with exiftool.ExifToolHelper() as et:
45
# Get all metadata
46
metadata = et.get_metadata(files)
47
for data in metadata:
48
print(f"File: {data['SourceFile']}")
49
print(f"Date: {data.get('EXIF:DateTimeOriginal', 'N/A')}")
50
51
# Get specific tags
52
tags = et.get_tags(files, ['EXIF:Make', 'EXIF:Model'])
53
54
# Set tags
55
et.set_tags('image.jpg', {'EXIF:Artist': 'John Doe'})
56
57
# Low-level approach for advanced usage
58
with exiftool.ExifTool() as et:
59
# Execute direct exiftool commands
60
result = et.execute_json('-j', 'image.jpg')
61
62
# Execute raw commands
63
output = et.execute('-n', '-g', 'image.jpg')
64
```
65
66
## Architecture
67
68
PyExifTool provides three main classes for different use cases:
69
70
- **ExifTool**: Core low-level interface that manages the exiftool subprocess and provides direct command execution
71
- **ExifToolHelper**: User-friendly wrapper that adds convenience methods, error checking, and auto-start functionality
72
- **ExifToolAlpha**: Experimental class with additional specialized functionality for niche use cases
73
74
The library runs ExifTool in batch mode using subprocess communication, keeping a single ExifTool process running for multiple operations to maximize performance. All classes support context manager patterns for automatic resource management.
75
76
## Capabilities
77
78
### Core Interface
79
80
Low-level interface to the exiftool subprocess with direct command execution, JSON parsing, and subprocess lifecycle management. Provides maximum control and flexibility for advanced users.
81
82
```python { .api }
83
class ExifTool:
84
def __init__(self, executable=None, common_args=None, win_shell=False, config_file=None, encoding=None, logger=None): ...
85
def run(self): ...
86
def terminate(self, timeout=30, _del=False): ...
87
def execute(self, *params, raw_bytes=False): ...
88
def execute_json(self, *params): ...
89
```
90
91
[Core Interface](./core-interface.md)
92
93
### Helper Interface
94
95
User-friendly wrapper with convenience methods for common metadata operations, automatic error checking, and simplified file handling. Recommended for most users.
96
97
```python { .api }
98
class ExifToolHelper(ExifTool):
99
def __init__(self, auto_start=True, check_execute=True, check_tag_names=True, **kwargs): ...
100
def get_metadata(self, files, params=None): ...
101
def get_tags(self, files, tags, params=None): ...
102
def set_tags(self, files, tags, params=None): ...
103
```
104
105
[Helper Interface](./helper-interface.md)
106
107
### Experimental Features
108
109
Experimental functionality for specialized use cases including batch operations, keyword management, and file-to-file tag copying.
110
111
```python { .api }
112
class ExifToolAlpha(ExifToolHelper):
113
def get_tag(self, filename, tag): ...
114
def copy_tags(self, from_filename, to_filename): ...
115
def set_keywords(self, filename, mode, keywords): ...
116
```
117
118
[Experimental Features](./experimental-features.md)
119
120
### Exception Handling
121
122
Comprehensive exception hierarchy for different error conditions with detailed error information including exit codes and command output.
123
124
```python { .api }
125
class ExifToolException(Exception): ...
126
class ExifToolProcessStateError(ExifToolException): ...
127
class ExifToolExecuteException(ExifToolException): ...
128
class ExifToolRunning(ExifToolProcessStateError): ...
129
class ExifToolNotRunning(ExifToolProcessStateError): ...
130
class ExifToolExecuteError(ExifToolExecuteException): ...
131
class ExifToolOutputEmptyError(ExifToolExecuteException): ...
132
class ExifToolJSONInvalidError(ExifToolExecuteException): ...
133
class ExifToolVersionError(ExifToolException): ...
134
class ExifToolTagNameError(ExifToolException): ...
135
```
136
137
[Exception Handling](./exception-handling.md)
138
139
### Constants and Version
140
141
Package version and platform-specific constants for advanced configuration.
142
143
```python { .api }
144
__version__ = "0.5.6"
145
146
# Platform detection
147
PLATFORM_WINDOWS: bool
148
PLATFORM_LINUX: bool
149
150
# Executable and configuration defaults
151
DEFAULT_EXECUTABLE = "exiftool"
152
DEFAULT_BLOCK_SIZE = 4096
153
EXIFTOOL_MINIMUM_VERSION = "12.15"
154
155
# Platform-specific constants
156
SW_FORCEMINIMIZE = 11 # Windows show window constant
157
PR_SET_PDEATHSIG = 1 # Linux process death signal constant
158
```
159
160
## Types
161
162
```python { .api }
163
# Type aliases for documentation
164
FilePath = Union[str, Path]
165
FileList = Union[FilePath, List[FilePath]]
166
TagDict = Dict[str, Any]
167
MetadataList = List[TagDict]
168
ParamsList = Optional[Union[str, List[str]]]
169
```