A GitHub Action to free disk space on Ubuntu runners by removing unnecessary software and files.

💡 For Contributors & AI Agents: See AGENTS.md for technical details, development setup, and contribution guidelines.

• Compatibility
• Available Options
• What's New in v3
• Quick Start
• Common Use Cases
• Size Savings
• FAQ
• Contributing
• Changelog

• Ubuntu 22.04 - Tested on 21/08/2025.
• Ubuntu Latest (24.04) - Tested on 30/10/2025.

• 🔥 rmz Support: Use rmz for up to 3x faster file deletion
• 🛠️ DevContainer: Full development environment with Docker-in-Docker
• ✅ Pre-commit Hooks: Automated code quality checks with shellcheck and actionlint
• 📦 Workflow Templates: Refactored tests using reusable workflows
• 🔧 Better Error Handling: Improved validation and error messages
• 📝 Enhanced Documentation: Complete API reference and examples

The v3 is fully backward compatible with v2. To migrate:

# Before (v2)
- uses: endersonmenezes/free-disk-space@v2
  with:
    remove_android: true

# After (v3) - works the same
- uses: endersonmenezes/free-disk-space@v3
  with:
    remove_android: true
    
# After (v3) - with new features
- uses: endersonmenezes/free-disk-space@v3
  with:
    remove_android: true
    rm_cmd: "rmz"        # NEW: Faster deletion
    rmz_version: "3.1.1" # NEW: Specify rmz version

Breaking Changes: None! All v2 configurations work in v3.

New Optional Parameters:

• rm_cmd: Choose between rm (default) or rmz (faster)
• rmz_version: Specify rmz version when using rm_cmd: rmz

Free Disk Space Action are inspired by jlumbroso/free-disk-space

At work I came across a huge Docker image that still needed to be analyzed by a local security tool. This consumed the entire Runner and in addition to the repository I found, I needed to remove some packages, which led me to create a modification of the original repository.

I will maintain a Stable version of this project.

name: Free Disk Space (Ubuntu)
on:
  - push

jobs:
  free-disk-space:
    runs-on: ubuntu-latest
    steps:
      - name: Free Disk Space
        uses: endersonmenezes/free-disk-space@v3  # Use @main for latest, @v3 for stable
        with:
          remove_android: true
          remove_dotnet: true
          remove_haskell: true
          remove_tool_cache: true
          remove_swap: true
          remove_packages: "azure-cli google-cloud-cli microsoft-edge-stable google-chrome-stable firefox postgresql* temurin-* *llvm* mysql* dotnet-sdk-*"
          remove_packages_one_command: true
          remove_folders: "/usr/share/swift /usr/share/miniconda /usr/share/az* /usr/local/lib/node_modules /usr/local/share/chromium /usr/local/share/powershell /usr/local/julia /usr/local/aws-cli /usr/local/aws-sam-cli /usr/share/gradle"
          rm_cmd: "rm"  # Use 'rmz' for faster deletion (default: 'rm')
          rmz_version: "3.1.1"  # Required when rm_cmd is 'rmz'
          testing: false

- name: Free Disk Space for Docker
  uses: endersonmenezes/free-disk-space@v3
  with:
    remove_android: true
    remove_dotnet: true
    remove_haskell: true
    rm_cmd: "rmz"  # Faster cleanup
    
- name: Build Docker Image
  run: docker build -t myapp:latest .

- name: Free Disk Space for Node
  uses: endersonmenezes/free-disk-space@v3
  with:
    remove_android: true
    remove_haskell: true
    remove_packages: "google-cloud-cli azure-cli"
    
- name: Install Dependencies
  run: npm ci

- name: Free Disk Space for Python
  uses: endersonmenezes/free-disk-space@v3
  with:
    remove_android: true
    remove_dotnet: true
    remove_folders: "/usr/share/swift /usr/local/julia"
    
- name: Install Python Packages
  run: pip install pandas numpy scikit-learn

For faster file deletion, you can use rmz instead of the default rm command:

- name: Free Disk Space (with rmz)
  uses: endersonmenezes/free-disk-space@v3
  with:
    remove_android: true
    remove_dotnet: true
    rm_cmd: "rmz"  # Faster deletion (~3x faster)
    rmz_version: "3.1.1"

Note: rmz is a Rust-based alternative to rm, providing significantly faster deletion for large directories. Learn more at SUPERCILEX/fuc.

Updated at: 30/10/2025 - Based on Run #197

Times shown as: ubuntu-latest / ubuntu-arm64

Ubuntu Latest (x86_64):

remove_packages: "azure-cli google-cloud-cli microsoft-edge-stable google-chrome-stable firefox postgresql* temurin-* *llvm* mysql* dotnet-sdk-*"

Top packages by size:

• microsoft-edge-stable - 617 MB
• azure-cli - 583 MB
• google-cloud-cli - 523 MB
• google-chrome-stable - 386 MB
• temurin-21-jdk - 352 MB
• firefox - 274 MB
• llvm-18-dev - 329 MB

Ubuntu ARM64:

remove_packages: "azure-cli dotnet-sdk-8.0 temurin-* *llvm* mysql* firefox"

Top packages by size:

• azure-cli - 583 MB
• temurin-21-jdk - 352 MB
• dotnet-sdk-8.0 - 324 MB
• llvm-18-dev - 311 MB
• firefox - 253 MB

Ubuntu Latest (x86_64):

remove_folders: "/usr/share/swift /usr/share/miniconda /usr/share/az* /usr/local/lib/node_modules /usr/local/share/chromium /usr/local/share/powershell /usr/local/julia /usr/local/aws-cli /usr/local/aws-sam-cli /usr/share/gradle"

Ubuntu ARM64:

remove_folders: "/usr/share/swift /usr/local/share/powershell /usr/local/lib/node_modules /usr/share/az* /usr/local/aws-cli"

• ⚡ rmz is significantly faster for large operations (up to 78% faster on Haskell removal)
• 🔧 ARM runners have fewer pre-installed packages (49 GB initial vs 23 GB on x86_64)
• 📊 Full cleanup on x86_64 can free up to 38 GB with Large removal
• 🎯 For maximum speed: Use rmz with remove_packages_one_command: true

The time can vary according to multiple factors. These measurements are based on Run #197

In our action you can see more folders and packages to delete, but it is your responsibility to know what you are doing.

Initially I created this project with the intention of doing all this and then being able to use Docker and Python, our tests will prove this.

Q: Should I use rm or rmz?

• Use rm (default) for compatibility and safety
• Use rmz when you need maximum performance

Q: How much time does this save in my CI/CD?

• Typical savings: 2-5 minutes per workflow run
• With rmz: Up to 3x faster deletion operations

Q: Is it safe to remove all these packages?

• The defaults are safe for most workflows
• Test with your specific needs first
• Use testing: true to see what would be removed

Q: How can I debug issues?

• Enable disk space logging before and after (see examples above)
• Use testing: true to see what would be removed without actually removing
• Check the AGENTS.md for troubleshooting details

We welcome contributions! Whether you're fixing bugs, adding features, or improving documentation, your help is appreciated.

Quick Start:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Open a Pull Request

For detailed instructions, see AGENTS.md which includes:

• Development setup (DevContainer & manual)
• Testing guidelines
• Code style standards
• Pre-commit hooks usage
• Architecture details

This project, despite being on my personal profile purely formally, is part of an NGO we have in Brazil, responsible for helping young people and adults learn to program and tackle real-world projects. Learn more at codaqui.dev.

New Features:

• ✨ Added rmz support for faster file deletion (up to 3x faster)
  • ✨ Added rm_cmd and rmz_version inputs
  • 🔧 Multi-architecture support for rmz (x86_64 and aarch64)
• 🛠️ DevContainer configuration for easy development
• ✅ Pre-commit hooks with shellcheck and actionlint
• 📝 Enhanced documentation with examples and troubleshooting

Improvements:

• 🔧 Better error handling and validation
• 🔧 Improved testing mode (echo commands instead of alias)
• 📦 Reusable workflow templates for testing

Bug Fixes:

• 🐛 Fixed bc validation to exit gracefully instead of failing
• 🐛 Improved permission handling in testing mode

Special Thanks:

• fbnrst for contributions, ideas, and testing!

Improvements:

• Streamlined BC verification
• Improved testing mode
• Better error messages

Features:

• Package removal support
• Folder removal support
• Enhanced disk space reporting
• Testing mode for local development

Initial Release:

• Android library removal
• .NET library removal
• Haskell library removal
• Tool cache removal
• Swap storage removal

This project is licensed under the terms specified in the LICENSE file.