# Bitbucket File Size Limit: Repository Limits, Git LFS, and Large Assets

Bitbucket enforces a soft repository size warning at 2GB, a hard push restriction at 4GB, and blocks individual files exceeding 100MB unless tracked via Git Large File Storage (LFS). Pushing large binary assets like model checkpoints, datasets, or build archives into standard Git history causes pre-receive hook rejections. This guide details Cloud versus Data Center limits, step-by-step history rewrites with git-filter-repo, and external workspace patterns for large assets.

Source: https://fast.io/resources/bitbucket-file-size-limit/
Author: [Derek Labian](https://fast.io/authors/derek-labian/)
Last reviewed: 2026-10-13

## What Are Bitbucket Cloud File Size and Repository Storage Limits?

Bitbucket Cloud repositories enforce a strict 4 GB hard repository size limit, display a warning at 2 GB, and block any standard Git push containing individual files of 100 MB or larger unless managed through Git Large File Storage.

When development teams and automated pipelines interact with Bitbucket Cloud, repository size boundaries dictate whether code pushes succeed or fail at the remote pre-receive hook. Many developers encounter these limits abruptly when an uncompressed dataset, a machine learning model weight, a database export, or a compiled binary lands in a commit. Git was built to manage line-by-line differences in source code, not to host multi-gigabyte binary files. Because Git packfiles duplicate or compress binary objects inefficiently across revisions, bloated repositories degrade clone speeds, inflate local disk usage, and place excessive resource demands on remote hosting infrastructure.

To maintain platform stability across its multi-tenant architecture, Atlassian implements several thresholds documented in the official [Bitbucket repository size documentation](https://support.atlassian.com/bitbucket-cloud/docs/reduce-repository-size/):

- **100 MB Per-File Push Limit**: Bitbucket Cloud inspects every incoming push with a pre-receive hook that blocks any individual file exceeding the 100 MB limit unless tracked via Git LFS. While administrators can toggle this push restriction in repository settings under the advanced section, turning off the setting is strongly discouraged because unconstrained commits bloat repository packfiles.
- **2 GB Soft Repository Warning**: Atlassian recommends that repositories stay below 2 GB to maintain fast network operations, rapid branch switching, and quick CI/CD checkouts. When a repository reaches 2 GB, Bitbucket Cloud displays a warning banner in the repository details panel notifying team members that the repository has reached halfway to the hard limit.
- **4 GB Hard Repository Limit**: Bitbucket Cloud repositories enforce an absolute maximum capacity of 4 GB. When a repository exceeds 4 GB, Bitbucket Cloud disables your ability to push any commits that add new data. The remote server rejects incoming commits with an explicit size limit error. Pushes that undo commits or roll back changes are permitted so teams can recover their repositories.
- **1 GB Workspace Storage Limit on Free Plans**: In Bitbucket Cloud, if total storage across all repositories in a Free workspace surpasses 1 GB, the workspace enters a read-only state. Team members cannot push new commits, create branches, or open pull requests until the workspace reduces its storage footprint or upgrades to a Standard or Premium plan.

| Limit Type | Threshold | Enforcement Mechanism | Impact on Development |
|---|---|---|---|
| Per-File Push Limit | 100 MB | Pre-receive hook | Rejects pushes containing individual blobs >= 100 MB |
| Soft Repository Limit | 2 GB | UI notification | Displays warning banner in repository details panel |
| Hard Repository Limit | 4 GB | Remote push block | Rejects all data-adding pushes until history is reduced |
| Free Workspace Pool | 1 GB total | Workspace read-only state | Locks pushes, branch creation, and PRs across all repos |
| Git LFS Per-File Cap | No limit | Storage policy | Allows large assets of any size tracked via Git LFS |

Understanding these specific thresholds prevents unexpected pipeline outages. When teams track binary dependencies, test suites, or generated assets inside version control, they risk turning a quick hotfix deployment into an emergency Git history remediation session.

## How Bitbucket Cloud Compares to Bitbucket Data Center Limits

A frequent source of confusion among systems engineers and DevOps administrators is the difference between Bitbucket Cloud and Bitbucket Data Center. Articles and forum discussions often debate Bitbucket repository limits without distinguishing whether they apply to Atlassian's multi-tenant cloud service or self-hosted enterprise infrastructure.

Bitbucket Server reached its official end-of-life on February 15, 2024. Teams running on-premises Atlassian source control today operate Bitbucket Data Center, which uses an entirely different architecture from Bitbucket Cloud:

### Bitbucket Cloud Multi-Tenant Controls

Bitbucket Cloud is a software-as-a-service platform managed by Atlassian. Because thousands of organizations share the same underlying compute and storage clusters, Atlassian enforces rigid, programmatic caps to prevent single repositories from degrading node performance. Bitbucket Cloud enforces the 4 GB repository ceiling, the 2 GB warning threshold, the 100 MB push hook, and the 1 GB Free workspace cap as hardcoded guardrails. Customers cannot file a support ticket to raise the 4 GB repository ceiling on Bitbucket Cloud; Atlassian's official engineering policy requires teams to reduce repository size or move assets to Git LFS.

### Bitbucket Data Center Host-Level Controls

Bitbucket Data Center is installed on dedicated servers, virtual machines, or Kubernetes clusters owned and managed by your organization. Bitbucket Data Center does not have an inherent, hardcoded 4 GB repository size limit or a mandatory 100 MB per-file push block in the core application.

Instead, limits in Bitbucket Data Center are governed by your hosting infrastructure:

- **Filesystem Capacity**: Repositories can grow as large as the underlying storage volume permits. Repositories reaching massive storage footprints can exist without the application automatically refusing pushes.
- **Reverse Proxy and Web Server Buffers**: File push limits are controlled by web proxies such as Nginx, HAProxy, or Apache. For example, an Nginx reverse proxy fronting Bitbucket Data Center enforces limits via the client max body size directive. If this parameter is set lower than an incoming push payload, Git pushes fail with HTTP 413 (Payload Too Large).
- **Java Virtual Machine Heap Allocation**: Processing massive Git packfiles during push and merge operations requires substantial JVM memory. If developers push multiple large binary files simultaneously, the Bitbucket Data Center instance can suffer from JVM heap exhaustion or Git process timeouts unless administrators tune command timeouts and heap parameters.
- **Custom Pre-Receive Hooks**: While Bitbucket Cloud provides an out-of-the-box toggle for 100 MB files, Data Center administrators must deploy custom pre-receive hook scripts or marketplace apps to enforce explicit per-file or per-repository size limits across projects.

| Feature or Characteristic | Bitbucket Cloud (SaaS) | Bitbucket Data Center (Self-Hosted) |
|---|---|---|
| Hard Repository Size Limit | 4 GB (strictly enforced) | No software limit; bounded by host disk capacity |
| Soft Size Warning | 2 GB (automatic UI banner) | Custom administrative monitoring / disk alerts |
| Single File Push Limit | 100 MB default pre-receive hook | Configured via reverse proxy buffer settings |
| Free Plan Storage Pool | 1 GB total across workspace | Not applicable (licensed per user tier on own hardware) |
| Git LFS Backend | Managed AWS S3 storage | Local disk, shared NFS, AWS S3, or Azure Blob |
| Git LFS Overage Model | $10/month per 100 GB block | Standard infrastructure and storage operational costs |
| Garbage Collection | Automatic on rollback/reset | Scheduled maintenance jobs or manual execution |

When planning migration projects from Bitbucket Data Center to Bitbucket Cloud, repository size audits are mandatory. A legacy repository that grew unhindered on an internal server will fail import into Bitbucket Cloud until its history is scrubbed below the 4 GB ceiling.

## How to Diagnose and Resolve Oversized Commits and Push Failures

When a git push command is rejected by Bitbucket Cloud, identifying the exact files and commits causing the error is the first step toward recovery. A push failure generally manifests in one of two ways: an individual file exceeding 100 MB blocked by the pre-receive hook, or a cumulative repository size exceeding the 4 GB hard limit.

### Identifying Oversized Objects in Local History

When Git attempts to push commits, it packs objects into a packfile. If an oversized binary exists anywhere in the unpushed commit range or past history, the remote hook declines the entire transaction.

Run this command in your repository terminal to list the largest objects in your Git database:

```bash
git rev-list --objects --all \
  | git cat-file --batch-check='%(objecttype) %(objectname) %(objectsize) %(rest)' \
  | grep '^blob' \
  | sort -k3 -n \
  | tail -10
```

In the command output, any blob size exceeding the Bitbucket Cloud 100 MB file limit indicates a file that the remote hook will reject. To scan your active working tree for large files before staging them, run:

```bash
find . -type f -size +100M -not -path './.git/*'
```

### Fixing an Unpushed Commit

If you committed an individual file over 100 MB locally but have not yet pushed it to your Bitbucket repository, recovery is straightforward. Do not create a new commit that simply deletes the file using git rm. In Git, creating a new commit to delete an object keeps the original object preserved in the previous commit's tree, meaning the push will still contain the forbidden blob.

Instead, remove the file from Git's index while preserving it on your local disk, and amend the commit:

```bash
git rm --cached path/to/oversized-asset.zip
git commit --amend -CHEAD
git push origin main
```

Adding the file pattern to your .gitignore file prevents Git from staging it again in future commits.

### Scrubbing Pushed Files with git-filter-repo

If an oversized commit was already pushed to Bitbucket Cloud, or if past historical commits have pushed your total repository size past the 2 GB warning or 4 GB hard limit, you must rewrite history to strip the offending objects.

Historically, Atlassian documentation suggested using tools like BFG Repo-Cleaner or the legacy git filter-branch command. However, modern Git documentation and the official Git project maintainers strongly recommend git-filter-repo. Written in Python, git-filter-repo is faster, handles commit hashes, branch pointers, and tag references safely, and avoids common edge-case corruptions.

Follow this step-by-step procedure to clean your Bitbucket repository:

#### Step 1: Create a Full Backup Clone

Rewriting history alters commit SHAs across your repository. Always create a full mirror backup before performing any filtering operation:

```bash
git clone --mirror git@bitbucket.org:workspace/my-repo.git my-repo-backup.git
```

#### Step 2: Make a Fresh Working Clone

Clone a fresh copy of your repository to run the cleanup tool:

```bash
git clone git@bitbucket.org:workspace/my-repo.git my-repo-cleanup
cd my-repo-cleanup
```

#### Step 3: Run git-filter-repo

You can strip large files by size threshold or by targeting specific file paths.

You can use git-filter-repo to remove all historical files exceeding the Bitbucket repository 100 MB limit across branches. Run this command:

```bash
git-filter-repo --strip-blobs-bigger-than 100M
```

Alternatively, if you know the exact path of an archived directory or large archive file that was mistakenly committed, run:

```bash
git-filter-repo --path models/weights.bin --invert-paths
```

#### Step 4: Reconnect Remote and Force Push

When git-filter-repo finishes, it removes the remote origin URL to protect against accidental pushes. Re-add your Bitbucket remote origin and force-push the rewritten branches and tags:

```bash
git remote add origin git@bitbucket.org:workspace/my-repo.git
git push origin --force --all
git push origin --force --tags
```

#### Step 5: Verify Bitbucket Garbage Collection

Once you force-push rewritten branches that remove the large commits, Bitbucket Cloud automatically initiates an internal garbage collection process. Dangling commits and unreferenced blobs are purged, and your repository size in the repository details panel recalculates to reflect the reduced footprint. In Bitbucket Cloud, once the repository size drops below the 4 GB limit, push access is automatically restored.

## When to Use Git Large File Storage for Bitbucket Repositories

When projects require versioned binary assets alongside source code, Git Large File Storage (Git LFS) provides the native solution supported by Bitbucket Cloud.

### How Git LFS Operates

In a standard Git repository, every version of every file is stored directly within the local .git directory on every machine that clones the repository. When a large media asset or trained model checkpoint changes repeatedly across branches, clones download the full cumulative history.

Git LFS alters this storage model. Instead of writing the full binary payload into the Git object tree, Git LFS intercepts the file during staging and replaces it with a tiny pointer file. The pointer file contains metadata identifying the real object:

```text
version https://git-lfs.github.com/spec/v1
oid sha256:7f83b1657ff1fc53b92dc18148a1d65dfc2d4b1fa3d677284addd200126d9069
size 345812904
```

The Git repository tracks only this text pointer, which consumes roughly 130 bytes in Git packfiles. The actual binary data transfers via HTTPS directly to Bitbucket's managed object storage backend on Amazon Web Services S3. When a developer checks out a branch, Git LFS downloads only the specific binary revisions needed for the active working tree.

### Configuring Git LFS for Bitbucket Cloud

To use Git LFS with your Bitbucket repository:

1. Install the Git LFS extension on your workstation:
  

```bash
   git lfs install
  

```

2. Define which file patterns should be managed by LFS:
  

```bash
   git lfs track "*.onnx"
   git lfs track "*.psd"
   git lfs track "*.tar.gz"
  

```

3. Commit the generated .gitattributes configuration file:
  

```bash
   git add .gitattributes
   git commit -m "Configure Git LFS tracking rules"
  

```

4. Add and commit your binary assets normally:
  

```bash
   git add models/checkpoint.onnx
   git commit -m "Add model checkpoint via Git LFS"
   git push origin main
  

```

### Storage Quotas and Pricing for Git LFS on Bitbucket Cloud

As detailed in the official [Git LFS storage policy documentation](https://support.atlassian.com/bitbucket-cloud/docs/storage-policy-for-git-lfs-with-bitbucket/), Bitbucket Cloud includes pooled Git LFS storage allocations based on your workspace subscription tier:

- **Free Plan**: 1 GB of included Git LFS storage
- **Academic Plan**: 5 GB of included Git LFS storage
- **Standard Plan**: 5 GB of included Git LFS storage
- **Premium Plan**: 10 GB of included Git LFS storage

Bitbucket Cloud enforces no individual file size limit when pushing Git LFS files, subject only to cloud object single-upload constraints. If your workspace exceeds its included Git LFS storage pool, Bitbucket Cloud automatically adds additional storage in blocks of 100 GB for $10 monthly.

### Operational Friction and Constraints of Git LFS

While Git LFS solves the raw Git object size limit, engineering teams frequently experience operational challenges when relying on LFS at scale:

- **CI/CD Pipeline Latency**: Build runners in Bitbucket Pipelines or external systems must execute git lfs pull during checkout. Fetching multi-gigabyte LFS objects on ephemeral build containers lengthens deployment cycles and increases pipeline minute consumption.
- **Bandwidth Expenses**: If automated build systems or remote development environments frequently clone LFS-heavy repositories from scratch, workspace LFS bandwidth consumption climbs rapidly.
- **Lack of In-Browser Collaboration**: Non-technical team members, stakeholders, and external clients cannot easily browse, search, or inspect files managed via Git LFS pointers directly within Bitbucket's web interface.
- **Merge Conflicts in Pointer Files**: If two developers or automated agents modify LFS-tracked assets concurrently on separate branches, resolving binary merge conflicts requires manual checkout and overwrite steps.

## How Decoupling Large Assets Keeps Bitbucket Repositories Lean

The rise of AI coding agents, automated data pipelines, and machine learning workflows has magnified the friction of Git file size limits. Autonomous development tools like Claude Code, Cursor, Codex, Devin, and Cline frequently generate or consume assets that break traditional source control:

- Synthetic test suites with large SQLite database dumps
- Embeddings corpora and vector store indexes
- Scraped training datasets and JSON document caches
- High-resolution rendering frames, audio files, and model checkpoints
- Packaged client deliverables and compiled distribution tarballs

Committing these assets to Bitbucket triggers the 100 MB pre-receive hook or rapidly pushes the repository toward the 2 GB warning and 4 GB push lockout. Even with Git LFS, managing dynamic agent outputs through commit pointers creates merge friction and ballooning cloud storage bills.

The architectural solution is decoupling: maintain pure source code and configuration files in Bitbucket, while offloading large assets, datasets, and agent outputs to external persistent cloud storage.

### Evaluating Storage Layers for Large Assets

Teams evaluating where to store large project assets typically compare three primary options:

1. **Object Storage (AWS S3, Google Cloud Storage, Cloudflare R2)**:
   - *Strengths*: Highly scalable, low cost per gigabyte, direct programmatic API access.
   - *Limitations*: No built-in version history UI, no document content indexing, complex IAM credential management for cross-functional teams, and no natural collaboration interface for non-developer stakeholders.

2. **Traditional Cloud Sync (Dropbox, Box, Microsoft OneDrive)**:
   - *Strengths*: Familiar desktop sync folders, broad consumer and enterprise adoption.
   - *Limitations*: Designed primarily for human office documents, desktop sync latency that clashes with headless CI/CD runners, and lack of native Model Context Protocol (MCP) integrations for AI agents.

3. **Intelligent Workspaces ([Fastio Workspaces](/product/workspaces/))**:
   - *Strengths*: Purpose-built for human-agent collaboration. Provides generous per-file upload caps, built-in search, and native MCP connectivity.

### How Fastio Bridges Bitbucket and Large Asset Workflows

Fastio provides shared, organization-owned cloud workspaces where developers and AI agents collaborate on large assets without stressing Git repositories:

- **High-Capacity File Uploads**: Fastio supports file uploads up to 25 GB on Starter, 50 GB on Business, and 100 GB on Enterprise, keeping repositories far below the Bitbucket Cloud 4 GB limit. Monthly subscriptions begin with a 14-day free trial requiring a credit card.
- **Native MCP Integration for AI Agents**: AI coding agents connect directly to Fastio using the Model Context Protocol over Streamable HTTP. Coding agents connect to `https://mcp.fast.io/mcp/code`, while general personal agents and Claude connect at `https://mcp.fast.io/mcp/tools`. Agents read and write datasets, logs, and artifacts directly in workspace storage without writing multi-gigabyte binaries into local Git working trees.
- **Built-in Intelligence Mode**: When [Fastio AI](/product/ai/) Intelligence Mode is enabled on a workspace, files are automatically indexed for full-text and semantic search. AI assistants can query multi-gigabyte document collections and retrieve answers with citations, eliminating the need to attach massive files directly into context windows.
- **Per-File Version History and Detailed Activity Log**: Every file maintains full version history, allowing teams to review and restore previous revisions. Organizations maintain visibility through a detailed activity log of changes, tracking uploads, edits, moves, and deletions across both human team members and AI agents.
- **Secure External Sharing**: Instead of checking client deliverables or distribution builds into Bitbucket, teams generate [Fastio Sharing](/product/sharing/) links with per-recipient access, expiration dates, and the option to disable file downloads.
- **Cloud Connectors**: Workspaces support cloud import from Google Drive, Dropbox, OneDrive, Box, or direct URLs. Workspaces also support Cloud Sync for Google Drive, Dropbox, Box, and OneDrive on a scheduled or on-demand basis.

By decoupling large assets into dedicated workspaces, engineering teams keep their Bitbucket repositories lightweight, ensure CI/CD pipelines clone in seconds, and give AI coding assistants the persistent storage required for modern development.

## Frequently asked questions

### What is the maximum file size you can push to Bitbucket?

Bitbucket Cloud enforces a default file size limit of 100 MB for individual files pushed to a repository. Any push containing a file larger than 100 MB is declined by a pre-receive hook unless the file is tracked via Git Large File Storage (LFS). While administrators can disable the Bitbucket repository 100 MB file push limit in settings, tracking large files in standard Git history causes rapid repository bloat.

### What is the repository size limit in Bitbucket Cloud?

Bitbucket Cloud enforces an absolute hard repository limit of 4 GB across all plans. In Bitbucket Cloud, pushes that add data to a repository exceeding the 4 GB limit are blocked. Bitbucket also triggers a soft warning banner in the repository details panel when a repository reaches 2 GB. In addition, workspaces on the Free plan share a total storage cap of 1 GB across all repositories.

### How do I push a file larger than 100 MB to a Bitbucket Cloud repository?

To push files larger than 100 MB to a Bitbucket Cloud repository, configure Git LFS on your machine using git lfs track and commit the .gitattributes file. Git LFS stores text pointer files in your Git repository and offloads the actual binary assets to Bitbucket's managed storage backend, with no individual LFS file size limit.

### What happens when a Bitbucket repository reaches the 4 GB limit?

When a repository reaches 4 GB, Bitbucket Cloud rejects all incoming pushes that attempt to add new data with a pre-receive hook error. You can still push commits that undo, revert, or rewind previous commits to reduce the repository size. In Bitbucket Cloud, once the repository size drops below the 4 GB limit, Bitbucket Cloud automatically runs garbage collection and restores full push access.

### Does Bitbucket Data Center have the same 4 GB limit as Bitbucket Cloud?

No. Bitbucket Data Center is self-hosted and does not have a hardcoded 4 GB repository cap or 100 MB per-file push limit. Size constraints on Data Center depend entirely on the underlying host filesystem capacity, reverse proxy buffer settings like client max body size in Nginx, and JVM heap memory configuration.

### How much does extra Git LFS storage cost on Bitbucket Cloud?

Bitbucket Cloud includes 1 GB of Git LFS storage on the Free plan, 5 GB on Standard and Academic plans, and 10 GB on Premium plans. If your workspace exceeds its included Git LFS storage pool, Bitbucket Cloud automatically adds additional storage in blocks of 100 GB for $10 monthly.

### Can I remove a large file from Bitbucket by deleting it in a new commit?

No. Git preserves the entire historical record of all commits. Deleting a file in a new commit leaves the large blob inside previous commits, meaning the repository size does not shrink and push limits will still be triggered. You must rewrite repository history using git-filter-repo and execute a force push to purge the blob completely.

## Sources

- [Atlassian Support: Reduce repository size](https://support.atlassian.com/bitbucket-cloud/docs/reduce-repository-size/): Bitbucket Cloud repositories enforce a 100 MB file size limit on pushes, issue a 2 GB repository size warning, and block pushes at a 4 GB repository limit.
- [Atlassian Support: Storage policy for Git LFS with Bitbucket](https://support.atlassian.com/bitbucket-cloud/docs/storage-policy-for-git-lfs-with-bitbucket/): Bitbucket Cloud Git Large File Storage tiers include 1 GB on Free workspaces, 5 GB on Standard, and 10 GB on Premium, with no individual LFS file cap and $10 monthly per 100 GB additional storage.

## About Fast.io

Fast.io provides shared workspaces where people and AI agents work on the same files, with built-in semantic search and citation-backed chat over what they hold. Agents reach it through a remote MCP server, a REST API at https://api.fast.io/current/, and a command line client published on npm as @vividengine/fastio-cli. MCP setup is at https://mcp.fast.io/docs: Claude and most MCP clients connect to https://mcp.fast.io/mcp/tools, ChatGPT to https://mcp.fast.io/mcp/operations, and coding agents to https://mcp.fast.io/mcp/code.