Migrate from LaunchDarkly to Unleash: what the work involves
If your LaunchDarkly renewal, licensing change or data residency concern is pushing you toward self-hosted Unleash, expect a scoped, mostly data-driven migration whose main risk is targeting and bucketing drift, not the code changes. Flags, segments and environments can be exported and recreated, but each targeting rule has to behave the same way after it is mapped to an activation strategy, and users in partial rollouts must keep their existing variation. Plan the work around those two points before you estimate anything else. The work usually falls to three groups. The platform team deploys the Unleash server against PostgreSQL 15 or later, sets up the admin UI on port 4242, and decides how Unleash Edge replaces the LaunchDarkly Relay Proxy. The SDK or application teams swap the client libraries or wrap them behind OpenFeature. The security team reviews access tokens, SSO needs and who holds admin rights, since Unleash Open Source is limited to 1 project and 2 environments with basic roles and SSO and custom roles sit in Enterprise. Ask your Unleash contact which of these features your plan includes before you size the work.
Effort depends on how many flags, segments and environments you run, how many SDKs and services read them, and how much your rules depend on LaunchDarkly-specific behavior such as prerequisites and multivariate flags. The Unleash migration guide describes the mapping, and the Unleash import and export documentation notes that segments and custom strategies are exported only as references, so they must exist in the target first. Recurring costs come from hosting, database operations, upgrades and the Unleash plan you choose, while one-time costs are the mapping, parallel running and cutover. Ask any implementation partner for a written scope that lists each of those items separately, and confirm the Unleash Edge end-of-life date of December 31, 2026 for your design before you commit to it.
Which LaunchDarkly capabilities map to Unleash, and which need rework
This table maps each main LaunchDarkly capability to its nearest Unleash equivalent and marks it as clean, needs rework or gap. Use it to scope the migration before exporting anything, because rework rows usually decide the timeline. The main takeaway is that the Open Source edition's 1 project and 2 environment limit is the first constraint to check against your current LaunchDarkly structure.
| Capability | Unleash equivalent | Status and what to confirm |
|---|---|---|
| Targeting rules | Activation strategies with constraints | Needs rework. Rules must be rewritten as strategies and constraints, and each rule's evaluation logic should be tested in both systems. |
| Multivariate flags | Strategy variants | Needs rework. Confirm variant weights and default values match the LaunchDarkly variations before cutover. |
| Segments | Segments referenced by strategies | Clean for static lists, needs rework for rule-based segments. Recreate segments first, because import expects them to exist in the target. |
| Prerequisites | Flag dependencies | Needs rework. Check that dependency chains evaluate the same way, especially where a parent flag is off. |
| Relay Proxy | Unleash Edge | Gap for OSS scale designs. The open-source Edge reaches end of life on December 31, 2026, so confirm an Enterprise plan or another caching approach. |
| Projects and environments | Projects and environments | Gap on Open Source. Unleash Open Source allows 1 project and 2 environments, while Enterprise adds unlimited projects and environments. |
| Governance and access | Roles, SSO, SCIM, user groups, change requests | Gap on Open Source. Enterprise adds SSO, SCIM provisioning, custom roles and change requests. Confirm which of these your audit needs. |
How to sequence the migration from inventory to decommission
The sequence moves LaunchDarkly definitions into Unleash in a controlled order, so each stage proves that targeting and bucketing behave the same before production traffic depends on the new server. Each step closes with a named artifact the team can review.
Inventory projects, environments, flags and segments
The platform or feature owner lists every LaunchDarkly project, environment, flag and segment, and marks which flags are live in production, which are archived and which are referenced by application code. Note prerequisites, multivariate flags and any Relay Proxy deployments, because each maps to a different Unleash concept. Done means an inventory sheet that a second engineer has reviewed and that lists the flags to migrate, the flags to retire and the services that call each one.
Export definitions as JSON through the REST API
Using a LaunchDarkly access token with read scope, the team exports flag, segment, environment and project definitions as JSON through the LaunchDarkly REST API and stores the files in version control with access restricted to the migration group. Confirm the token's scope and expiry with your LaunchDarkly administrator before the export, and remove the token once the export is verified. Done means a complete set of exported files, checked against the inventory sheet for counts and names.
Map targeting rules to activation strategies
Build a mapping sheet that translates each LaunchDarkly targeting rule into an Unleash activation strategy, multivariate variations into strategy variants, segments into Unleash segments and prerequisites into flag dependencies, following the mapping published in Unleash's migration guide. Mark every rule that has no direct equivalent and decide, per flag, whether to rewrite it or keep the logic in application code. Done means a mapping sheet where every exported rule has a target or an explicit exception approved by the owner.
Recreate context fields and segments first
Before any flag is imported, the team defines the custom context fields that the rules depend on in the target Unleash instance and creates the segments that flags reference. Unleash's environment import and export only references segments and custom strategies, so they must already exist in the target or the import will fail to resolve them. Done means the target instance lists every segment and context field the mapping sheet requires, and a spot check confirms that each segment matches the source membership logic.
Pilot on low-risk flags in a non-production environment
The team imports a small set of low-risk flags into a non-production environment, using the Admin API or the import feature, and wires one internal service to the Unleash SDK behind an OpenFeature provider or a thin wrapper. Evaluate each pilot flag against a fixed set of test contexts in both systems and record any difference in result. Done means a pilot report that lists every flag, the contexts tested and zero unexplained differences, or a documented fix for each one.
Run both systems in parallel behind an abstraction layer
The application teams route flag evaluation through one abstraction layer that can call LaunchDarkly or Unleash, and they keep LaunchDarkly as the source of truth while shadow evaluations run against Unleash. Log both results for each evaluation and compare them daily, paying close attention to partial rollouts, where the hashing and stickiness settings must keep each user in the same bucket. Done means a parallel-run comparison showing matching results for every production flag over a window the owners agree in writing, with bucketing mismatches resolved before cutover.
Cut over flag by flag
The team moves each flag's authority from LaunchDarkly to Unleash in small batches, starting with flags that have the lowest blast radius, and confirms that the Unleash SDK and the Unleash Edge or proxy path serve the expected values. Keep a documented rollback that reverts a single flag to the LaunchDarkly value without a code change. Done means a cutover log with a timestamp, owner and verification check for every flag, and no open rollbacks.
Decommission LaunchDarkly and the Relay Proxy
After all flags serve from Unleash and the owners sign off, the team removes LaunchDarkly SDK calls and dependencies, retires the Relay Proxy, revokes the access tokens used for the migration and confirms with the LaunchDarkly contract owner which subscription, service connection and data export settings to end. Keep the exported JSON and the cutover log in an archive that your audit or compliance team can access. Done means a decommissioning checklist signed by the platform owner, with no active LaunchDarkly tokens and no remaining SDK references in the repositories.
What data moves through the export path and what must be rebuilt
A LaunchDarkly to Unleash move carries flag definitions across, but not everything a team relies on in production. The cards below separate what the export path copies from what you must recreate by hand, pre-create in the target, or accept as lost history before you schedule cutover.
Flag and segment definitions via REST API
Flag and segment definitions leave LaunchDarkly as JSON through its REST API, authenticated with an access token scoped to the projects you are moving. Export each project and environment separately so you can diff the output against Unleash later. Confirm that the token has read access to segments as well as flags, because a token that reads flags alone will produce an incomplete export that looks successful.
Segments and custom strategies must pre-exist
Unleash import and export moves flag configuration as JSON, but it exports segments and custom strategies only as references. Create every segment and custom strategy in the target Unleash instance before you run the import, or the imported flags will point at objects that do not exist. Build a simple inventory of segment names from the LaunchDarkly export so the rebuild is checked line by line.
Context fields and targeting rules
LaunchDarkly targeting rules map to Unleash activation strategies, and multivariate flags map to strategy variants. Context attributes used in rules, such as plan tier or region, must exist as context fields in Unleash before strategies reference them. Review each mapped rule with the flag owner, because clause operators and attribute names rarely translate one to one.
SDK replacement in each application
The LaunchDarkly SDK calls in each service must be replaced with an Unleash SDK or with an OpenFeature provider if you want a vendor-neutral layer. This is application code work that the definition export does not touch, and it is the step most likely to be underestimated in a fleet with many repositories. Inventory every service that calls the LaunchDarkly SDK before setting a cutover date.
Relay Proxy replaced by Unleash Edge
Where teams run the LaunchDarkly Relay Proxy inside their network, Unleash Edge takes the caching role between SDKs and the Unleash API. Note that the open-source version of Edge reaches end of life on December 31, 2026, so a design built on OSS Edge needs a dated plan for an Enterprise tier or another caching approach. Confirm the Edge version and its supported deployment before you rewire the proxy hostnames.
Evaluation history and events are not exported
The definition export carries the flag configuration, not the evaluation history, custom events or experiment results that LaunchDarkly recorded. Dashboards, audit trails and metric history for past releases stay in LaunchDarkly unless you export them through its Data Export add-on or archive them yourself. Decide with compliance and product owners which historical records must be retained before the LaunchDarkly contract ends.
How to avoid re-bucketing users in partial rollouts
A percentage rollout only stays stable through a cutover if Unleash assigns each user to the same side of the split that LaunchDarkly did. Bucketing is a hash of a stickiness key, so any difference in the key, the context fields that feed it, or the seed will move users between variations. Before you flip traffic, confirm which context field LaunchDarkly used for bucketing (commonly the user key, but some flags bucket on another attribute) and map it to the same field in the Unleash strategy parameters and the SDK context. A mismatch in field name or casing is the most common way the split changes without anyone noticing.
Segments need the same care. A user who sits inside a targeted segment in LaunchDarkly but falls outside the equivalent Unleash segment at cutover will see a different result even when the percentage is identical. Before the parallel run, export the segment membership rules from the LaunchDarkly REST API, recreate them in Unleash, and confirm the rollout percentages were copied exactly, including any rollout already in progress. Record each flag's percentage, stickiness field and segment list in a change record so that any later difference can be traced to one of those three inputs.
During the parallel run, evaluate a sample of users in both systems for each partial rollout and compare the variation returned. Include users near the edges of the rollout, since they are the first to show a shift. Treat any disagreement as a blocker until the cause is found. The exact bucketing behavior, including how the hash is computed and how the stickiness parameter is applied, should be confirmed in the Unleash documentation and in the release of the SDK your applications use, because it can differ by SDK version and by server release.
What usually goes wrong in a LaunchDarkly to Unleash move
Most failed flag migrations break at the seams: user bucketing, import order, dependencies, feature gaps and licensing. Each card below names one of these failure points and the check that prevents it before cutover.
Users re-bucketed during partial rollouts
A percentage rollout assigns each user to a variant by hashing a key, and a different hashing setup or context key in Unleash can move users to a different variant. Users who saw the new feature may suddenly lose it, which skews both experience and any experiment data. Before cutover, confirm which context field LaunchDarkly used for bucketing (for example, the key), recreate the same field in Unleash, and compare assignments for a sample of users while both systems run in parallel.
Segments imported after the flags
Unleash exports and imports segments and custom strategies only as references, so a flag that points to a segment will fail or behave unexpectedly if the segment does not already exist in the target instance. The fix is an ordering rule: recreate context fields and segments first, then import flags, and verify each reference resolves before enabling any flag. Keep the segment list from the LaunchDarkly REST API export as the checklist.
Prerequisites lost as missing dependencies
LaunchDarkly prerequisites gate one flag on another flag's variation. The migration guide maps these to Unleash flag dependencies, but a prerequisite that was not carried across leaves the dependent flag enabled without its gate. Review every flag with a prerequisite in the export, recreate each dependency explicitly, and test the dependent flag with its parent both on and off before any production traffic moves.
Enterprise features assumed in Open Source
Unleash Open Source is limited to one project and two environments with basic roles. Teams that depend on multiple projects, SSO, SCIM provisioning, custom roles, user groups or change requests will find those controls missing after cutover. Compare each LaunchDarkly governance feature in use against the OSS comparison page, and either accept the gap in writing or price an Enterprise plan before the migration plan is approved.
Unleash Edge OSS end of life
The open-source version of Unleash Edge, the caching layer that replaces LaunchDarkly's Relay Proxy in your design, reaches end of life on December 31, 2026. A deployment that places OSS Edge between SDKs and the server will need a supported replacement or an Enterprise plan before that date. Put Edge version and support status into the architecture review, and decide whether SDKs will call the Unleash server directly during the parallel run.
AGPLv3 misread for internal use
Starting with v8.0.0, the Unleash server source moved from Apache 2.0 to AGPLv3, while the official open-source Docker images stay under Apache 2.0. Unleash states that running the official images without modifying the source is not affected, but teams that patch the server and offer it to outside users have obligations to publish source or buy a license. Ask legal to confirm the position for internal use, and record whether any build of the server is modified before rollout.
How the migration differs by team size and starting point
A small team with a modest flag inventory on a single LaunchDarkly project usually has the simplest path. Unleash Open Source covers one project and two environments, so the export, recreation and cutover work fits inside the free edition if the team's needs stay within those limits. The main effort is reviewing each flag by hand, since few teams keep a clean record of why a rule exists.
- Fit check: Confirm that the number of environments in use is two or fewer and that the flag count stays within the Open Source limit on the Unleash pricing page.
- Hosting: Plan a single PostgreSQL instance and the Unleash server on your own infrastructure, using the getting started guide as the baseline.
- Rules review: Decide whether each LaunchDarkly targeting rule maps cleanly to an activation strategy or needs simplifying before recreation.
- Licensing: Check the AGPLv3 change in v8.0.0 against how you will run and modify the server, even for internal use.
- Ownership: Name one engineer who will run upgrades and backups after the migration, since no vendor team handles that for you.
Before starting, ask whether the team expects to add a second project or a third environment within the next year, because that decision changes the edition you need.
An organization with several teams, multiple projects and separate production and staging environments reaches the Open Source limits quickly. Unleash Enterprise adds unlimited projects and environments, single sign-on, SCIM provisioning, project and custom roles, user groups and change requests. The migration then becomes a governance design project as much as a data move, because each team's access and approval needs must be mapped before flags are imported.
- Edition decision: Price Enterprise on a custom annual contract with the Unleash sales team, and ask for a written quote that covers hosting model and support scope.
- Project structure: Decide how LaunchDarkly projects map to Unleash projects and whether shared segments belong in one place.
- Access model: Map existing LaunchDarkly roles to Unleash project and custom roles, and confirm SSO and SCIM requirements with your identity team.
- Import order: Create segments and custom context fields in the target before importing flag configurations, because exported segments are references only.
- Change control: Decide which teams need change requests before production flags move.
Ask the vendor to confirm in writing which Enterprise features are included in the hosting model you choose.
A team that already routes flag evaluation through its own wrapper or through the OpenFeature API has the easiest cutover. Application code calls one interface, so the work concentrates on a provider switch, a parallel run and verification of targeting results. Teams in this position mainly need to confirm that the wrapper passes the same context attributes that the Unleash rules depend on.
- Provider swap: Replace the LaunchDarkly provider or adapter with the Unleash one in a non-production environment first.
- Parallel run: Evaluate flags in both systems and log disagreements before any production traffic moves.
- Context parity: Confirm that user, device and organization attributes arrive with the same names and types in both systems.
- Bucketing: Check that partial rollouts keep existing users in their current variants during the switch.
- Cleanup: Remove the LaunchDarkly dependency only after the parallel run has been clean for an agreed period.
Review the wrapper's test coverage first, since weak tests make disagreement logs harder to trust.
A team that calls the LaunchDarkly SDK directly in many services has the largest code change. Every call site, initialization path and test double must change, and the team has to coordinate releases across services. The migration effort is driven more by the number of repositories and languages than by the number of flags, so the inventory of call sites is the first deliverable.
- Inventory: Search each repository for LaunchDarkly SDK imports and record language, service and owner for each call site.
- Introduce a seam: Consider wrapping existing calls behind a thin interface before changing the vendor, so each service can move independently.
- SDK coverage: Confirm that Unleash SDKs exist for every language in use, and where they do not, decide whether to use an OpenFeature provider instead.
- Edge deployment: Map the LaunchDarkly Relay Proxy to Unleash Edge, and check the Edge end-of-life date of December 31, 2026 for the open-source edition.
- Rollout schedule: Stage service-by-service cutovers so a single failure does not affect every product.
Ask each team to confirm which flags it still reads, because stale flags often account for much of the inventory.
Questions buyers ask before moving LaunchDarkly flags to Unleash
How much does it cost to move LaunchDarkly flags to self-hosted Unleash?
Unleash Open Source is free to self-host, so the license line is zero, but the total cost is the infrastructure, the PostgreSQL database, the people who run it and any paid tier you need. The Unleash pricing page lists Pay-As-You-Go at $75 per seat per month for self-hosted, with a 5-seat minimum, and Custom Enterprise on annual contracts. Those seat figures are the only published numbers to plan around, and the pricing page is the source to check. One-time costs are the migration work and SDK changes. Recurring costs are hosting, database operations, upgrades and any seats or support you buy. Ask any implementation partner for a fixed-scope quote that separates these components.
How long does a LaunchDarkly to Unleash migration take?
No duration is published for this migration, and the length depends on the number of projects, flags, segments, SDK integrations and applications that read flags. The Unleash migration guide sequences the work: export flag and segment definitions, recreate context fields and segments first, recreate flags, then run both systems in parallel before cutover. Parallel running is usually the longest phase because each application must be verified. Ask for a written timeline that lists the applications in scope and the parallel-run window before any work starts.
What does the migration need from our engineering team?
Plan for application engineers who own each SDK integration, a platform owner for the Unleash server and database, and a product or release owner who signs off on each flag's targeting behavior. Application engineers swap or wrap the SDK calls, platform engineers deploy the server against PostgreSQL 15 or later and manage the Edge layer, and release owners confirm that rollouts still match what users saw. Your team should also inventory every LaunchDarkly environment and project before starting.
Can our own team do the migration without an implementation partner?
Yes, a team with Kubernetes or container experience, access to the LaunchDarkly REST API and ownership of the affected applications can run the Unleash migration itself. The Unleash guide documents the export, mapping and import steps. A partner is most useful when you have many services, strict change control, or no one who can own the parallel-run period and rollback plan. Whichever path you choose, test each flag's behavior in a staging environment before production.
Does the Unleash Open Source limit of one project and two environments block a migration?
It can. Unleash Open Source allows 1 project and 2 environments, with basic roles, and the Unleash pricing page also lists 5,000 feature flags per instance. If your LaunchDarkly account uses several projects or more environments such as development, staging and several production regions, you will need Unleash Enterprise, which adds unlimited projects and environments, single sign-on, SCIM provisioning and custom roles. Map your current project and environment count against these limits before choosing a tier, and confirm current limits with Unleash.
Does the AGPLv3 license change affect internal use of Unleash?
For internal use of the official open-source Docker images without modifying the source, the Unleash blog states that the AGPLv3 change does not affect you. Starting with v8.0.0, the server source code moved from Apache 2.0 to AGPLv3, while the Docker images stay under Apache 2.0 and the SDKs keep their permissive licenses. If you modify Unleash and offer it as a public or commercial service, the blog says you must publish the source or buy a commercial license. Have your legal team read the Unleash blog post of June 2, 2026 against your actual deployment before you adopt any modified build.
How does the Unleash Edge end-of-life date change the design?
The open-source version of Unleash Edge reaches end of life on December 31, 2026, so a design that depends on Edge for scale should not rely on the OSS build past that date. Unleash recommends that OSS Edge users move to an Enterprise plan. Decide early whether your LaunchDarkly Relay Proxy replacement will use Edge under a paid plan, use another caching approach, or wait for a supported path, and include that decision in your architecture review and cost quote.
What drives cost on the Unleash side
The Unleash side of the bill has four components: the server and its database, the caching design that serves SDKs at scale, seats for the paid tiers, and the engineering time to migrate and run the platform. The server runs from the unleashorg/unleash-server image (or unleashorg/unleash-enterprise for Enterprise) on PostgreSQL 15 or later, with the server and admin UI on port 4242. Those infrastructure costs are yours to pay to your cloud provider or data center, and they recur. Ask your platform team to size the database for backups, high availability and patching windows before comparing against a SaaS invoice.
Caching is the component most likely to change the design. The open-source version of Unleash Edge reaches end of life on December 31, 2026, and Unleash recommends that OSS Edge users move to an Enterprise plan. If your LaunchDarkly estate depends on the Relay Proxy for scale, decide early whether Edge runs on an Enterprise plan, whether you replace it with another caching layer, or whether your SDKs call the server directly. That decision drives the seat count and the license you buy.
Seats are the recurring line you choose. The Unleash pricing page lists Pay-As-You-Go at $75 per seat per month with a 5-seat minimum for self-hosted, and Custom Enterprise on annual contracts. Open Source stays free but is limited to 1 project and 2 environments. Only buy seats if you need SSO, SCIM provisioning, project roles, user groups or change requests, and confirm each of these in your own environment before you rely on them. Ask any vendor for a written quote that states the seat count, hosting model and support terms.
How DeployOpen scopes, runs and supports the Unleash migration
DeployOpen plans and implements self-hosted Unleash inside your own infrastructure, including the export of LaunchDarkly flags and segments, the recreation of targeting as activation strategies, and the parallel run that precedes cutover. Engagements are fixed-scope, so the work, deliverables and timelines are agreed in writing before any migration starts.
How we scope
- We inventory LaunchDarkly projects, environments, flags, segments, prerequisites and Relay Proxy deployments that the written scope covers.
- We confirm the Unleash edition and hosting model, including whether Unleash Open Source's limit of 1 project and 2 environments fits your needs.
- We agree in writing which SDKs, applications and environments move, and which stay on LaunchDarkly during parallel running.
How we build
- We deploy the Unleash server against PostgreSQL in your environment, with the server and admin UI on port 4242 behind your own access controls.
- We script the LaunchDarkly REST API export as JSON, then recreate context fields and segments in Unleash before any flag import.
- We map targeting rules to activation strategies and multivariate flags to strategy variants, and test that user bucketing stays stable in partial rollouts.
How we hand over
- We document the export scripts, the mapping table, the Unleash configuration and the parallel-run checks so your team can repeat them.
- We record each flag's before and after evaluation results and list every difference found, with the decision taken on each one.
- We confirm the cutover plan, the rollback path and the owner of each flag and environment before the LaunchDarkly subscription is changed.
How we support
- Ongoing support, upgrades and continuous testing are available as a retainer, agreed separately from the migration scope.
- We plan Unleash upgrades around the AGPLv3 licensing change from v8.0.0 and the Unleash Edge open-source end-of-life date of December 31, 2026.
- Your compliance evidence, including change records and access reviews, can be prepared for your independent auditor, who issues any report or certification.
