### 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
```

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

### 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.
```

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

### 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()`.
```

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

### 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
```

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

### 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_)
```

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

### 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 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_)
```

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

### 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 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 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_)
```

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

### 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 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
```

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

### 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}")
```

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

### 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"])
```

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

### 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.
```

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

### 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`
```

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

### 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'))
```

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

### 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)
```

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

### 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.
```

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

### 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]
```

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

### 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")
```

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

### 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 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

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]
```

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

### 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]
```

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

### 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.
```

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

### 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
```

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

### 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]]
```

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

### 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)
```

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

### 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.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.
```

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

### 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.
```

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

### Execute command with argument unpacking

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

Use argument unpacking from a list to pass arguments to exiftool commands. Parameters that require quoting on the command line generally do not need it here.

```text
exiftool -P -DateTimeOriginal="2021:01:02 03:04:05" -MakerNotes= "spaces in filename.jpg"
```

```python
execute(*["-P", "-DateTimeOriginal=2021:01:02 03:04:05", "-MakerNotes=", "spaces in filename.jpg"])
```

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

### 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).
```

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

### set_keywords()

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

Sets keywords for metadata. This method is part of the experimental ExifToolAlpha interface.

```APIDOC
## set_keywords()

### Description
Sets keywords for metadata. This method is part of the experimental ExifToolAlpha interface.

### 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)
```

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

### version

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

A property that returns the exiftool version.

```APIDOC
## version

### Description
A property that returns the exiftool version.

### 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)
```

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

### ExifTool Command Line with -G and -n Flags

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

Demonstrates how to achieve output similar to PyExifTool's default by enabling group names (-G) and disabling print conversion (-n) on the exiftool command line.

```bash
$ exiftool -G -n -JFIF:all rose.jpg

```

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


```

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

### Execute ExifTool Command

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

The core method for interacting with the exiftool subprocess. It sends parameters directly to exiftool, appends '-execute', and returns the raw output. Supports string or bytes parameters and can return raw bytes.

```python
try:
    # Example: Get version info
    stdout, stderr = exiftool.execute('-ver')
    print(f'STDOUT: {stdout}')
    print(f'STDERR: {stderr}')

    # Example: Get raw bytes output
    raw_output = exiftool.execute('-ver', raw_bytes=True)
    print(f'Raw bytes: {raw_output}')

except ExifToolNotRunning:
    print('ExifTool is not running.')
except ExifToolVersionError as e:
    print(f'ExifTool version error: {e}')
except TypeError as e:
    print(f'Type error: {e}')
```

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

### exiftool.ExifToolAlpha.get_metadata_batch_wrapper

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

Wrapper for retrieving metadata from multiple files in JSON format.

```APIDOC
## exiftool.ExifToolAlpha.get_metadata_batch_wrapper

### Description
Wrapper for retrieving metadata from multiple files in JSON format.

### 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.
```

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

### exiftool.ExifTool.execute

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

Executes a batch of parameters with the `exiftool` subprocess. This is the core method for interfacing with the `exiftool` subprocess, passing parameters directly without processing.

```APIDOC
## Method: `execute`

### Description
Execute the given batch of parameters with `exiftool`. This method accepts any number of parameters and sends them to the attached `exiftool` subprocess. The process must be running. The final `-execute` 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

- **`*params`** (`str` or `bytes`)
  - Required
  - One or more parameters to send to the `exiftool` subprocess. `str` parameters are encoded automatically using the `encoding` property. `bytes` parameters are passed directly.

- **`raw_bytes`** (`bool`)
  - Optional
  - If `True`, returns bytes instead of a string. Defaults to `False`.

### Returns

- STDOUT is returned by the method call and also set in `last_stdout`.
- STDERR is set in `last_stderr`.
- Exit Status of the command is set in `last_status`.

### Raises

- `exiftool.exceptions.ExifToolNotRunning`: If the process is not running.
```

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

### Use a Faster JSON Parser in PyExifTool

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

Demonstrates how to replace the default JSON parser with an alternative, such as ujson, for potentially faster performance.

```python
import exiftool, json
with exiftool.ExifToolHelper() as et:
        et.set_json_loads(ujson.loads)
        ...
```

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

### execute

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

Executes an ExifTool command with specified tags and parameters. It handles the conversion of tag dictionaries into command-line arguments and manages potential errors during execution.

```APIDOC
## execute(**opts)

### Description
Executes an ExifTool command.

This allows setting things like ``-Keywords=a -Keywords=b -Keywords=c`` by passing in ``tags={"Keywords": ['a', 'b', 'c']}``

### Parameters
#### Path Parameters
None

#### Query Parameters
* **tags** (dict) - A dictionary where keys are tag names and values are lists of tag values.
* **params** (str, list, or None) - Optional parameter(s) to send to *exiftool*.

### Request Example
```python
# Example usage (assuming ExifTool class instance 'exiftool')
exiftool.execute(tags={'Keywords': ['a', 'b', 'c']}, params='-overwrite_original')
```

### Response
#### Success Response (200)
Returns the output of the exiftool command, typically a JSON string or a list of dictionaries, depending on the exiftool configuration.

#### Response Example
```json
{
  "example": "[ { \"SourceFile\": \"example.jpg\", \"Keywords\": [ \"a\", \"b\", \"c\" ] } ]"
}
```

### Raises
* **ValueError**: Invalid Parameter
* **TypeError**: Invalid Parameter
* **ExifToolExecuteError**: If `check_execute` == True, and exit status was non-zero
```

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

### exiftool.ExifToolAlpha.get_tags_wrapper

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

Wrapper for retrieving multiple tags' values from a single file.

```APIDOC
## exiftool.ExifToolAlpha.get_tags_wrapper

### Description
Wrapper for retrieving multiple tags' values from a single file.

### 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.
- **_filename_** (string) - Required - The path to the file.

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

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

### execute_json

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

Executes the given batch of parameters and parses the JSON output. This method automatically adds the parameter `-j` to request JSON output from `exiftool` and parses the output. The return value is a list of dictionaries, mapping tag names to the corresponding values. All keys are strings. The values can have multiple types. Each dictionary contains the name of the file it corresponds to in the key `"SourceFile"`. By default, the tag names include the group name in the format `<group>:<tag>` (if using the `-G` option). This method does not verify the exit status code returned by `exiftool`. Mimics exiftool’s default method of operation “continue on error” and “best attempt” to complete commands given.

```APIDOC
## execute_json(*params)

### Description
Executes a batch of parameters with exiftool and parses the JSON output.

### Method
execute_json

### 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 is running)
# exiftool.execute_json('-G', '-j', 'image.jpg')
```

### Response
#### Success Response (200)
- **parsed_json** (List[Dict]) - A list of dictionaries, where each dictionary represents the metadata for a file.

#### Response Example
```json
[
  {
    "SourceFile": "image.jpg",
    "EXIF": {
      "Make": "Canon"
    }
  }
]
```

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