PyExifTool

https://sylikc.github.io/pyexiftool
Admin
PyExifTool is a Python library that communicates with Phil Harvey's ExifTool command-line...
Tokens:38,426
Snippets:371
Trust Score:8.3
Update:2 months ago
Show doc for...
Tokens:
Raw
### Install PyExifTool from Source

Source: https://sylikc.github.io/pyexiftool/installation.html

Install PyExifTool by cloning the source code from GitHub and running the setup script. Optional flags can specify user or prefix installation.

```bash
git clone git://github.com/sylikc/pyexiftool.git

```

```bash
python setup.py install [--user|--prefix=<installation-prefix>]

```

--------------------------------

### Install ExifTool on Ubuntu

Source: https://sylikc.github.io/pyexiftool/installation.html

Install the exiftool package on Ubuntu systems using apt. Ensure the installed version meets PyExifTool's minimum requirements.

```bash
sudo apt install libimage-exiftool-perl

```

--------------------------------

### Install ExifTool on CentOS/RHEL

Source: https://sylikc.github.io/pyexiftool/installation.html

Install the exiftool package on CentOS/RHEL systems using yum. Ensure the installed version meets PyExifTool's minimum requirements.

```bash
yum install perl-Image-ExifTool

```

--------------------------------

### exiftool.ExifToolHelper.run

Source: https://sylikc.github.io/pyexiftool/reference/2-helper.html

Overrides the `exiftool.ExifTool.run()` method. This method ensures that the ExifTool process is started and managed.

```APIDOC
## exiftool.ExifToolHelper.run

### Description
Override the `exiftool.ExifTool.run()` method. Will not attempt to run if already running (so no warning about ‘ExifTool already running’ will trigger).

### Return Type
None
```

--------------------------------

### Install PyExifTool from PyPI

Source: https://sylikc.github.io/pyexiftool/installation.html

Use pip to install the latest version of PyExifTool from the Python Package Index.

```python
python -m pip install -U pyexiftool

```

--------------------------------

### ExifToolHelper Constructor

Source: https://sylikc.github.io/pyexiftool/reference/2-helper.html

Initializes the ExifToolHelper class. It can automatically start the exiftool process, check command execution status, and validate tag names.

```APIDOC
## exiftool.ExifToolHelper.__init__

### Description
Initializes the ExifToolHelper class with options for automatic process startup, execution checking, and tag name validation.

### Parameters
* **auto_start** (bool) - Optional - Will automatically start the exiftool process on first command run, defaults to True.
* **check_execute** (bool) - Optional - Will check the exit status (return code) of all commands. This catches some invalid commands passed to exiftool subprocess, defaults to True.
* **check_tag_names** (bool) - Optional - Will check the tag names provided to methods which work directly with tag names. This catches unintended uses and bugs, default to True.
* **kwargs** - Optional - All other parameters are passed directly to the super-class constructor: `exiftool.ExifTool.__init__()`.

### Return Type
None
```

--------------------------------

### exiftool.ExifTool.run

Source: https://sylikc.github.io/pyexiftool/reference/1-exiftool.html

Starts an exiftool subprocess in batch mode. This method issues a UserWarning if the subprocess is already running. The process is started with common arguments, which are automatically included in every command executed.

```APIDOC
## exiftool.ExifTool.run

### Description
Start an `exiftool` subprocess in batch mode. This method will issue a `UserWarning` if the subprocess is already running (`running` == True). The process is started with `common_args` as common arguments, which are automatically included in every command you run with `execute()`.
```

--------------------------------

### run

Source: https://sylikc.github.io/pyexiftool/_sources/autoapi/exiftool/exiftool/index.rst.txt

Starts an exiftool subprocess in batch mode. It includes common arguments and can be configured via the constructor or by setting the `common_args` attribute before calling.

```APIDOC
## run()

### Description
Starts an exiftool subprocess in batch mode. It includes common arguments and can be configured via the constructor or by setting the `common_args` attribute before calling. Issues a UserWarning if the subprocess is already running.

### Method
`run`

### Parameters
None

### Request Example
```python
# Example usage (assuming exiftool_helper is an instance of ExifToolHelper)
# exiftool_helper.run()
```

### Response
None

### Raises
* **FileNotFoundError**: If *exiftool* is no longer found.
* **OSError**: Re-raised from subprocess.Popen().
* **ValueError**: Re-raised from subprocess.Popen().
* **subproccess.CalledProcessError**: Re-raised from subprocess.Popen().
* **RuntimeError**: Popen() launched process but it died right away.
* **ExifToolVersionError**: If the exiftool version is below the minimum required version.
```

--------------------------------

### auto_start Property

Source: https://sylikc.github.io/pyexiftool/reference/2-helper.html

A read-only property to get the current setting for whether auto_start is enabled.

```APIDOC
## exiftool.ExifToolHelper.auto_start

### Description
Gets the current setting passed into the constructor to determine if auto_start is enabled.

### Return Type
bool
```

--------------------------------

### run

Source: https://sylikc.github.io/pyexiftool/autoapi/exiftool/exiftool/index.html

Starts an `exiftool` subprocess in batch mode. This method will issue a `UserWarning` if the subprocess is already running (`running` == True). The process is started with `common_args` as common arguments, which are automatically included in every command you run with `execute()`. You can override these default arguments with the `common_args` parameter in the constructor or setting `common_args` before calling `run()`.

```APIDOC
## run()

### Description
Starts an exiftool subprocess in batch mode.

### Method
run

### Parameters
None

### Request Example
```python
# Example usage
# exiftool.run()
```

### Response
#### Success Response (200)
None (This method starts a subprocess and does not return data directly).

### Raises
* **FileNotFoundError**: If `exiftool` is no longer found.
* **OSError**: Re-raised from subprocess.Popen().
* **ValueError**: Re-raised from subprocess.Popen().
* **subproccess.CalledProcessError**: Re-raised from subprocess.Popen().
* **RuntimeError**: Popen() launched process but it died right away.
* **ExifToolVersionError**: `exiftool.constants.EXIFTOOL_MINIMUM_VERSION` not met. ExifTool process will be automatically terminated.
```

--------------------------------

### Matching ExifTool Output with PyExifTool (Option 1)

Source: https://sylikc.github.io/pyexiftool/_sources/faq.rst.txt

To match exiftool's output, enable print conversion on the command line. This example shows how to achieve that.

```text
[JFIF]          JFIF Version                    : 1 1
[JFIF]          Resolution Unit                 : 1
[JFIF]          X Resolution                    : 72
[JFIF]          Y Resolution                    : 72
```

--------------------------------

### SW_FORCEMINIMIZE

Source: https://sylikc.github.io/pyexiftool/_sources/autoapi/exiftool/constants/index.rst.txt

A Windows ShowWindow constant that dictates the initial state of a launched process window, specifically to start minimized.

```APIDOC
## SW_FORCEMINIMIZE

### Description
Windows ShowWindow constant from win32con

Indicates the launched process window should start minimized

### Type
int

### Value
11
```

--------------------------------

### ExifToolHelper Constructor

Source: https://sylikc.github.io/pyexiftool/autoapi/exiftool/helper/index.html

Initializes the ExifToolHelper class, extending the base ExifTool class with helper functions. It allows configuration of automatic process starting, execution status checking, and tag name validation.

```APIDOC
## ExifToolHelper Constructor

### Description
Initializes the ExifToolHelper class, extending the base ExifTool class with helper functions. It allows configuration of automatic process starting, execution status checking, and tag name validation.

### Parameters
* **auto_start** (bool) - Optional - Will automatically start the exiftool process on first command run, defaults to True.
* **check_execute** (bool) - Optional - Will check the exit status (return code) of all commands. This catches some invalid commands passed to exiftool subprocess, defaults to True.
* **check_tag_names** (bool) - Optional - Will check the tag names provided to methods which work directly with tag names. This catches unintended uses and bugs, default to True.
* **kwargs** - Optional - All other parameters are passed directly to the super-class constructor: `exiftool.ExifTool.__init__()`
```

--------------------------------

### Get Tags with Non-existent File (Helper)

Source: https://sylikc.github.io/pyexiftool/_sources/examples.rst.txt

Demonstrates `ExifToolHelper.get_tags` behavior when a non-existent file is included in the list. The helper raises an `ExifToolExecuteError`.

```python
from exiftool import ExifToolHelper
with ExifToolHelper() as et:
    print(et.get_tags(
        ["rose.jpg", "skyblue.png", "non-existent file.tif"],
        tags=["FileSize"]
    ))
```

--------------------------------

### Get Multiple Tags (Wrapper)

Source: https://sylikc.github.io/pyexiftool/autoapi/exiftool/experimental/index.html

Wrapper for retrieving multiple tags from a single file, with support for additional parameters.

```python
get_tags_wrapper(_tags_ , _filename_ , _params =None_)
```

--------------------------------

### Get Single Tag Batch (Wrapper)

Source: https://sylikc.github.io/pyexiftool/autoapi/exiftool/experimental/index.html

A wrapper for batch tag retrieval, allowing optional parameters for advanced usage.

```python
get_tag_batch_wrapper(_tag_ , _filenames_ , _params =None_)
```

--------------------------------

### Check ExifTool Version

Source: https://sylikc.github.io/pyexiftool/installation.html

Verify the installed version of the exiftool command-line utility. This is required for PyExifTool to function correctly.

```bash
exiftool -ver

```

--------------------------------

### Get Metadata in Batch (Wrapper)

Source: https://sylikc.github.io/pyexiftool/autoapi/exiftool/experimental/index.html

Retrieve metadata for multiple files efficiently using get_metadata_batch_wrapper. Optional parameters can be passed for customization.

```python
get_metadata_batch_wrapper(_filenames_ , _params =None_)
```

--------------------------------

### Get Specific Tags from Multiple Files using ExifToolHelper

Source: https://sylikc.github.io/pyexiftool/examples.html

Fetches specified tags (e.g., FileSize, ImageSize) from multiple image files using ExifToolHelper.get_tags. This is efficient for querying specific pieces of information across several files.

```python
from exiftool import ExifToolHelper

with ExifToolHelper() as et:
    for d in et.get_tags(["rose.jpg", "skyblue.png"], tags=["FileSize", "ImageSize"]):
        for k, v in d.items():
            print(f"Dict: {k} = {v}")
```

--------------------------------

### Execute ExifTool Command for JSON Output

Source: https://sylikc.github.io/pyexiftool/examples.html

Demonstrates how to get JSON output from exiftool using the execute_json method with argument unpacking. This is ideal for parsing structured metadata.

```python
from exiftool import ExifTool

with ExifTool() as et:
    # exiftool command-line: exiftool -j -XMP:all -JFIF:JFIFVersion /path/somefile.jpg
    args = ["-j", "-XMP:all", "-JFIF:JFIFVersion", "/path/somefile.jpg"]
    result = et.execute_json(*args)
    print(result)
```

--------------------------------

### Get Metadata for a Single File (Wrapper)

Source: https://sylikc.github.io/pyexiftool/autoapi/exiftool/experimental/index.html

Use get_metadata_wrapper to extract metadata from a single file. Custom parameters can be provided.

```python
get_metadata_wrapper(_filename_ , _params =None_)
```

--------------------------------

### Get Metadata from Multiple Files

Source: https://sylikc.github.io/pyexiftool/autoapi/exiftool/index.html

Use ExifToolHelper to extract metadata from a list of image files and print the source file name and original date/time.

```python
import exiftool

files = ["a.jpg", "b.png", "c.tif"]
with exiftool.ExifToolHelper() as et:
        metadata = et.get_metadata(files)
for d in metadata:
        print("{:20.20} {:20.20}".format(d["SourceFile"],
                                 d["EXIF:DateTimeOriginal"]))

```

--------------------------------

### Get Multiple Tags Batch (Wrapper)

Source: https://sylikc.github.io/pyexiftool/autoapi/exiftool/experimental/index.html

Retrieve multiple tags from multiple files using this wrapper function. Supports additional parameters.

```python
get_tags_batch_wrapper(_tags_ , _filenames_ , _params =None_)
```

--------------------------------

### Get specific tags from multiple files

Source: https://sylikc.github.io/pyexiftool/_sources/examples.rst.txt

Retrieve a subset of tags (e.g., FileSize, ImageSize) from multiple image files using ExifToolHelper. This is efficient for targeted metadata extraction.

```python
from exiftool import ExifToolHelper
with ExifToolHelper() as et:
    for d in et.get_tags(["rose.jpg", "skyblue.png"], tags=["FileSize", "ImageSize"]):
        for k, v in d.items():
            print(f"Dict: {k} = {v}")
```

--------------------------------

### Get All Metadata from a Single File using ExifToolHelper

Source: https://sylikc.github.io/pyexiftool/examples.html

Retrieves all available metadata tags for a single image file using the ExifToolHelper.get_metadata method. The output is a list of dictionaries, where each dictionary represents metadata from one file.

```python
from exiftool import ExifToolHelper

with ExifToolHelper() as et:
    for d in et.get_metadata("rose.jpg"):
        for k, v in d.items():
            print(f"Dict: {k} = {v}")
```

--------------------------------

### Get all metadata from a single file

Source: https://sylikc.github.io/pyexiftool/_sources/examples.rst.txt

Retrieve all available metadata tags for a single image file using ExifToolHelper. The output is a list of dictionaries, where each dictionary represents metadata from one file.

```python
from exiftool import ExifToolHelper
with ExifToolHelper() as et:
    for d in et.get_metadata("rose.jpg"):
        for k, v in d.items():
            print(f"Dict: {k} = {v}")
```

```text
Dict: SourceFile = rose.jpg
Dict: ExifTool:ExifToolVersion = 12.37
Dict: File:FileName = rose.jpg
Dict: File:Directory = .
Dict: File:FileSize = 4949
Dict: File:FileModifyDate = 2022:03:03 17:47:11-08:00
Dict: File:FileAccessDate = 2022:03:27 08:28:16-07:00
Dict: File:FileCreateDate = 2022:03:03 17:47:11-08:00
Dict: File:FilePermissions = 100666
Dict: File:FileType = JPEG
Dict: File:FileTypeExtension = JPG
Dict: File:MIMEType = image/jpeg
Dict: File:ImageWidth = 70
Dict: File:ImageHeight = 46
Dict: File:EncodingProcess = 0
Dict: File:BitsPerSample = 8
Dict: File:ColorComponents = 3
Dict: File:YCbCrSubSampling = 2 2
Dict: JFIF:JFIFVersion = 1 1
Dict: JFIF:ResolutionUnit = 1
Dict: JFIF:XResolution = 72
Dict: JFIF:YResolution = 72
Dict: XMP:XMPToolkit = Image::ExifTool 8.85
Dict: XMP:Subject = Röschen
Dict: Composite:ImageSize = 70 46
Dict: Composite:Megapixels = 0.00322
```

--------------------------------

### Execute ExifTool Command and Print Output

Source: https://sylikc.github.io/pyexiftool/_sources/examples.rst.txt

Demonstrates how to execute a basic ExifTool command to set an XMP tag and print the raw output. This method is suitable for commands that return information to stdout.

```python
from exiftool import ExifTool
with ExifTool() as et:
    print(et.execute(*["-XMP:Subject=hi"] + ["skyblue.png"]))

```

--------------------------------

### ExifTool Class Initialization

Source: https://sylikc.github.io/pyexiftool/reference/1-exiftool.html

Shows the signature for initializing the ExifTool class, detailing the parameters available for configuring the exiftool executable and its behavior.

```python
exiftool.ExifTool(_executable =None_, _common_args =['-G', '-n']_, _win_shell =False_, _config_file =None_, _encoding =None_, _logger =None_)
```

--------------------------------

### ExifTool Class Constructor

Source: https://sylikc.github.io/pyexiftool/autoapi/exiftool/exiftool/index.html

Initializes an ExifTool instance to run the exiftool command-line tool and communicate with it. Allows configuration of the executable path, common arguments, and other process-related settings.

```APIDOC
## ExifTool Class

### Description
Runs the exiftool command-line tool and communicates with it. It manages the exiftool subprocess, allowing for configuration of arguments and process behavior.

### Parameters

*   **executable** (_str_ or _None_) – Path to the exiftool executable. If None, it will be looked for in the system's PATH.
*   **common_args** (_list_ of _str_ or _None_) – Additional parameters passed to the exiftool subprocess. Defaults to `["-G", "-n"]`.
*   **win_shell** (_bool_) – (Windows only) Minimizes the exiftool process.
*   **config_file** (_str_, _Path_, or _None_) – Path to a configuration file for exiftool.
*   **encoding** (_Optional_[_str_]) – Encoding to use when communicating with the exiftool process. Defaults to `locale.getpreferredencoding()`.
*   **logger** – A custom logger object for status and debug messages.
```

--------------------------------

### Execute ExifTool Command with Argument Unpacking

Source: https://sylikc.github.io/pyexiftool/examples.html

Shows how to use argument unpacking with a list to pass arguments to the execute method. This is helpful when you have a list of arguments, such as from a configuration or dynamic generation.

```python
from exiftool import ExifTool

with ExifTool() as et:
    # exiftool command-line: exiftool -P -DateTimeOriginal="2021:01:02 03:04:05" -MakerNotes= "spaces in filename.jpg"
    args = ["-P", "-DateTimeOriginal=2021:01:02 03:04:05", "-MakerNotes=", "spaces in filename.jpg"]
    result = et.execute(*args)
    print(result.decode('utf-8'))
```

--------------------------------

### ExifToolVersionError

Source: https://sylikc.github.io/pyexiftool/_sources/autoapi/exiftool/exceptions/index.rst.txt

Raised to represent a version mismatch between PyExifTool and the installed ExifTool.

```APIDOC
## ExifToolVersionError

### Description
Generic Error to represent some version mismatch.
PyExifTool is coded to work with a range of exiftool versions. If the advanced params change in functionality and break PyExifTool, this error will be thrown

### Inheritance
Bases: `ExifToolException`
```

--------------------------------

### run()

Source: https://sylikc.github.io/pyexiftool/genindex.html

Executes the exiftool command. This method can be called directly on an ExifTool instance or through a helper.

```APIDOC
## run()

### Description
Executes the exiftool command. This method can be called directly on an ExifTool instance or through a helper.

### Method
Not specified (likely a method call in Python)

### Endpoint
N/A (Python method)

### Parameters
N/A (Python method)

### Request Example
N/A (Python method)

### Response
N/A (Python method)
```

--------------------------------

### ExifToolNotRunning

Source: https://sylikc.github.io/pyexiftool/autoapi/exiftool/exceptions/index.html

Raised when the ExifTool subprocess is not running, indicating it needs to be started or has unexpectedly terminated.

```APIDOC
## ExifToolNotRunning

### Description
ExifTool is not running. This exception is raised when an operation is attempted that requires the ExifTool subprocess to be active, but it is not.

### Exception
`exiftool.exceptions.ExifToolNotRunning`

### Inheritance
Bases: `ExifToolProcessStateError`

### Parameters
* **message** (_str_): A message describing the reason why ExifTool is not running.
```

--------------------------------

### Get Single Tag (Wrapper)

Source: https://sylikc.github.io/pyexiftool/autoapi/exiftool/experimental/index.html

Wrapper for retrieving a single tag from a single file, with support for additional parameters.

```python
get_tag_wrapper(_tag_ , _filename_ , _params =None_)
```

--------------------------------

### Handling Missing Files with PyExifTool

Source: https://sylikc.github.io/pyexiftool/_sources/faq.rst.txt

Demonstrates how to execute a command with PyExifTool when a file might be missing. The library handles this by raising an exception.

```python
with exiftool.ExifToolHelper(logger=logging.getLogger(__name__)) as et:
    et.execute("missingfile.jpg",)
```

--------------------------------

### ExifTool Constructor

Source: https://sylikc.github.io/pyexiftool/reference/1-exiftool.html

Initializes an ExifTool instance to communicate with the exiftool command-line tool. It allows specifying the executable path, common arguments, configuration file, encoding, and a custom logger. The instance manages a persistent exiftool subprocess.

```APIDOC
## ExifTool Constructor

### Description
Initializes an ExifTool instance to communicate with the exiftool command-line tool. It allows specifying the executable path, common arguments, configuration file, encoding, and a custom logger. The instance manages a persistent exiftool subprocess.

### Parameters

#### Parameters

- **executable** (str or None) - Optional - Specify file name of the exiftool executable if it is in your PATH. Otherwise, specify the full path to the exiftool executable. Defaults to exiftool.constants.DEFAULT_EXECUTABLE.
- **common_args** (list of str or None) - Optional - Pass in additional parameters for the stay-open instance of exiftool. Defaults to ["-G", "-n"].
  - `-G` (groupName level 1 enabled) separates the output with groupName:tag to disambiguate same-named tags under different groups.
  - `-n` (print conversion disabled) improves the speed and consistency of output, and is more machine-parsable.
- **win_shell** (bool) - Optional - (Windows only) Minimizes the exiftool process. May be deprecated in the future.
- **config_file** (str, Path, or None) - Optional - File path to the -config parameter when starting the exiftool process.
- **encoding** (str) - Optional - Specify encoding to be used when communicating with exiftool process. Defaults to locale.getpreferredencoding().
- **logger** - Optional - Set a custom logger to log status and debug messages to.
```

--------------------------------

### execute

Source: https://sylikc.github.io/pyexiftool/autoapi/exiftool/exiftool/index.html

Accepts any number of parameters and sends them to the attached `exiftool` subprocess. The process must be running, otherwise `exiftool.exceptions.ExifToolNotRunning` is raised. The final `-execute` necessary to actually run the batch is appended automatically. The `exiftool` output is read up to the end-of-output sentinel and returned as a `str` decoded based on the currently set `encoding`, excluding the sentinel. Parameters must be of type `str` or `bytes`. `str` parameters are encoded to bytes automatically using the `encoding` property. `bytes` parameters are untouched and passed directly to `exiftool`. This is the core method to interface with the `exiftool` subprocess. No processing is done on the input or output.

```APIDOC
## execute(*params, raw_bytes=False)

### Description
Executes a batch of parameters directly with the exiftool subprocess, returning raw stdout.

### Method
execute

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
* **params** (str or bytes) - Required - One or more parameters to send to the exiftool subprocess.
* **raw_bytes** (bool) - Optional - If True, returns bytes. Default behavior returns a str.

### Request Example
```python
# Example usage (assuming exiftool is running)
# exiftool.execute('-G', 'image.jpg')
```

### Response
#### Success Response (200)
- **stdout** (str or bytes) - The standard output from the exiftool command.
- **stderr** (str) - The standard error from the exiftool command, set in `last_stderr`.
- **status** (int) - The exit status of the command, set in `last_status`.

#### Response Example
```json
{
  "stdout": "Example exiftool output...",
  "stderr": "",
  "status": 0
}
```

### Raises
* **ExifToolNotRunning**: If attempting to execute when not running.
* **ExifToolVersionError**: If unexpected text was returned from the command while parsing out the sentinels.
* **UnicodeDecodeError**: If the `encoding` is not specified properly.
* **TypeError**: If `params` argument is not `str` or `bytes`.
```

--------------------------------

### Configure Logging for Debugging PyExifTool

Source: https://sylikc.github.io/pyexiftool/faq.html

Shows how to set up a logger to capture debug information from PyExifTool, useful for diagnosing issues. Basic logging configuration is included.

```python
import logging
import exiftool

logging.basicConfig(level=logging.DEBUG)
with exiftool.ExifToolHelper(logger=logging.getLogger(__name__)) as et:
        et.execute("missingfile.jpg",)
```

--------------------------------

### Extract Metadata from Multiple Files

Source: https://sylikc.github.io/pyexiftool/_sources/autoapi/exiftool/index.rst.txt

Demonstrates how to use ExifToolHelper to extract metadata from a list of image files. Ensure ExifToolHelper is imported and initialized.

```python
import exiftool

files = ["a.jpg", "b.png", "c.tif"]
with exiftool.ExifToolHelper() as et:
        metadata = et.get_metadata(files)
for d in metadata:
        print("{:20.20} {:20.20}".format(d["SourceFile"],
                                         d["EXIF:DateTimeOriginal"]))

```

--------------------------------

### ExifToolHelper Class

Source: https://sylikc.github.io/pyexiftool/_sources/autoapi/exiftool/helper/index.rst.txt

The ExifToolHelper class extends the low-level ExifTool class with helper functions. It provides parameters for controlling automatic process startup, exit status checking, and tag name validation.

```APIDOC
## Class: ExifToolHelper

### Description
This class extends the low-level :py:class:`exiftool.ExifTool` class with 'wrapper'/'helper' functionality. It keeps low-level core functionality with the base class but extends helper functions in a separate class.

### Parameters
* **auto_start** (bool) - Optional - Will automatically start the exiftool process on first command run, defaults to True.
* **check_execute** (bool) - Optional - Will check the exit status (return code) of all commands. This catches some invalid commands passed to exiftool subprocess, defaults to True. See :py:attr:`check_execute` for more info.
* **check_tag_names** (bool) - Optional - Will check the tag names provided to methods which work directly with tag names. This catches unintended uses and bugs, default to True. See :py:attr:`check_tag_names` for more info.
* **kwargs** - All other parameters are passed directly to the super-class constructor: :py:meth:`exiftool.ExifTool.__init__()`

### Properties
* **auto_start** (bool) - Read-only property. Gets the current setting passed into the constructor as to whether auto_start is enabled or not.
* **check_execute** (bool) - Flag to enable/disable checking exit status (return code) on execute. If enabled, will raise :py:exc:`exiftool.exceptions.ExifToolExecuteError` if a non-zero exit status is returned during :py:meth:`execute()`. This setting can be changed any time and will only affect subsequent calls.
* **check_tag_names** (bool) - Flag to enable/disable checking of tag names. If enabled, will raise :py:exc:`exiftool.exceptions.ExifToolTagNameError` if an invalid tag name is detected. This setting can be changed any time and will only affect subsequent calls.
```

--------------------------------

### ExifToolVersionError

Source: https://sylikc.github.io/pyexiftool/autoapi/exiftool/exceptions/index.html

Generic error to represent a version mismatch between PyExifTool and the installed ExifTool binary. This can occur if ExifTool's functionality changes and breaks compatibility.

```APIDOC
## ExifToolVersionError

### Description
Generic Error to represent some version mismatch. PyExifTool is coded to work with a range of exiftool versions. If the advanced params change in functionality and break PyExifTool, this error will be thrown.

### Exception
`exiftool.exceptions.ExifToolVersionError`

### Inheritance
Bases: `ExifToolException`
```

--------------------------------

### Setting Multiple Tags with ExifTool Helper

Source: https://sylikc.github.io/pyexiftool/_sources/autoapi/exiftool/helper/index.rst.txt

Demonstrates how to pass a dictionary of tags to the exiftool helper to set multiple values for a single tag, such as 'Keywords'.

```python
tags={"Keywords": ["a", "b", "c"]}
```

--------------------------------

### Get Tags with Invalid Tag Name (Helper)

Source: https://sylikc.github.io/pyexiftool/_sources/examples.rst.txt

Demonstrates `ExifToolHelper.get_tags` behavior with an invalid tag name containing an equals sign. The helper raises an `ExifToolTagNameError`.

```python
from exiftool import ExifToolHelper
with ExifToolHelper() as et:
    print(et.get_tags(["skyblue.png"], tags=["XMP:Subject=hi"]))

```

--------------------------------

### Execute command with arguments

Source: https://sylikc.github.io/pyexiftool/_sources/examples.rst.txt

Directly call exiftool commands with arguments. Arguments are passed as separate strings.

```text
exiftool -XMPToolKit -Subject rose.jpg
```

```python
execute("-XMPToolKit", "-Subject", "rose.jpg")
```

--------------------------------

### executable

Source: https://sylikc.github.io/pyexiftool/_sources/autoapi/exiftool/exiftool/index.rst.txt

Specifies the path to the ExifTool executable. This property can be read to get the current path or set to a new path. Setting is only available when the ExifTool process is not running.

```APIDOC
## executable

### Description
Path to the ExifTool executable. This property can be read to get the current path or set to a new path. Setting is only available when the ExifTool process is not running.

### Getter
Returns the current ExifTool path.

### Setter
Specify just the executable name, or an absolute path to the executable. If the path given is not absolute, it searches the environment `PATH`. Setting is only available when the ExifTool process is not running.

### Raises
- `ExifToolRunning`: If attempting to set while the process is running.

### Type
Union[str, pathlib.Path]
```

--------------------------------

### execute

Source: https://sylikc.github.io/pyexiftool/autoapi/exiftool/helper/index.html

Overrides the base `exiftool.ExifTool.execute()` method to add logic for auto-starting the ExifTool process if not running and for converting non-string/bytes parameters to strings.

```APIDOC
## execute

### Description
Overrides the base `exiftool.ExifTool.execute()` method to add logic for auto-starting the ExifTool process if not running and for converting non-string/bytes parameters to strings. This allows passing objects like Path without explicit casting.

### Raises
* **ExifToolExecuteError** – If `check_execute` is True and the exit status was non-zero.

### Parameters
* **params** (Any) – Parameters to be passed to the exiftool command.
* **kwargs** – Additional keyword arguments.

### Return Type
Union[str, bytes]
```

--------------------------------

### Get ExifTool Version

Source: https://sylikc.github.io/pyexiftool/_sources/autoapi/exiftool/exiftool/index.rst.txt

Retrieves the cached version string of the exiftool executable, obtained by running 'exiftool -ver' once at startup. Raises ExifToolNotRunning if called when the subprocess is not active.

```python
try:
    version = exiftool.version
    print(f'ExifTool version: {version}')
except ExifToolNotRunning:
    print('ExifTool is not running, cannot get version.')
```

--------------------------------

### Execute ExifTool Command Directly

Source: https://sylikc.github.io/pyexiftool/examples.html

Demonstrates calling an exiftool command-line directly using PyExifTool's execute method. This is useful for simple commands where you need to pass arguments as separate strings.

```python
from exiftool import ExifTool

with ExifTool() as et:
    # exiftool command-line: exiftool -XMPToolKit -Subject rose.jpg
    result = et.execute("-XMPToolKit", "-Subject", "rose.jpg")
    print(result.decode('utf-8'))
```

--------------------------------

### ExifTool Methods

Source: https://sylikc.github.io/pyexiftool/_sources/autoapi/exiftool/exiftool/index.rst.txt

Provides methods for executing commands with the ExifTool subprocess and handling its output.

```APIDOC
## ExifTool Methods

### Description
Methods for direct interaction with the ExifTool subprocess, including executing commands and retrieving results.

### Methods

- **execute(*params, raw_bytes=False)**
  - **Description**: Executes a batch of parameters with the attached ExifTool subprocess. Appends the `-execute` flag automatically. Reads and returns the output up to the end-of-output sentinel.
  - **Parameters**:
    - `*params` (str or bytes): One or more parameters to send to the ExifTool subprocess. String parameters are encoded using the current `encoding` property. Bytes parameters are passed directly.
    - `raw_bytes` (bool): If True, returns the output as bytes. Defaults to False (returns str).
  - **Returns**: The standard output from ExifTool. Also sets `last_stdout`, `last_stderr`, and `last_status` properties.
  - **Raises**:
    - `ExifToolNotRunning`: If the subprocess is not running.
    - `ExifToolVersionError`: If unexpected text is returned during sentinel parsing.
    - `UnicodeDecodeError`: If `encoding` is improperly specified.
    - `TypeError`: If `params` is not of type `str` or `bytes`.

- **execute_json(*params)**
  - **Description**: Executes a batch of parameters with ExifTool and parses the JSON output. Automatically adds the `-j` parameter for JSON output.
  - **Parameters**:
    - `*params` (str or bytes): One or more parameters to send to the ExifTool subprocess.
  - **Returns**: A list of dictionaries, where each dictionary represents a file and maps tag names to their values. Includes a `"SourceFile"` key for the corresponding filename.
```

--------------------------------

### Execute command for JSON output with argument unpacking

Source: https://sylikc.github.io/pyexiftool/_sources/examples.rst.txt

Call exiftool commands to get JSON output using argument unpacking. This is useful for structured metadata retrieval.

```text
exiftool -j -XMP:all -JFIF:JFIFVersion /path/somefile.jpg
```

```python
execute_json(*["-XMP:all", "-JFIF:JFIFVersion", "/path/somefile.jpg"])
```

--------------------------------

### ExifTool Class

Source: https://sylikc.github.io/pyexiftool/_sources/autoapi/exiftool/exiftool/index.rst.txt

The ExifTool class provides an interface to run the exiftool command-line tool and communicate with its subprocess. It allows for configuration of the executable, common arguments, and encoding, and supports usage as a context manager for automatic subprocess termination.

```APIDOC
## ExifTool Class

### Description

Manages the exiftool command-line tool subprocess, enabling communication and data extraction/writing. Supports configuration of the executable path, common arguments, and encoding. It is recommended to use this class as a context manager to ensure proper subprocess termination.

### Class Signature

```python
class ExifTool(executable=None, common_args=['-G', '-n'], win_shell=False, config_file=None, encoding=None, logger=None)
```

### Parameters

- **executable** (str or None): Path to the exiftool executable. Defaults to `exiftool.constants.DEFAULT_EXECUTABLE` if None, which requires exiftool to be in the system's PATH.
- **common_args** (list of str or None): Additional parameters passed to the exiftool subprocess. Defaults to `['-G', '-n']`. `-G` enables group names, and `-n` disables print conversion for faster, more machine-parsable output.
- **win_shell** (bool): (Windows only) If True, minimizes the exiftool process. This parameter may be deprecated in the future.
- **config_file** (str, Path, or None): Path to a configuration file to be used with exiftool's `-config` option.
- **encoding** (str or None): Encoding to use for communication with the exiftool process. Defaults to `locale.getpreferredencoding()`.
- **logger**: A custom logger object for status and debug messages.

### Properties

- **block_size** (int): The block size used for reading from the exiftool subprocess's I/O pipe. Can be get or set. Setting requires a value greater than 0.
- **common_args** (Optional[List[str]]): The list of common arguments passed to the exiftool subprocess.

### Usage Notes

- Options and parameters are not validated; exiftool itself handles validation, and invalid options are often silently ignored.
- Avoid passing non-existent files to methods, as this can lead to undefined behavior.
- Ensure subprocesses are terminated using `terminate()` or by using the class as a context manager (`with ExifTool() as et:`).
- Subprocesses are not automatically terminated if the parent process exits unexpectedly.
```

--------------------------------

### encoding

Source: https://sylikc.github.io/pyexiftool/_sources/autoapi/exiftool/exiftool/index.rst.txt

Defines the encoding for Popen() communication with the ExifTool process. This property can be read to get the current encoding or set to a new encoding. Setting is only available when the ExifTool process is not running.

```APIDOC
## encoding

### Description
Encoding of Popen() communication with the ExifTool process. This property can be read to get the current encoding or set to a new encoding. Setting is only available when the ExifTool process is not running.

### Getter
Returns the current encoding setting.

### Setter
Sets a new encoding. If `new_encoding` is None, it will be detected from `locale.getpreferredencoding(do_setlocale=False)`. Defaults to `utf-8` if nothing is returned by `getpreferredencoding`. The property setter does not validate the encoding for validity.

### Raises
- `ExifToolRunning`: If attempting to set while the process is running.

### Type
Optional[str]
```

--------------------------------

### run

Source: https://sylikc.github.io/pyexiftool/autoapi/exiftool/helper/index.html

Overrides the `exiftool.ExifTool.run()` method. This method will not attempt to run if already running, preventing warnings about the ExifTool process already being active.

```APIDOC
## run

### Description
Overrides the `exiftool.ExifTool.run()` method. Will not attempt to run if already running (so no warning about ‘ExifTool already running’ will trigger).

### Return type
None
```

--------------------------------

### running

Source: https://sylikc.github.io/pyexiftool/genindex.html

A property indicating whether the exiftool process is currently running.

```APIDOC
## running

### Description
A property indicating whether the exiftool process is currently running.

### Method
N/A (Python property)

### Endpoint
N/A (Python property)

### Parameters
N/A (Python property)

### Request Example
N/A (Python property)

### Response
N/A (Python property)
```

--------------------------------

### config_file

Source: https://sylikc.github.io/pyexiftool/_sources/autoapi/exiftool/exiftool/index.rst.txt

Specifies the path to the configuration file used by ExifTool. This property can be read to get the current config file path or set to a new path. Setting is only available when the ExifTool process is not running.

```APIDOC
## config_file

### Description
Path to the configuration file. This property can be read to get the current config file path or set to a new path. Setting is only available when the ExifTool process is not running.

### Getter
Returns the current config file path, or None if not set.

### Setter
Sets the config file path. File existence is checked when setting the parameter. Set to `None` to disable the `-config` parameter. Set to `""` to disable loading the default config file. Currently, the file is checked for existence when setting, not when starting the process.

### Raises
- `ExifToolRunning`: If attempting to set while the process is running.

### Type
Optional[Union[str, pathlib.Path]]
```

--------------------------------

### common_args

Source: https://sylikc.github.io/pyexiftool/_sources/autoapi/exiftool/exiftool/index.rst.txt

Represents common arguments passed to every command executed by the ExifTool subprocess. It can be read to get the current list of arguments or set to a new list. Setting is only available when the ExifTool process is not running.

```APIDOC
## common_args

### Description
This property represents common arguments that are passed when the ExifTool process is STARTED. It can be read to get the current list of arguments or set to a new list. Setting is only available when the ExifTool process is not running.

### Getter
Returns the current `common_args` list.

### Setter
Sets the `common_args` list. If `None` is passed, it sets `common_args` to an empty list. Otherwise, it sets the given list without validation. A warning is issued as invalid options may result in undefined behavior. Setting is only available when the ExifTool process is not running.

### Raises
- `ExifToolRunning`: If attempting to set while the process is running.
- `TypeError`: If the value set is not a list.

### Type
list[str] or None
```

--------------------------------

### ExifTool Methods

Source: https://sylikc.github.io/pyexiftool/autoapi/exiftool/exiftool/index.html

Methods for interacting with the ExifTool process.

```APIDOC
## Method: execute

### Description
Executes a batch of parameters with the ExifTool command-line utility.

### Parameters
* **params**: Variable arguments representing the ExifTool parameters.
* **raw_bytes** (bool, optional): If `True`, the output will be returned as bytes. Defaults to `False`.

### Return Type
Depends on the `raw_bytes` parameter and ExifTool's output.
```

```APIDOC
## Special Methods: Context Manager

### Description
Provides context management capabilities for the ExifTool instance.

### `__enter__()`
Enters the runtime context related to this object. Returns the instance itself.

### `__exit__(exc_type, exc_val, exc_tb)`
Exits the runtime context. Cleans up resources if necessary.

### Return Type
None
```

```APIDOC
## Special Methods: Destructor

### Description
Handles the cleanup of the ExifTool instance when it is garbage collected.

### `__del__()`
Called when the object is about to be destroyed. Ensures resources are released.

### Return Type
None
```

--------------------------------

### exiftool.ExifToolAlpha.execute_json_wrapper

Source: https://sylikc.github.io/pyexiftool/reference/3-alpha.html

Wrapper for executing commands and returning JSON output.

```APIDOC
## exiftool.ExifToolAlpha.execute_json_wrapper

### Description
Wrapper for executing commands and returning JSON output.

### Method
Not specified (assumed to be a method call within the Python library).

### Parameters
#### Path Parameters
- **_filenames_** (list of strings) - Required - A list of file names to process.

#### Query Parameters
- **_params_** (dict, optional) - Additional parameters for the exiftool command.
- **_retry_on_error_** (bool, optional) - Whether to retry on error. Defaults to True.
```

--------------------------------

### Using ExifTool as a Context Manager

Source: https://sylikc.github.io/pyexiftool/autoapi/exiftool/exiftool/index.html

Ensures the exiftool subprocess is properly terminated when finished. This is the recommended way to use the ExifTool instance.

```python
with ExifTool() as et:
        ...
```

--------------------------------

### execute

Source: https://sylikc.github.io/pyexiftool/_sources/autoapi/exiftool/exiftool/index.rst.txt

Executes a command with exiftool, returning the output as a Python list of dictionaries. It handles potential errors like empty output or invalid JSON, and mimics exiftool's default error handling.

```APIDOC
## execute(params)

### Description
Executes a command with exiftool, returning the output as a Python list of dictionaries. It handles potential errors like empty output or invalid JSON, and mimics exiftool's default error handling.

### Method
`execute`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
* **params** (str or bytes) - Required - One or more parameters to send to the ``exiftool`` subprocess.

### Request Example
```python
# Example usage (assuming exiftool_helper is an instance of ExifToolHelper)
# exiftool_helper.execute('-G', '-json', 'image.jpg')
```

### Response
#### Success Response (200)
* **list of dicts**: Valid JSON parsed into a Python list of dicts

#### Response Example
```json
[
  {
    "SourceFile": "image.jpg",
    "ExifToolVersion": "12.34",
    "ImageWidth": 1920,
    "ImageHeight": 1080
  }
]
```

### Raises
* **ExifToolOutputEmptyError**: If *exiftool* did not return any STDOUT.
* **ExifToolJSONInvalidError**: If *exiftool* returned STDOUT which is invalid JSON.
```

--------------------------------

### Parsing ExifTool Command Line Arguments with shlex

Source: https://sylikc.github.io/pyexiftool/faq.html

Illustrates how to use Python's `shlex.split()` to correctly parse complex exiftool command-line arguments into a list suitable for PyExifTool's execute methods. This is primarily for debugging argument parsing issues.

```python
import shlex, exiftool
with exiftool.ExifToolHelper() as et:
        params = shlex.split('-v0 -preserve -overwrite_original -api largefilesupport=1 "-EXIF:DateTimeOriginal+=1:2:3 4:5:6" -XMP:DateTimeOriginal="2006:05:04 03:02:01" -gpsaltituderef="Above Sea Level" -make= test.mov')
        print(params)
        # Output: ['-v0', '-preserve', '-overwrite_original', '-api', 'largefilesupport=1', '-api', 'QuickTimeUTC=1', '-EXIF:DateTimeOriginal+=1:2:3 4:5:6', '-XMP:DateTimeOriginal=2006:05:04 03:02:01', '-gpsaltituderef=Above Sea Level', '-make=', 'test.mov']
        et.execute(*params)

```

--------------------------------

### auto_start Property

Source: https://sylikc.github.io/pyexiftool/autoapi/exiftool/helper/index.html

A read-only property that indicates whether the auto_start functionality is enabled for the ExifTool process.

```APIDOC
## auto_start Property

### Description
A read-only property that indicates whether the auto_start functionality is enabled for the ExifTool process.

### Return Type
bool
```

--------------------------------

### execute

Source: https://sylikc.github.io/pyexiftool/_sources/autoapi/exiftool/helper/index.rst.txt

Overrides the base ExifTool.execute() method to add auto-start logic and parameter type coercion. It ensures ExifTool is running if auto_start is true and converts non-string/bytes parameters to strings.

```APIDOC
## execute(*params, **kwargs)

### Description
Overrides the :py:meth:`exiftool.ExifTool.execute()` method. Adds logic to auto-start if not running, if :py:attr:`auto_start` == True. Adds logic to str() any parameter which is not a str or bytes. (This allows passing in objects like Path _without_ casting before passing it in.)

### Raises
* **ExifToolExecuteError**: If :py:attr:`check_execute` == True, and exit status was non-zero.
```

--------------------------------

### Set Keywords Tag

Source: https://sylikc.github.io/pyexiftool/_sources/examples.rst.txt

Sets the 'Keywords' tag for specified files to a list of strings. No output is returned if successful.

```python
from exiftool import ExifToolHelper
with ExifToolHelper() as et:
    et.set_tags(
        ["rose.jpg", "skyblue.png"],
        tags={"Keywords": ["sunny", "nice day", "cool", "awesome"]}
    )
```

--------------------------------

### exiftool.ExifToolAlpha.get_tags_batch_wrapper

Source: https://sylikc.github.io/pyexiftool/reference/3-alpha.html

Wrapper for retrieving multiple tags' values from multiple files.

```APIDOC
## exiftool.ExifToolAlpha.get_tags_batch_wrapper

### Description
Wrapper for retrieving multiple tags' values from multiple files.

### Method
Not specified (assumed to be a method call within the Python library).

### Parameters
#### Path Parameters
- **_tags_** (list of strings) - Required - A list of tag names to extract.
- **_filenames_** (list of strings) - Required - A list of file names to process.

#### Query Parameters
- **_params_** (dict, optional) - Additional parameters for the exiftool command.
```

--------------------------------

### check_ok

Source: https://sylikc.github.io/pyexiftool/autoapi/exiftool/experimental/index.html

Evaluates the output from an ExifTool write operation.

```APIDOC
## Function: check_ok

### Description
Evaluates the output from an ExifTool write operation (e.g., `set_tags`) to determine success.

### Parameters
* **result** (any) - The result from an `execute` method.

### Returns
`True` if the operation was successful, `False` otherwise.
```

--------------------------------

### run

Source: https://sylikc.github.io/pyexiftool/_sources/autoapi/exiftool/helper/index.rst.txt

Overrides the base ExifTool.run() method to prevent attempting to run if ExifTool is already running, thus avoiding a warning message.

```APIDOC
## run()

### Description
Override the :py:meth:`exiftool.ExifTool.run()` method. Will not attempt to run if already running (so no warning about 'ExifTool already running' will trigger).
```
Tokens:
Raw