---
title: "subtract"
subtitle: "Function in std::solid"
excerpt: "Subtract removes tool solids from base solids, leaving the remaining material."
layout: manual
---

Subtract removes tool solids from base solids, leaving the remaining material.

```kcl
subtract(
  @solids: [Solid],
  tools: [Solid],
  tolerance?: number,
): [Solid]
```

Performs a boolean subtraction operation, removing the volume of one or more tool solids from one or more base solids. The result is a new solid representing the material that remains after all tool solids have been cut away. This function is essential for machining simulations, cavity creation, and complex multi-body part modeling.

### Arguments

| Name | Type | Description | Required |
|----------|------|-------------|----------|
| `solids` | [`[Solid]`](/docs/kcl-std/types/std-types-Solid) | The solids to use as the base to subtract from. | Yes |
| `tools` | [`[Solid]`](/docs/kcl-std/types/std-types-Solid) | The solids to subtract. | Yes |
| `tolerance` | [`number`](/docs/kcl-std/types/std-types-number) | The tolerance to use for the subtraction operation. | No |

### Returns

[`[Solid]`](/docs/kcl-std/types/std-types-Solid)


### Examples

```kcl
// Subtract a cylinder from a cube using the stdlib functions.


fn cube(center, size) {
  return startSketchOn(XY)
    |> startProfile(at = [center[0] - size, center[1] - size])
    |> line(endAbsolute = [center[0] + size, center[1] - size])
    |> line(endAbsolute = [center[0] + size, center[1] + size])
    |> line(endAbsolute = [center[0] - size, center[1] + size])
    |> close()
    |> extrude(length = 10)
}

part001 = cube(center = [0, 0], size = 10)
part002 = cube(center = [7, 3], size = 5)
  |> translate(z = 1)

subtractedPart = subtract([part001], tools = [part002])
```

![Rendered example of subtract 0](data:image/png;base64,[encoded data, 81116 characters])

```kcl
// Subtract a cylinder from a cube using operators.
// NOTE: This will not work when using codemods through the UI.
// Codemods will generate the stdlib function call instead.


fn cube(center, size) {
  return startSketchOn(XY)
    |> startProfile(at = [center[0] - size, center[1] - size])
    |> line(endAbsolute = [center[0] + size, center[1] - size])
    |> line(endAbsolute = [center[0] + size, center[1] + size])
    |> line(endAbsolute = [center[0] - size, center[1] + size])
    |> close()
    |> extrude(length = 10)
}

part001 = cube(center = [0, 0], size = 10)
part002 = cube(center = [7, 3], size = 5)
  |> translate(z = 1)

// This is the equivalent of: subtract([part001], tools=[part002])
subtractedPart = part001 - part002
```

![Rendered example of subtract 1](data:image/png;base64,[encoded data, 81116 characters])


