# pydicom.filewriter.dcmwrite

pydicom.filewriter.dcmwrite(filename: str | bytes | PathLike | BinaryIO | WriteableBuffer, dataset: Dataset, /, __write_like_original: bool | None = None, *, implicit_vr: bool | None = None, little_endian: bool | None = None, enforce_file_format: bool = False, force_encoding: bool = False, overwrite: bool = True, **kwargs: Any) → None

  Write dataset to filename, which can be a path, a file-like or a writeable buffer.

  Changed in version 3.0: Added the enforce_file_format and overwrite keyword arguments.

  Deprecated since version 3.0: write_like_original is deprecated and will be removed in v4.0, use enforce_file_format instead.

  If enforce_file_format is `True` then an attempt will be made to write dataset using the DICOM File Format, or raise an exception if unable to do so.

  If enforce_file_format is `False` (default) then dataset will be written as-is (after minimal validation checking) and may or may not contain all or parts of the File Meta Information and hence may or may not be conformant with the DICOM File Format.

  DICOM File Format

  The DICOM File Format consists of a 128-byte preamble, a 4 byte `b'DICM'` prefix, the File Meta Information Group elements and finally the encoded dataset.

  Preamble and Prefix

  The `dataset.preamble` attribute shall be 128-bytes long or `None`. The actual preamble written depends on enforce_file_format and `dataset.preamble` (see the table below).

  | enforce_file_format
  --- | ---
  dataset.preamble | False | True
  None | no preamble | 128 0x00 bytes
  128 bytes | dataset.preamble

  The prefix shall be the bytestring `b'DICM'` and will be written if and only if the preamble is present.

  File Meta Information Group Elements

  The preamble and prefix are followed by a set of DICOM elements from the (0002,eeee) group. Some of these elements are required (Type 1) while others are optional (Type 3/1C). If enforce_file_format is `False` then the File Meta Information Group elements are all optional, otherwise an attempt will be made to add the required elements using dataset. See `write_file_meta_info()` for more information on which elements are required.

  The File Meta Information Group elements must be included within their own `FileMetaDataset` in the `dataset.file_meta` attribute.

  Encoding

  The preamble and prefix are encoding independent. The File Meta Information Group elements are encoded as Explicit VR Little Endian as required by the DICOM Standard.

  Dataset

  A DICOM Dataset representing a SOP Instance related to a DICOM Information Object Definition (IOD). It’s up to the user to ensure dataset conforms to the requirements of the IOD.

  Encoding

  Changed in version 3.0: Added the implicit_vr and little_endian arguments.

  The dataset is encoded as specified by (in order of priority):

  - The encoding corresponding to the set Transfer Syntax UID in `file_meta`.

  - The implicit_vr and little_endian arguments

  - `is_implicit_VR` and `is_little_endian`

  - `original_encoding`

  Warning

  This function does not automatically convert dataset from little to big endian encoding (or vice versa). The endianness of values for elements with a VR of OD, OF, OL, OW, OV and UN must be converted manually prior to calling `dcmwrite()`.

  Parameters:

    - filename (str, PathLike, file-like or writeable buffer) – File path, file-like or writeable buffer to write the encoded dataset to. If using a writeable buffer it must have `write()`, `seek()` and `tell()` methods.

    - dataset (pydicom.dataset.FileDataset) – The dataset to be encoded.

    - write_like_original (bool, optional) – If `True` (default) then write dataset as-is, otherwise ensure that dataset is written in the DICOM File Format or raise an exception if that isn’t possible. This parameter is deprecated, please use enforce_file_format instead.

    - implicit_vr (bool, optional) – Required if dataset has no valid public Transfer Syntax UID set in the file meta and dataset has been created from scratch. If `True` then encode dataset using implicit VR, otherwise use explicit VR.

    - little_endian (bool, optional) – Required if dataset has no valid public Transfer Syntax UID set in the file meta and dataset has been created from scratch. If `True` (default) then use little endian byte order when encoding dataset, otherwise use big endian.

    - enforce_file_format (bool, optional) –

      If `True` then ensure dataset is written in the DICOM File Format or raise an exception if that isn’t possible.

      If `False` (default) then write dataset as-is, preserving the following - which may result in a non-conformant file:

      - `dataset.preamble`: if dataset has no preamble then none will be written

      - `dataset.file_meta`: if dataset is missing any required File Meta Information Group elements then they will not be written.

    - force_encoding (bool, optional) – If `True` then force the encoding to follow implicit_vr and little_endian. Cannot be used with enforce_file_format. Default `False`.

    - overwrite (bool, optional) – If `False` and filename is a `str` or PathLike, then raise a `FileExistsError` if a file already exists with the given filename (default `True`).

  Raises:

    ValueError –

    - If group `0x0000` Command Set elements are present in dataset. * If group `0x0002` File Meta Information Group elements are present in dataset. * If `dataset.preamble` exists but is not 128 bytes long.

  See also

  `pydicom.dataset.Dataset`

    Dataset class with relevant attributes and information.

  `pydicom.dataset.Dataset.save_as`

    Encode a dataset and write it to file, wraps `dcmwrite()`.