# Known Limitations

By design, Quilt is backed by Amazon S3 and scales to billions of objects and petabytes of data. The underlying limitations of S3 apply.

The Quilt catalog can browse packages and S3 buckets of any size.

## Catalog push

To ensure usability and quick package pushes, the Quilt web catalog imposes the following limits on pushes (which vary depending on whether the chunked checksums are enabled on the stack). These limits do not apply to the `quilt3` Python API.

| Dimension                                                  | Max (classic / chunked checksums) |
| ---------------------------------------------------------- | --------------------------------- |
| Package manifest size (metadata)                           | 100 MiB                           |
| Package size (data; via promotion or from an S3 directory) | 100 GiB / 5 TiB                   |
| Total size of uploaded files (soft limit)                  | 20 GB                             |
| Total size of files from S3 (soft limit)                   | 50 GB / 5 TB                      |
| Maximum file size                                          | 10 GiB / 5 TiB                    |
| Maximum number of files per push (soft limit)              | 1,000                             |
| Maximum number of files per push (hard limit)              | 5,000                             |

### Important note about S3 prefix enumeration

When creating a package from an S3 prefix (folder) using the Catalog GUI, the interface will display a warning if the prefix contains more than 1,000 files (the soft limit): "Total number of files exceeds recommended maximum of 1000." You can proceed past this warning, but the number of files the Catalog enumerates from S3 may vary, and browser performance may degrade with large file counts. The hard limit is 5,000 files per push (see table above). Additionally, S3 does not guarantee a stable ordering of listed objects, so the exact set of files included may differ between attempts.

**Workarounds for large directories:**

* Use the `quilt3` Python API's `Package.set_dir()` method, which has no such limitation
* Use the [Packaging Engine](/quilt-platform-catalog-user/packaging.md) to automate package creation from S3 prefixes
* Split your data into multiple packages, each under the 1,000 file limit

## API

As of this writing, with sufficient client-side memory, you can comfortable scale Quilt packages to at least one million objects per package, with no practical limit on object size (save S3's 5 TB per object limit). A fast network, or better yet an AWS compute instance in the same region as your Quilt S3 buckets, is recommended.

## Metadata

See [Metadata for teams](/metadata.md).


---

# Agent Instructions: 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:

```
GET https://docs.quilt.bio/quilt-python-sdk/api-reference/limitations.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.