Feature Flag
Also known as: feature toggle, feature flagging
A switch in code that turns a feature on or off at runtime without a redeploy — used to roll out gradually, test in production, and decouple deploying code from releasing it to users.
- Primary domain
- Software Development Process
- Sub-category
- Software Design, Construction & Deployment
In simple terms
A feature flag (or feature toggle) is an if statement wired to a switch you can flip without changing code. Instead of “deploy the new checkout flow and everyone gets it instantly,” you deploy it behind a flag that’s off, then turn it on — for yourself, for 1% of users, for everyone — whenever you choose. The big idea: deploying code and releasing a feature become two separate actions. Code ships to production dark, gets switched on gradually, and can be switched off instantly if something goes wrong.
The Visual Map
graph LR
Deploy["deploy code\n(flag OFF — shipped 'dark')"] --> Internal["enable for staff\n+ allowlist"]
Internal --> Canary["1% of users"]
Canary --> Ramp["10% → 50%"]
Ramp --> Full["100%"]
Full --> Cleanup["remove the flag\n(delete the dead branch)"]
Ramp -->|"metrics bad?"| Kill["KILL SWITCH\nflip to 0% instantly\n(no rollback deploy)"]
Canary -->|"metrics bad?"| Kill
note["Deploy is decoupled from release:\nthe code is already in prod; the flag controls who sees it."]
More detail
At its simplest a flag is a boolean checked at runtime:
if (flags.isEnabled("new-checkout", user)) {
renderNewCheckout();
} else {
renderOldCheckout();
}
The power comes from where the value comes from — a configuration service that can target by user, percentage, region, or plan, changeable in real time. That enables several patterns: gradual rollout (1% → 10% → 100%, watching metrics — closely related to canary releases), kill switch (instantly disable a misbehaving feature with no rollback deploy), trunk-based development (merge unfinished work behind an off flag, avoiding long-lived branches), A/B testing (variants to different cohorts), and entitlements (gate premium features by tier).
Flags come in flavours with very different lifespans: short-lived release flags (delete after rollout) versus long-lived ops and permission flags. The main hazard is flag debt — old flags that linger create a combinatorial explosion of untested code paths, a concrete form of technical debt — so disciplined teams track and remove them.
Under the Hood
The trick to percentage rollouts is consistent bucketing: hash the flag name plus the user id into a stable 0–99 bucket, and enable the flag when the bucket is below the rollout percentage. The same user always lands in the same bucket, so they never flicker between old and new as you ramp up:
#!/usr/bin/env python3
"""Percentage rollout via consistent hashing — the core of every flag system."""
import hashlib
def is_enabled(flag, user_id, percent):
h = hashlib.sha1(f"{flag}:{user_id}".encode()).hexdigest()
bucket = int(h, 16) % 100 # stable 0..99 for this (flag, user)
return bucket < percent # in the rollout iff below the threshold
flag = "new-checkout"
users = [f"user{i}" for i in range(1000)]
for pct in [0, 10, 50, 100]:
enabled = sum(is_enabled(flag, u, pct) for u in users)
print(f" rollout {pct:3d}% -> {enabled}/1000 users enabled")
# A user's decision is STABLE as the rollout grows — no flickering:
u = "user42"
print("\nuser42 as rollout grows 10->50%:", [is_enabled(flag, u, p) for p in [10, 20, 30, 40, 50]])
About 10% of users are enabled at 10%, ~50% at 50%, all at 100% — and user42 stays enabled once their bucket is crossed, because bucket < percent only ever flips on as percent rises. That monotonic, deterministic property is exactly what makes “ramp from 1% to 100%” a smooth, observable dial rather than a random reshuffle each step.
Engineering Trade-offs
Decoupling deploy from release vs. added complexity Flags let you ship code continuously and release on a separate schedule — derisking launches, enabling instant kill switches, and supporting trunk-based development. The cost is a permanent layer of indirection: behaviour now depends on runtime config, so “what does production actually do?” requires knowing the flag state, and reproducing a bug means reproducing the exact flag configuration.
Safety of gradual rollout vs. flag debt
Ramping behind a flag with a kill switch is far safer than a big-bang release. But every flag is a branch in the code, and 2^N flags is 2^N possible combinations — most never tested together. Release flags that aren’t deleted after rollout become untested dead code paths and a maintenance tax. The practice only stays net-positive with disciplined cleanup.
Targeting power vs. testing surface Rich targeting (by user, region, plan, percentage) is what makes flags more than a config boolean — it enables canaries, A/B tests, and entitlements. But each targeting dimension multiplies the states your system can be in, and bugs that only appear for “users in region X at 30% rollout on plan Y” are genuinely hard to find and reproduce.
Build vs. buy
A boolean read from config is trivial to build in-house. Real-time updates, audit logs, percentage targeting, and consistent bucketing across services are not — which is why platforms like LaunchDarkly exist. Small teams often start in-house and migrate once flag management (not the if) becomes the bottleneck.
Real-world examples
- A team dark-launches a rewritten search backend behind a flag, ramps 1% → 100% over a week while watching latency and error rates, and flips it to 0% the instant a problem appears — no rollback deploy needed.
- LaunchDarkly, Unleash, and Flagsmith are dedicated feature-flag platforms; many companies also build a simple in-house version first.
- A premium feature shown only to paid users via a permission flag tied to their subscription tier — a long-lived flag, not a release toggle.
- Trunk-based development at scale (Google, Facebook) relies on flags so half-finished features can live on
mainswitched off, avoiding long-lived merge-hell branches.
Common misconceptions
- “Feature flags are just config booleans.” The targeting, real-time updates, consistent bucketing, and lifecycle management are what make them a practice rather than a one-off
if. - “Flags are free.” Each adds a code branch; left uncleaned, they accumulate into untested combinations and real maintenance cost — flag debt is a recognised failure mode.
- “A kill switch is the same as a rollback.” A kill switch flips config in seconds with the code already deployed; a rollback re-deploys an old build (minutes, and it reverts everything in that build, not just the one feature).
Try it yourself
See targeting and the kill switch in action: an allowlisted beta user gets the new experience even at 0% rollout, ordinary users flip on as the percentage rises, and 0% disables it for everyone instantly:
python3 - << 'EOF'
import hashlib
def bucket(flag, user):
return int(hashlib.sha1(f"{flag}:{user}".encode()).hexdigest(), 16) % 100
def serve(flag, user, percent, allowlist=()):
if user in allowlist: # explicit targeting beats percentage
return "NEW (allowlisted)"
return "NEW" if bucket(flag, user) < percent else "old"
flag = "search-v2"
for u in ["alice", "bob", "carol", "dave"]:
print(f" {u:6} @10%={serve(flag,u,10):3} @50%={serve(flag,u,50):3} "
f"beta(allowlist alice)={serve(flag, u, 0, {'alice'})}")
print(" KILL SWITCH @0%:", [serve(flag, u, 0) for u in ['alice','bob','carol','dave']])
EOF
alice sees NEW via the allowlist even at 0%; carol flips from old to NEW as the rollout reaches 50% (her bucket is in that band); and the kill switch at 0% serves old to everyone — instantly, with no deploy. Notice each user’s result at a given percentage is deterministic and stable: that’s the consistent-bucketing property from the Under-the-Hood example doing its job.
Learn next
- CI/CD — flags complete the pipeline by decoupling deploy from release, so continuous deployment can ship code dark and release it safely later.
- Deployment — gradual strategies like canary releases that flags implement at the application layer.
- Technical debt — uncleaned flags are a concrete, compounding form of debt; understanding it explains why flag lifecycle discipline matters.
Read this in a learning path
All paths →This topic is part of a learning path. Start in context to keep prev/next and progress tracking.
Relationships
- Requires
- Related
Neighborhood
A visual companion to the relationships above. Click any node to visit that topic.