> For the complete documentation index, see [llms.txt](https://boxlang.ortusbooks.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://boxlang.ortusbooks.com/boxlang-framework/file-handling/compression.md).

# Compression and Archives

BoxLang provides built-in functions and components for creating, reading, extracting, and managing compressed files. Use `compress()` and `extract()` for straightforward archive workflows, or use `<bx:zip>` when you need to list entries, read content, filter files, or add in-memory content with `<bx:zipParam>`.

## Compress an archive

Pass the source and destination as named arguments when creating an archive:

```js
compress(
    source = "/tmp/project",
    destination = "/tmp/project.tar.gz",
    format = "tar.gz"
)
```

`source` may be a file or directory. When the source is a directory, `compress()` includes its contents recursively by default. Set `includeBaseFolder = false` when the archive should contain the directory contents without the top-level directory name.

```js
compress(
    source = "/tmp/project",
    destination = "/tmp/project.zip",
    format = "zip",
    includeBaseFolder = false,
    compressionLevel = 9
)
```

## Extract an archive

Use `destination` for the output directory:

```js
extract(
    source = "/tmp/project.tbz2",
    destination = "/tmp/project-out",
    format = "tbz2"
)
```

The `destination` argument replaces the older `target` spelling. The transpiler maps `target` to `destination` for compatibility with older source code.

Use `overwrite`, `filter`, and `entryPaths` to control extraction:

```js
extract(
    source = "/tmp/project.tar.gz",
    destination = "/tmp/project-out",
    format = "tar.gz",
    overwrite = true,
    filter = ( path ) => path.endsWith( ".json" )
)
```

{% hint style="info" %}
When an archive is created inside the directory being compressed, BoxLang avoids adding the archive itself to the archive. This supports destinations such as `/tmp/project/project.zip` without recursively including the output file.
{% endhint %}

## Supported archive formats

| Format   | `compress()` | `extract()` |
| -------- | :----------: | :---------: |
| `zip`    |      Yes     |     Yes     |
| `gzip`   |      Yes     |     Yes     |
| `bzip`   |      Yes     |     Yes     |
| `bzip2`  |      Yes     |     Yes     |
| `tar`    |      Yes     |     Yes     |
| `tar.bz` |      Yes     |      No     |
| `tbz`    |      Yes     |     Yes     |
| `tbz2`   |      Yes     |     Yes     |
| `tgz`    |      Yes     |     Yes     |
| `tar.gz` |      Yes     |     Yes     |

## ZIP components

The `<bx:zip>` component creates and manages ZIP archives. Use its `action` attribute to choose whether to create an archive, extract it, inspect its entries, read entry content, or remove entries.

### Actions

| Action       | Purpose                                                                                                   | Common attributes                                                    | Result                                           |
| ------------ | --------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- | ------------------------------------------------ |
| `zip`        | Add a file or directory to a ZIP archive. Use `<bx:zipParam>` for in-memory content or per-entry filters. | `file`, `source`, `recurse`, `overwrite`, `prefix`, `filter`         | Creates or updates the archive.                  |
| `unzip`      | Extract all or selected entries from a ZIP archive into a directory.                                      | `file`, `destination`, `entryPath`, `recurse`, `overwrite`, `filter` | Writes extracted files to `destination`.         |
| `list`       | List the entries in an archive.                                                                           | `file`, `entryPath`, `filter`, `flatList`, `recurse`, `result`       | Stores entry metadata or paths in `result`.      |
| `read`       | Read an entry as text.                                                                                    | `file`, `entryPath`, `charset`, `variable`                           | Stores the entry content in `variable`.          |
| `readBinary` | Read an entry as binary data.                                                                             | `file`, `entryPath`, `variable`                                      | Stores the binary content in `variable`.         |
| `delete`     | Remove one or more entries from an archive.                                                               | `file`, `entryPath`, `filter`                                        | Updates the archive without the deleted entries. |

The default action is `zip`. For `zip`, `file` is the archive to create or update and `source` identifies the input. For `unzip`, `destination` is the output directory. The `entryPath` attribute accepts a single path or an array of paths for entry-specific operations.

### Zip a file or directory

```xml
<bx:zip
    action="zip"
    file="/tmp/archive.zip"
    source="/tmp/project"
    recurse="true"
    overwrite="true">
</bx:zip>
```

The script form is also available:

```js
bx:zip
    action = "zip"
    file = "/tmp/archive.zip"
    source = "/tmp/project"
    recurse = true
    overwrite = true
```

### Extract a ZIP file

```xml
<bx:zip
    action="unzip"
    file="/tmp/archive.zip"
    destination="/tmp/project-out"
    overwrite="true">
</bx:zip>
```

### List or read entries

```js
bx:zip action = "list" file = "/tmp/archive.zip" result = "entries"

bx:zip
    action = "read"
    file = "/tmp/archive.zip"
    entryPath = "config/settings.json"
    variable = "settings"
```

### Add in-memory content

Use `<bx:zipParam>` to add content directly to an archive or to apply a source filter:

```xml
<bx:zip action="zip" file="/tmp/archive.zip">
    <bx:zipParam
        content="Hello BoxLang"
        entryPath="hello.txt">
    </bx:zipParam>
</bx:zip>
```

```xml
<bx:zip action="zip" file="/tmp/logs.zip" source="/tmp/logs">
    <bx:zipParam filter="*.log">
    </bx:zipParam>
</bx:zip>
```

## Related reference

* [`compress()`](/boxlang-language/reference/built-in-functions/zip/compress.md)
* [`extract()`](/boxlang-language/reference/built-in-functions/zip/extract.md)
* [`isZipFile()`](/boxlang-language/reference/built-in-functions/zip/iszipfile.md)
* [`<bx:zip>`](/boxlang-language/reference/components/zip/zip.md)
* [`<bx:zipParam>`](/boxlang-language/reference/components/zip/zipparam.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://boxlang.ortusbooks.com/boxlang-framework/file-handling/compression.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.