Skip to content

Compress-Archive

SYNOPSIS

Creates a compressed archive, or zipped file, from specified files and directories.

SYNTAX

Path (Default)

Compress-Archive [-Path] <String[]> [-DestinationPath] <String> [-CompressionLevel <String>] [-PassThru]
 [-WhatIf] [-Confirm] [<CommonParameters>]

PathWithUpdate

Compress-Archive [-Path] <String[]> [-DestinationPath] <String> [-CompressionLevel <String>] [-Update]
 [-PassThru] [-WhatIf] [-Confirm] [<CommonParameters>]

PathWithForce

Compress-Archive [-Path] <String[]> [-DestinationPath] <String> [-CompressionLevel <String>] [-Force]
 [-PassThru] [-WhatIf] [-Confirm] [<CommonParameters>]

LiteralPathWithUpdate

Compress-Archive -LiteralPath <String[]> [-DestinationPath] <String> [-CompressionLevel <String>] [-Update]
 [-PassThru] [-WhatIf] [-Confirm] [<CommonParameters>]

LiteralPathWithForce

Compress-Archive -LiteralPath <String[]> [-DestinationPath] <String> [-CompressionLevel <String>] [-Force]
 [-PassThru] [-WhatIf] [-Confirm] [<CommonParameters>]

LiteralPath

Compress-Archive -LiteralPath <String[]> [-DestinationPath] <String> [-CompressionLevel <String>] [-PassThru]
 [-WhatIf] [-Confirm] [<CommonParameters>]

DESCRIPTION

The `Compress-Archive` cmdlet creates a compressed, or zipped, archive file from one or more specified files or directories. An archive packages multiple files, with optional compression, into a single zipped file for easier distribution and storage. An archive file can be compressed by using the compression algorithm specified by the CompressionLevel parameter.

The `Compress-Archive` cmdlet uses the Microsoft .NET API System.IO.Compression.ZipArchive (/dotnet/api/system.io.compression.ziparchive)to compress files. The maximum file size is 2 GB because there's a limitation of the underlying API.

Some examples use splatting to reduce the line length of the code samples. For more information, see about_Splatting (../Microsoft.PowerShell.Core/About/about_Splatting.md).

EXAMPLES

Example 1: Compress files to create an archive file

$compress = @{
  Path = "C:\Reference\Draftdoc.docx", "C:\Reference\Images\*.vsd"
  CompressionLevel = "Fastest"
  DestinationPath = "C:\Archives\Draft.Zip"
}
Compress-Archive @compress

The Path parameter accepts specific file names and file names with wildcards, `*.vsd`. The Path uses a comma-separated list to get files from different directories. The compression level is Fastest to reduce processing time. The DestinationPath parameter specifies the location for the `Draft.zip` file. The `Draft.zip` file contains `Draftdoc.docx` and all the files with a `.vsd` extension.

Example 2: Compress files using a LiteralPath

$compress = @{
LiteralPath= "C:\Reference\Draft Doc.docx", "C:\Reference\Images\diagram2.vsd"
CompressionLevel = "Fastest"
DestinationPath = "C:\Archives\Draft.Zip"
}
Compress-Archive @compress

Absolute path and file names are used because the LiteralPath parameter doesn't accept wildcards. The Path uses a comma-separated list to get files from different directories. The compression level is Fastest to reduce processing time. The DestinationPath parameter specifies the location for the `Draft.zip` file. The `Draft.zip` file only contains `Draftdoc.docx` and `diagram2.vsd`.

Example 3: Compress a directory that includes the root directory

Compress-Archive -Path C:\Reference -DestinationPath C:\Archives\Draft.zip

`Compress-Archive` uses the Path parameter to specify the root directory, `C:\Reference`. The DestinationPath parameter specifies the location for the archive file. The `Draft.zip` archive includes the `Reference` root directory, and all its files and subdirectories.

Example 4: Compress a directory that excludes the root directory

Compress-Archive -Path C:\Reference\* -DestinationPath C:\Archives\Draft.zip

`Compress-Archive` uses the Path parameter to specify the root directory, `C:\Reference` with an asterisk (` `) wildcard. The DestinationPath * parameter specifies the location for the archive file. The `Draft.zip` archive contains the root directory's files and subdirectories. The `Reference` root directory is excluded from the archive.

Example 5: Compress only the files in a root directory

Compress-Archive -Path C:\Reference\*.* -DestinationPath C:\Archives\Draft.zip

`Compress-Archive` uses the Path parameter to specify the root directory, `C:\Reference` with a star-dot-star (` . `) wildcard. The DestinationPath parameter specifies the location for the archive file. The `Draft.zip` archive only contains the `Reference` root directory's files and the root directory is excluded.

Example 6: Use the pipeline to archive files

Get-ChildItem -Path C:\Reference\Afile.txt, C:\Reference\Images\Bfile.txt |
  Compress-Archive -DestinationPath C:\Archives\PipelineFiles.zip

`Get-ChildItem` uses the Path parameter to specify two files from different directories. Each file is represented by a FileInfo object and is sent down the pipeline to `Compress-Archive`. The two specified files are archived in `PipelineFiles.zip`.

Example 7: Use the pipeline to archive a directory

Get-ChildItem -Path C:\LogFiles | Compress-Archive -DestinationPath C:\Archives\PipelineDir.zip

`Get-ChildItem` uses the Path parameter to specify the `C:\LogFiles` root directory. Each FileInfo and DirectoryInfo object is sent down the pipeline.

`Compress-Archive` adds each object to the `PipelineDir.zip` archive. The Path parameter isn't specified because the pipeline objects are received into parameter position 0.

Example 8: How recursion can affect archives

Get-ChildItem -Path C:\TestLog -Recurse |
  Compress-Archive -DestinationPath C:\Archives\PipelineRecurse.zip

The `C:\TestLog` directory doesn't contain any files. It does contain a subdirectory named `testsub` that contains the `testlog.txt` file.

`Get-ChildItem` uses the Path parameter to specify the root directory, `C:\TestLog`. The Recurse parameter processes the files and directories. A DirectoryInfo object is created for `testsub` and a FileInfo object `testlog.txt`.

Each object is sent down the pipeline to `Compress-Archive`. The DestinationPath specifies the location for the archive file. The Path parameter isn't specified because the pipeline objects are received into parameter position 0.

The following summary describes the `PipelineRecurse.zip` archive's contents that contains a duplicate file:

  • The DirectoryInfo object creates the `testsub` directory and contains the `testlog.txt` file, which reflects the original directory structure. - The FileInfo object creates a duplicate `testlog.txt` in the archive's root. The duplicate file is created because recursion sent a file object to `Compress-Archive`. This behavior is expected because each object sent down the pipeline is added to the archive.

Example 9: Update an existing archive file

Compress-Archive -Path C:\Reference -Update -DestinationPath C:\Archives\Draft.Zip

The command updates `Draft.Zip` with newer versions of existing files in the `C:\Reference` directory and its subdirectories. And, new files that were added to `C:\Reference` or its subdirectories are included in the updated `Draft.Zip` archive.

PARAMETERS

-CompressionLevel

Specifies how much compression to apply when you're creating the archive file. Faster compression requires less time to create the file, but can result in larger file sizes.

If this parameter isn't specified, the command uses the default value, Optimal .

The following are the acceptable values for this parameter:

  • Fastest . Use the fastest compression method available to reduce processing time. Faster compression can result in larger file sizes. - NoCompression . Doesn't compress the source files. - Optimal . Processing time is dependent on file size.
Type: System.String
Parameter Sets: (All)
Aliases:
Accepted values: Optimal, NoCompression, Fastest

Required: False
Position: Named
Default value: Optimal
Accept pipeline input: False
Accept wildcard characters: False

-DestinationPath

This parameter is required and specifies the path to the archive output file. The DestinationPath should include the name of the zipped file, and either the absolute or relative path to the zipped file.

If the file name in DestinationPath doesn't have a `.zip` file name extension, the cmdlet adds the `.zip` file name extension.

Type: System.String
Parameter Sets: (All)
Aliases:

Required: True
Position: 1
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-Force

Forces the command to run without asking for user confirmation.

Type: System.Management.Automation.SwitchParameter
Parameter Sets: PathWithForce, LiteralPathWithForce
Aliases:

Required: True
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False

-LiteralPath

Specifies the path or paths to the files that you want to add to the archive zipped file. Unlike the Path parameter, the value of LiteralPath is used exactly as it's typed. No characters are interpreted as wildcards. If the path includes escape characters, enclose each escape character in single quotation marks, to instruct PowerShell not to interpret any characters as escape sequences. To specify multiple paths, and include files in multiple locations in your output zipped file, use commas to separate the paths.

Type: System.String[]
Parameter Sets: LiteralPathWithUpdate, LiteralPathWithForce, LiteralPath
Aliases: PSPath

Required: True
Position: Named
Default value: None
Accept pipeline input: True (ByPropertyName)
Accept wildcard characters: False

-PassThru

Causes the cmdlet to output a file object representing the archive file created.

This parameter was introduced in PowerShell 6.0.

Type: System.Management.Automation.SwitchParameter
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False

-Path

Specifies the path or paths to the files that you want to add to the archive zipped file. To specify multiple paths, and include files in multiple locations, use commas to separate the paths.

This parameter accepts wildcard characters. Wildcard characters allow you to add all files in a directory to your archive file.

Using wildcards with a root directory affects the archive's contents:

  • To create an archive that includes the root directory, and all its files and subdirectories, specify the root directory in the Path without wildcards. For example: `-Path C:\Reference` - To create an archive that excludes the root directory, but zips all its files and subdirectories, use the asterisk (` `) wildcard. For example: `-Path C:\Reference\ ` - To create an archive that only zips the files in the root directory, use the star-dot-star (` . `) wildcard. Subdirectories of the root aren't included in the archive. For example: `-Path C:\Reference\ . `
Type: System.String[]
Parameter Sets: Path, PathWithUpdate, PathWithForce
Aliases:

Required: True
Position: 0
Default value: None
Accept pipeline input: True (ByPropertyName, ByValue)
Accept wildcard characters: False

-Update

Updates the specified archive by replacing older file versions in the archive with newer file versions that have the same names. You can also add this parameter to add files to an existing archive.

Type: System.Management.Automation.SwitchParameter
Parameter Sets: PathWithUpdate, LiteralPathWithUpdate
Aliases:

Required: True
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False

-Confirm

Prompts you for confirmation before running the cmdlet.

Type: System.Management.Automation.SwitchParameter
Parameter Sets: (All)
Aliases: cf

Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False

-WhatIf

Shows what would happen if the cmdlet runs. The cmdlet isn't run.

Type: System.Management.Automation.SwitchParameter
Parameter Sets: (All)
Aliases: wi

Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False

CommonParameters

This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.

INPUTS

System.String

You can pipe a string that contains a path to one or more files.

OUTPUTS

System.IO.FileInfo

The cmdlet only returns a FileInfo object when you use the PassThru parameter.

NOTES

Using recursion and sending objects down the pipeline can duplicate files in your archive. For example, if you use `Get-ChildItem` with the Recurse parameter, each FileInfo and DirectoryInfo object that's sent down the pipeline is added to the archive.

The ZIP file specification (https://pkware.cachefly.net/webdocs/casestudies/APPNOTE.TXT)does not specify a standard way of encoding filenames that contain non-ASCII characters. The `Compress-Archive` cmdlet uses UTF-8 encoding. Other ZIP archive tools may use a different encoding scheme. When extracting files with filenames not stored using UTF-8 encoding, `Expand-Archive` uses the raw value found in the archive. This can result in a filename that is different than the source filename stored in the archive.

Expand-Archive

Get-ChildItem

Back to top