Scratch Org
A Scratch Org is a temporary, source-driven Salesforce environment created on demand from a project's source code via the Salesforce CLI.
Definition
A Scratch Org is a temporary, source-driven Salesforce environment created on demand from a project's source code via the Salesforce CLI. It is the cornerstone of the Salesforce DX development model: spin up a fresh org, push the latest project source, run tests, then discard it. Scratch orgs live up to 30 days (configurable per definition file), are billed against a Dev Hub allocation rather than per-edition licenses, and start empty rather than copying production metadata or data.
Scratch orgs solve problems that traditional Developer sandboxes cannot. Each scratch org represents a clean state, so developers test their feature against a known starting point rather than against the accumulated drift of a shared sandbox. The org definition file (.json) declares which features, settings, and edition to include, so the org matches exactly what production needs. Continuous Integration pipelines spin up scratch orgs to run automated tests, validate metadata, and tear them down within minutes. Scratch orgs are the standard for source-driven Salesforce development; legacy projects on older workflows often have not adopted them yet.
How scratch orgs enable source-driven Salesforce development
Source-driven development versus org-driven development
Traditional Salesforce development is org-driven: changes happen in a sandbox, then propagate to other sandboxes and production through change sets. Source-driven development inverts the model: changes happen in source code (committed to Git), and the source code drives org state through deployments. Scratch orgs are the source-driven model''s ephemeral runtime: spin up from source, validate, discard. The shift to source-driven is a significant cultural change for Salesforce teams but produces better audit trails, code review hygiene, and rollback capability than sandbox-driven workflows.
The scratch org definition file
Every scratch org is created from a JSON definition file (config/project-scratch-def.json by convention). The file specifies the org edition (Developer, Enterprise), features (SalesEnabled, ServiceCloud, Communities), settings (default currency, multi-currency, password policies), and licenses. The definition determines exactly what the org looks like. Multiple definition files let you test against different configurations: one for Sales Cloud features, another for Service Cloud, a third for Communities.
Dev Hub: the org that creates scratch orgs
Scratch orgs are created from a Dev Hub, which is a designated Salesforce org (typically the production org or a dedicated developer edition) authorized to provision them. Each Dev Hub has a daily and active scratch org limit based on its edition (typically 3 active for Developer Edition, up to 100 for paid plans). Authenticate the Salesforce CLI to the Dev Hub once, then create scratch orgs as needed: sf org create scratch -f config/project-scratch-def.json. The Dev Hub tracks the active scratch orgs and their expiration dates.
Source push and pull cycles
After creating a scratch org, push the project source: sf project deploy start. This deploys every metadata file in the project to the org in one operation. Edit metadata in the org (declarative changes), then pull the changes back to source: sf project retrieve start. The push-pull cycle is the rhythm of source-driven development. Conflicts between local and org changes surface explicitly through tracking; SFDX maintains a per-org tracking ledger of what has been deployed and what has drifted.
Data seeding and the empty-org problem
Scratch orgs start empty. No Accounts, Contacts, or anything else. For testing, you need to seed data. SFDX supports data seeding through sf data import tree (loading a tree of related records from JSON) or through Apex anonymous scripts. Define seed data in the project as fixtures; the scratch org creation script runs the seed automatically. Without proper data seeding, scratch orgs are useless for testing anything beyond pure metadata work.
Lifecycle and 30-day expiration
Scratch orgs expire after a configurable number of days (default 7, max 30). After expiration, the org is deleted automatically and cannot be recovered. This is a feature, not a bug: it forces clean, source-driven workflows because work in the org must be committed to source control before the org disappears. Plan scratch org lifetimes around the work: a few days for individual feature branches, up to 30 days for long-running integration testing. Each org type has different expiration options.
Scratch orgs versus sandboxes
Scratch orgs are ephemeral, source-driven, start empty, and have short lives (1-30 days). Sandboxes are persistent, often metadata-driven, copy from production (or are blank for Developer), and live until manually deleted or refreshed. Use scratch orgs for individual development work, CI/CD pipelines, isolated feature testing, and experiments. Use sandboxes for shared integration testing, UAT with realistic data, and pre-production staging that needs to mirror production behavior over time. Most modern Salesforce teams use both: scratch orgs for development, sandboxes for staging.
How to create and use a Scratch Org
Using scratch orgs requires the Salesforce CLI, a project in SFDX project format, an authorized Dev Hub, and a scratch org definition file. The first-time setup takes a few hours; daily use is fast once the toolchain is in place. The shift from org-driven to source-driven development is the bigger lift than the technical setup itself.
- Install the Salesforce CLI and VS Code Extensions
Install the sf CLI from developer.salesforce.com. Install VS Code with the Salesforce Extensions Pack. Run sf to confirm the install. The CLI authenticates against Dev Hubs and individual orgs through its login commands.
- Enable Dev Hub on the source org
Setup > Dev Hub > Enable Dev Hub. This authorizes the org to provision scratch orgs. Production is the standard Dev Hub for established teams; a dedicated free Developer Edition org works for solo developers.
- Authenticate the CLI to the Dev Hub
sf org login web --set-default-dev-hub. A browser opens for OAuth login. After successful authentication, the CLI remembers the Dev Hub for future scratch org creation.
- Create or open an SFDX project
sf project generate creates a new SFDX project structure. Open an existing one with sfdx-project.json at the root. The project must be in SFDX format (not the older metadata format) for scratch org workflows.
- Configure the scratch org definition file
Edit config/project-scratch-def.json. Specify edition, features, and settings. The CLI generates a sensible default; customize as needed for the project. Save the file in source control so the whole team uses the same scratch org shape.
- Create the scratch org
sf org create scratch --definition-file config/project-scratch-def.json --alias my-scratch --duration-days 7. The org provisions in 30-90 seconds. The CLI returns the login URL and credentials.
- Push source and seed data
sf project deploy start deploys the project source to the scratch org. sf data import tree --plan data/sample-plan.json seeds realistic test data. Both should run as part of an org-setup script for repeatable provisioning.
- Develop, test, and tear down
Edit metadata in the org or in source. Run tests with sf apex run test. Commit changes to source control before the org expires. Tear down with sf org delete scratch --target-org my-scratch when finished.
JSON config specifying edition, features, settings. Drives what the scratch org looks like.
How long the org lives before automatic deletion. Plan based on the work; default is 7.
Each Dev Hub has a limit on active and daily scratch orgs. Plan the allocation across the team.
- Scratch orgs are deleted at expiration, irreversibly. Commit all work to source control before the org disappears; the CLI does not warn about uncommitted changes.
- Scratch orgs start empty. Test code that assumes existing Accounts, Contacts, or other records will fail without data seeding. Build the seed step into the org creation script.
- Dev Hub allocations cap concurrent scratch orgs. Hitting the cap blocks new org creation; coordinate across the team or upgrade the Dev Hub tier for higher limits.
- Some features are not available in scratch orgs because they require licensed configuration. Confirm the definition file enables every feature the test code expects.
- Source tracking conflicts can arise when both source and the org change between push and pull. The CLI surfaces conflicts; resolve them through git diff and explicit pull/push decisions.
Trust & references
Cross-checked against the following references.
- Scratch Org OverviewSalesforce Developer
- Dev HubSalesforce Developer
- Salesforce CLISalesforce Developer
Straight from the source - Salesforce's reference material on Scratch Org.
- Create a Scratch OrgSalesforce Developer
- Scratch Org Definition FileSalesforce Developer
- CI/CD with Salesforce DXSalesforce Developer
Hands-on resources to go deeper on Scratch Org.
About the Author
Dipojjal Chakrabarti is a B2C Solution Architect with 29 Salesforce certifications and over 13 years in the Salesforce ecosystem. He runs salesforcedictionary.com to help admins, developers, architects, and cert/interview candidates sharpen their fundamentals. More about Dipojjal.
Test your knowledge
Q1. What is a Governor Limit in the context of Scratch Org?
Q2. What skill set is typically needed to work with Scratch Org?
Q3. Where would a developer typically work with Scratch Org?
Discussion
Loading discussion…