It is not necessary to override the SDK in the `stdenv` nor is it necessary to override the SDK used by your dependencies.
If your derivation needs a non-default SDK at build time (e.g., for a `depsBuildBuild` compiler), see the cross-compilation documentation for which input you should use.

When determining whether to use a non-default SDK, consider the following:

- Try building your derivation with the default SDK. If it works, you’re done.
- If the package specifies a specific version, use that. See below for how to map Xcode version to SDK version.
- If the package’s documentation indicates it supports optional features on newer SDKs, consider using the SDK that enables those features.
  If you’re not sure, use the default SDK.

Note: It is possible to have multiple, different SDK versions in your inputs.
When that happens, the one with the highest version is always used.

```nix
stdenv.mkDerivation {
  name = "libfoo-1.2.3";
  # ...
  buildInputs = [ apple-sdk_14 ];
}
```

#### What is a “deployment target” (or minimum version)? {#sec-darwin-troubleshooting-using-deployment-targets}

The “deployment target” refers to the minimum version of macOS that is expected to run an application.
In most cases, the default is fine, and you don’t have to do anything else.
If you’re not sure, don’t do anything, and that will probably be fine.

Some packages require setting a non-default deployment target (or minimum version) to gain access to certain APIs.
You do that using the `darwinMinVersionHook`, which takes the deployment target version as a parameter.
There are primarily two ways to determine the deployment target.

- The upstream documentation will specify a deployment target or minimum version. Use that.
- The build will fail because an API requires a certain version. Use that.
- In all other cases, you probably don’t need to specify a minimum version. The default is usually good enough.

```nix
stdenv.mkDerivation {
  name = "libfoo-1.2.3"; # Upstream specifies the minimum supported version as 12.5.
  buildInputs = [ (darwinMinVersionHook "12.5") ];
}
```

Note: It is possible to have multiple, different instances of `darwinMinVersionHook` in your inputs.
When that happens, the one with the  highest version is always used.

#### Picking an SDK version {#sec-darwin-troubleshooting-picking-sdk-version}

The following is a list of Xcode versions, the SDK version in Nixpkgs, and the attribute to use to add it.
Check your package’s documentation (platform support or installation instructions) to find which Xcode or SDK version to use.
Generally, only the last SDK release for a major version is packaged.

| Xcode version      | SDK version        | Nixpkgs attribute            |
|--------------------|--------------------|------------------------------|
| 12.0–12.5.1        | 11.3               | `apple-sdk_11` / `apple-sdk` |
| 13.0–13.4.1        | 12.3               | `apple-sdk_12`               |
| 14.0–14.3.1        | 13.3               | `apple-sdk_13`               |
| 15.0–15.4          | 14.4               | `apple-sdk_14`               |
| 16.0               | 15.0               | `apple-sdk_15`               |


#### Darwin Default SDK versions {#sec-darwin-troubleshooting-darwin-defaults}

The current default version of the SDK and deployment target (minimum supported version) are indicated by the Darwin-specific platform attributes `darwinSdkVersion` and `darwinMinVersion`.
Because of the ways that minimum version and SDK can be changed that are not visible to Nix, they should be treated as lower bounds.
If you need to parameterize over a specific version, create a function that takes the version as a parameter instead of relying on these attributes.

On macOS, the `darwinMinVersion` and `darwinSdkVersion` are always the same, and are currently set to 11.3.


#### `xcrun` cannot find a binary {#sec-darwin-troubleshooting-xcrun}

`xcrun` searches `PATH` and the SDK’s toolchain for binaries to run.
If it cannot find a required binary, it will fail. When that happens, add the package for that binary to your derivation’s `nativeBuildInputs` (or `nativeCheckInputs` if the failure is happening when running tests).