---
schema_version: "1"
id: bdef8550a76a5cb590057975839356189d4809c539a2f1358a7b85b529a771dc
title: Scratch Org Definition Files vs Org Shape in Package Development
collection: developer
version: current
locale: en-us
portal_url: https://docs.salesforce.com/developer/current/en-us/platform-pkg-exchange/managed_packaging/guides/second-generation/dev2gp-so-orgshape-vs-def-file.md
canonical_url: https://developer.salesforce.com/docs/platform/pkg2-dev/guide/dev2gp-so-orgshape-vs-def-file.html
source_site: developer.salesforce.com
content_type: documentation
content_hash: 18c5f23692c9ad77941bb724511ef46c0aac0b29f03fd0d815c52ae543ef2e05
products:
  - Second-Generation Managed Packaging Developer Guide
  - merged-docs
---

# Scratch Org Definition Files vs Org Shape in Package Development

The scratch org definition file is used when you create scratch orgs, and also when you create new package versions. The scratch org definition file is a blueprint for your scratch org and defines the shape of the org you want for your package development work.

## Build Your Own Scratch Definition File

If you read [How Scratch Orgs Fit in the Package Development Workflow](https://developer.salesforce.com/docs/platform/pkg2-dev/guide/dev2gp-so-how-fit-pkg-dev.md) you might recall that the CLI command for creating scratch orgs includes a flag called `--definition-file`.

```nolang
sf org create scratch --target-dev-hub MyHub --definition-file config/project-scratch-def.json
```

In this example, `project-scratch-def.json` is the scratch org definition file. To learn more about what can be specified in this definition file, see [Build Your Own Scratch Org Definition File](https://developer.salesforce.com/docs/atlas.en-us.sfdx_dev.meta/sfdx_dev/sfdx_dev_scratch_orgs_def_file.htm) in the _Salesforce DX Developer Guide_.

Similarly the CLI `--definition-file` flag can be used when creating a new package version.

```nolang
sf package version create --package "Expenser App"
--definition-file config/project-scratch-def.json --code-coverage

```

When used in the `package version create` command, the scratch org definition file is used to specify the features, settings, or limits that your package requires.

## When to Use Org Shape

If you're developing managed packages to distribute on AgentExchange, we expect that you know what features and settings your packages depends on, and expect you to specify these requirements in a scratch org definition file. But there are scenarios like unlocked packages, or if you're moving from 1GP to 2GP package development, where using [Org Shape for Scratch Orgs](https://developer.salesforce.com/docs/atlas.en-us.sfdx_dev.meta/sfdx_dev/sfdx_dev_shape_intro.htm) can be useful.

During org shape creation, we capture the features, settings, edition, licenses, and limits of the specified source org. By using org shape you don’t have to manually list these items in the scratch org definition file.

**note:** The source org you use for org shape can’t be a sandbox or scratch org.

Later when you create a package version, specify the org ID for the source org in the scratch org definition file.

```nolang
{
  "orgName": "Acme",
  "sourceOrg": "00DB1230400Ifx5"
}

```

For more detailed instructions on enabling and creating org shape, review [Create a Scratch Org Based on an Org Shape](https://developer.salesforce.com/docs/atlas.en-us.sfdx_dev.meta/sfdx_dev/sfdx_dev_shape_intro.htm) in the _Salesforce DX Developer Guide._

If you’re moving from managed 1GP package development to 2GP package development, creating an org shape of your 1GP packaging org could be useful as you begin 2GP package development. Creating an org shape of your 1GP packaging org ensures that the features required for your package metadata are specified.

**See Also**

- [How Scratch Orgs Fit in the Package Development Workflow](https://developer.salesforce.com/docs/platform/pkg2-dev/guide/dev2gp-so-how-fit-pkg-dev.md)
- [_Salesforce DX Developer Guide_: Build Your Own Scratch Org Definition File](https://developer.salesforce.com/docs/atlas.en-us.sfdx_dev.meta/sfdx_dev/sfdx_dev_scratch_orgs_def_file.htm)
- [_Salesforce DX Developer Guide_: Create a Scratch Org Based on an Org Shape](https://developer.salesforce.com/docs/atlas.en-us.sfdx_dev.meta/sfdx_dev/sfdx_dev_shape_intro.htm)
- [_Salesforce DX Developer Guide_: Create a Scratch Org Based on an Org Shape](https://developer.salesforce.com/docs/atlas.en-us.sfdx_dev.meta/sfdx_dev/sfdx_dev_shape_intro.htm)