Fish compatibility: the complete guide.

Fish compatibility is the single most misunderstood subject in the aquarium hobby, and the reason is simple: almost every source reduces it to a yes/no answer. "Can a betta live with shrimp?" gets a one-word reply, when the honest answer is it depends — on tank size, on planting, on the individual fish's temperament, on whether the shrimp are adults or babies. Compatibility is not a verdict. It is a set of conditions. Two species can be perfectly compatible in a 30-gallon planted tank and a disaster in a 5-gallon bare one. This guide is the complete framework for thinking about it properly — the four factors that actually decide whether two fish can share a tank, the special cases that break the rules, and how to design a setup that turns a borderline pairing into a stable one.

When you are ready to test specific combinations, the Fish Compatibility Checker scores any two species across all four of these factors and explains its reasoning. This page is the theory behind that score.

Compatibility Is Conditions, Not a Verdict

The instinct to ask "are these two fish compatible?" assumes the answer lives in the fish. It does not. It lives in the relationship between the fish and the environment you put them in. A school of tiger barbs is a notorious fin-nipper — but in a group of twelve, in a large tank, they nip each other and largely leave tankmates alone. The same six barbs in a 20-gallon tank with a single angelfish will shred its fins. Nothing about the species changed. The conditions did.

This is why the "community fish" label on a store tank is close to meaningless. It tells you a species is generally peaceful, which is a starting point, not a guarantee. Real compatibility assessment asks four questions, and a pairing has to pass all four:

1. Water parameters — can both species actually thrive in the same water chemistry?
2. Temperament — will their behavior create stress, aggression, or harassment?
3. Size and predation — can one fit the other in its mouth?
4. Competition and niche — do they fight over the same food, space, or territory?

A failure on any one of these can sink the pairing regardless of how well it does on the other three. Two fish with identical water requirements and gentle temperaments still fail if one is large enough to eat the other. The rest of this guide takes each factor in turn.

The core principle: compatibility is the overlap between two species' needs and the environment that hosts them. Change the tank and you change the answer. The goal is not to memorize which fish "go together" — it is to understand the four levers and design for them.

The First Factor: Water Parameters

Parameter compatibility is non-negotiable, and it is the factor hobbyists most often ignore because its failures are slow and invisible. Two fish whose natural water chemistry does not overlap cannot both thrive in the same tank. One of them will live at the wrong end of its tolerance range, in a state of chronic osmoregulatory stress that suppresses immune function and quietly shortens its life.

Why mismatched water is a slow killer

Fish are constantly managing the movement of water and salts across their gills and skin — osmoregulation. A species evolved for soft, acidic blackwater spends energy keeping salts in; a species from hard, alkaline water spends energy keeping salts balanced the other direction. Put a soft-water fish in hard water and it pays a metabolic tax every hour of every day. It will not die tomorrow. It will look "fine" for months. Then it succumbs to an opportunistic infection that a non-stressed fish would have shrugged off, and the keeper calls it a "mystery death."

This is the most common cause of unexplained losses in community tanks. The water tested fine — ammonia zero, nitrite zero, nitrate low — but "fine" for the tank is not "fine" for a fish at the edge of its range. The three parameters that matter most for compatibility are temperature, pH, and hardness.

Temperature

Temperature is the hardest constraint because it cannot be compromised — every fish in a tank shares one temperature. A discus wants 82–86°F; a white cloud mountain minnow wants 64–72°F. There is no overlap, so there is no shared temperature that keeps both healthy. One will always be wrong. This is why coldwater and tropical fish should never be mixed, no matter how peaceful both are.

When temperature ranges do overlap, aim for the shared band. If species A wants 74–80°F and species B wants 78–84°F, keep the tank at 78–80°F — the overlap — not at either extreme.

pH and the parameter-overlap trap

pH ranges are more forgiving than temperature because most fish tolerate a band, but mismatches still matter. The classic example is mixing neon tetras (pH 5.8–7.0, soft) with swordtails (pH 7.0–8.0, hard). They overlap only at the very edge — around pH 7.0 — which means at any pH that suits one, the other is stressed. They can coexist at a compromise of 7.0–7.2, but neither is at optimal chemistry, and for breeding or long-term health that compromise is a cost.

The lesson: overlap at the edges is not the same as a comfortable shared range. A pairing where both species are happy across a wide band of pH is far more robust than one that only works at a single knife-edge value.

Hardness (GH and KH)

General hardness (GH) and carbonate hardness (KH) track with pH and are often the real driver behind it. Soft-water fish — most tetras, rasboras, many catfish, wild bettas — come from mineral-poor water and can struggle to breed or thrive in hard water. Hard-water fish — livebearers, African cichlids, many shrimp — need the minerals. KH also buffers pH stability; low-KH tanks swing more, which stresses fish that need consistency. Use the GH/KH converter to translate between dGH, dKH, ppm, and mmol/L, and the water parameter reference to compare ideal ranges across species before you buy.

The Second Factor: Temperament

If water chemistry is the invisible factor, temperament is the visible one — and it is individual as much as it is species-wide. A "peaceful" pearl gourami can turn aggressive in a small tank or while defending a breeding territory. A "semi-aggressive" tiger barb can be a model citizen in a large school in a well-designed tank. Species generalizations are the average; the fish in front of you is a sample of one.

That said, several behavioral risk categories are reliable enough to design around.

Fin-nippers versus long-finned fish

Some species nip fins — tiger barbs, serpae tetras, Buenos Aires tetras, and most puffers. Pair any of them with a long-finned, slow-moving fish — a betta, a guppy, an angelfish, a fancy goldfish — and the long fins become a target regardless of how well water parameters overlap. The nippers are not "aggressive" in the predatory sense; they simply find trailing fins irresistible. The result is shredded fins, constant stress, and eventually infection. This pairing fails on temperament even when it passes on chemistry.

Territorial fish

Cichlids, many gouramis, and some catfish establish and defend territories. Compatibility here depends almost entirely on space and sightlines. Two territorial fish in a bare tank will fight to the edges of the glass; the same two in a large, heavily aquascaped tank with visual barriers may each claim a zone and coexist. Territory aggression also spikes during breeding — a normally tolerant cichlid pair will clear the tank of everything when guarding eggs.

Predatory and ambush feeders

Oscars, large cichlids, pike cichlids, and large catfish operate on a simple rule: if it fits in the mouth, it is food. This is not aggression — it is feeding — and it cannot be trained or designed away. A predatory fish will eat tankmates small enough to swallow, eventually, no matter how well-fed it is. The only solution is to keep tankmates that are too large to eat and too fast or armored to be worth chasing.

Individual variation and the betta problem

No species illustrates individual temperament better than the betta. Some male bettas tolerate shrimp, snails, and peaceful nano fish for years. Others hunt anything that moves and must be kept alone. There is no way to know which betta you have until you try — which means every betta community is an experiment that needs an escape plan (a backup tank) ready. The betta and shrimp and betta and corydoras pairings go deep on exactly this.

The Third Factor: Size and Predation

The bluntest compatibility rule in the hobby is also the most reliable: if one fish can fit another in its mouth, it eventually will. Size disparity is not about aggression — a perfectly peaceful fish will still inhale a tankmate small enough to swallow, because to a fish, small moving things are food. This is why the "they grew up together" reasoning fails so often: the small fish was safe only until the large fish's mouth outgrew it.

The practical implication is that you should plan for adult sizes, not the sizes in the store tank. A two-inch juvenile that will reach ten inches is not a tankmate for neon tetras, even if it ignores them today. Size mismatch also creates non-lethal problems: a much larger fish out-competes smaller ones for food, intimidates them away from open water, and raises the bioload disproportionately. A useful heuristic is that tankmates should be within roughly the same size class — and where they are not, the smaller species needs to be too large to swallow and have the cover to stay out of reach.

Predation has one important special case that the SpawnOS checker flags explicitly: the live food relationship. When you pair a microfauna species — daphnia, scuds, copepods — with a fish, the "compatibility" question is mislabeled. These are not tankmates; they are food. A low compatibility score there is not a failure, it is the correct answer: the fish will eat the daphnia, which is exactly what you want when you are feeding live. The Live Food Encyclopedia covers that relationship as the feeding tool it is.

The Fourth Factor: Competition and Niche

The subtlest factor is resource competition. Two species can pass on chemistry, temperament, and size and still make each other miserable if they occupy the same niche — the same water level, the same diet, the same shelter. A tank works best when its inhabitants spread across the available zones: bottom-dwellers (corydoras, loaches, many catfish), mid-water swimmers (most tetras, barbs, rasboras), and top-water fish (hatchetfish, many livebearers, gouramis). Stock all three levels and you reduce direct competition; stock three species that all want the bottom and you create constant friction.

Diet overlap matters too. Fast, aggressive eaters out-compete slow, deliberate ones at feeding time — a school of barbs will strip the surface before a shy, methodical fish like a discus or many catfish gets its share. The slow feeder slowly starves in a tank that "looks" well-fed. Mixing feeding styles requires either target-feeding the slow species or choosing tankmates with compatible feeding tempo.

Tank Design: The Lever That Changes the Answer

Here is the most important practical truth in this entire guide: many borderline-compatible combinations succeed in well-designed tanks and fail in poorly designed ones. Tank design is the lever you control, and it can turn a "caution" pairing into a stable community.

Size dilutes aggression. A bigger tank gives subordinate fish room to escape, lets territorial fish hold non-overlapping territories, and reduces the frequency of forced encounters. More water is the single most reliable fix for borderline aggression. Confirm you actually have the space with the stocking density calculator, which uses real bioload math instead of the misleading one-inch-per-gallon rule.

Planting and hardscape create sightlines and refuge. Dense planting breaks line of sight, which lowers territorial aggression — a fish that cannot see a rival does not defend against it. Caves, driftwood, and plant thickets give smaller or subordinate fish places to retreat. A shrimp colony survives alongside a betta far better in a jungle of moss and floating plants than in an open tank, because the babies have somewhere to hide during the vulnerable hours after molting.

Group sizes change behavior. Schooling species kept in too-small groups are stressed and often turn nippy; the same species in a proper school of ten or more spread their interactions among themselves and bother tankmates less. Understocking a schooling fish is a common, hidden cause of community aggression.

Zone the tank deliberately. Combine bottom, mid, and top species so the tank uses all its volume and competition stays low. The compatibility checker returns a recommended setup — minimum tank size, flow, planting density, and hiding level — for exactly this reason: the right setup is part of the answer, not an afterthought.

Special Cases That Break the Rules

Some pairings have enough specific, well-documented behavior that they deserve their own rules. These are the cases where general principles are not enough.

Bettas

Male bettas are territorial toward other bettas and toward fish they read as rivals — anything with flowing fins or bright color, like male guppies. Two males must never share a tank. With nano fish and invertebrates, individual temperament decides everything, so a betta community needs heavy planting and a backup plan. Bettas also want warm, still water, which rules out high-flow tankmates like hillstream loaches.

Shrimp and small invertebrates

Dwarf shrimp (cherry shrimp, caridina) are prey to most fish at some life stage, especially as freshly molted adults and as babies. Adult shrimp survive with many peaceful fish; the colony's reproduction often does not, because the fish eat the shrimplets faster than they recruit. If the goal is a breeding shrimp colony, the safest tankmates are none, or tiny non-predatory fish in a heavily planted tank.

Goldfish

Goldfish are a coldwater, high-waste, fast-growing, large fish, which makes them poor matches for most tropical community species on temperature, bioload, and eventual size all at once. They belong with other goldfish or coldwater tankmates, not in a tropical community.

Axolotls

Axolotls are best kept species-only. They are coldwater amphibians; fish nip their external gills, can stress them, may carry pathogens, and small fish get eaten. There is essentially no good fish tankmate for an axolotl.

Freshwater versus marine or brackish

This is an absolute. Freshwater and marine/brackish animals have fundamentally different salinity requirements and cannot share water, even if a few other parameters look close. The checker treats this as a hard "do not mix."

Coldwater versus warmwater

Even within freshwater, coldwater species (goldfish, white clouds, hillstream loaches) and warmwater species (discus, rams, most gouramis) have non-overlapping temperature needs. The checker flags this as a habitat mismatch because no single temperature serves both.

How the SpawnOS Compatibility Score Works

The Fish Compatibility Checker turns this entire framework into a number you can act on. It does not return a yes/no — it returns a 0–100 score, a relationship type, and the reasoning behind both, because a score without a reason is just another verdict.

Under the hood it evaluates the four factors as weighted sub-scores. Water and temperature measure parameter overlap directly, using the actual ranges from the species database and rewarding wide, comfortable overlap over knife-edge compromises. Behavior applies the temperament rules — fin-nipping, territoriality, betta-specific logic, cichlid conflicts. Predation safety checks the size and prey rules, including the live-food relationship. Habitat catches the absolutes: freshwater-versus-marine, coldwater-versus-warmwater. Setup ease estimates how much the right tank design has to do to make the pairing work.

The result also names a relationship type — Tankmates, Conditional Community, Predator/Prey, Live Food, Species-Only Conflict, Habitat Mismatch, or Do Not Mix — because "compatible" means something different for two peaceful schoolers than it does for a fish and its live food. And it returns risk flags and a recommended setup so you know not just whether a pairing can work, but the exact conditions that make it work. A score of 70+ means easy success; 40–69 means workable with the right setup; below 40 means find an alternative.

The checker is deterministic and explainable by design — the same principle behind everything in SpawnOS, the aquarium operating system built by Blackwater Aquatics Canada. It tells you why, so you can make the decision yourself.

More Special Cases Worth Knowing

Beyond the headline examples, a handful of groups come up often enough that their specific behavior is worth internalizing.

African cichlids (mbuna and peacocks). These are hard-water, high-aggression fish that compatibility-wise live in their own world. The counterintuitive trick with mbuna is overstocking — a crowded tank spreads aggression so thinly that no single fish gets singled out and killed, whereas a lightly stocked mbuna tank often ends with one survivor. They need hard, alkaline water and rockwork, and they should not be mixed with soft-water community fish or with the gentler New World cichlids whose temperament they will overwhelm.

Livebearers (guppies, mollies, platies, swordtails). Hard-water, prolific, and generally peaceful, livebearers are easy community fish for hardwater setups. The catch is the constant flood of fry, which larger or opportunistic tankmates will eat — often a feature, not a bug, for population control. Male guppies' bright trailing fins can also trigger fin-nippers and male bettas, so the "peaceful" label has edges.

Plecos and large catfish. Common plecos are sold tiny and reach 18 inches; they belong only in large tanks and produce a heavy waste load that strains the bioload budget. Some large catfish are also nocturnal predators that will eat fish small enough to swallow while the keeper sleeps. The compatibility question for catfish is almost always about adult size and night-time predation, not daytime behavior.

Pufferfish. Most puffers are dedicated fin-nippers and many have specific salinity needs (some are brackish, some pure freshwater), which stacks two compatibility problems at once. Pea puffers are the most community-tolerant, and even they are best in a species tank or with fast, short-finned dither fish. Long-finned tankmates are off the table.

Introduction Order and Acclimation

How you add fish changes compatibility outcomes, especially with territorial species. A fish that has held a territory for weeks treats every newcomer as an intruder; the same two fish added together to a fresh tank start on equal footing. For territorial or semi-aggressive communities, two techniques reduce conflict: add the most aggressive species last, so it cannot establish ownership of the whole tank before others arrive, and rearrange the hardscape when introducing a new fish, which resets existing territory claims and forces everyone to renegotiate at once.

Acclimation matters too, but not the way most people think. The point of slow acclimation is parameter shock, not temperament — a fish dumped from soft store water into hard tank water suffers an osmotic jolt on top of the stress of a new environment. A stressed, freshly moved fish is also more likely to be bullied, so a quarantine period before introduction does double duty: it protects the established tank from disease and lets the newcomer recover its condition before facing tankmates. Quarantine is the most underused compatibility tool in the hobby, because a healthy fish defends itself and a sick one gets targeted.

A Pre-Purchase Research Checklist

The cheapest way to solve a compatibility problem is to never create it. Before buying any fish, five minutes of research answers the questions that prevent almost every failure. Look up the adult size, not the store size — this single number kills most predation and bioload surprises. Check the water parameter range and confirm it overlaps your tank's actual chemistry, not a chemistry you intend to chase. Read the temperament notes for fin-nipping, territoriality, and predatory behavior. Find the minimum group size for schooling species, since understocking them creates aggression. And note the swimming zone so you can balance bottom, mid, and top across the stock.

Every entry in the species database carries exactly these fields, and the compatibility checker reads from the same data, so the research and the verdict come from one consistent source. The discipline of running this checklist before every purchase — rather than after a fish is already in the bag — is what separates a planned community from a tank assembled by impulse. It is also why the breeder workflow in SpawnOS connects fish, pairs, and parameters into one system: the data you need to make a compatibility decision is the same data you need to keep, breed, and track the fish afterward.

Common Pairings at a Glance

Each of these deserves its own analysis, which is what the compatibility database provides — scored, written-up pairings with the full reasoning. Run your own combinations through the checker for an instant version of the same.

Putting It Together

Stocking a community tank well is a sequence, not a single decision. Start with the water: pick a target chemistry and choose only species whose ranges overlap it comfortably — the water parameter reference makes this a five-minute check. Then layer in temperament: avoid pairing fin-nippers with long fins, predators with mouth-sized prey, and multiple territorial fish without the space to separate them. Confirm sizes at adulthood, not in the store. Spread the stock across bottom, mid, and top zones to keep competition low. Finally, confirm you actually have the volume and filtration for the bioload with the stocking calculator, and pressure-test every pairing in the compatibility checker before you buy.

Do that and you replace the hobby's worst habit — buying fish because they looked good together in the store — with a system that tells you, in advance and with reasons, whether a tank will work. That is the whole point of treating compatibility as conditions rather than a verdict: conditions are something you can design for.

Frequently Asked Questions

Can any two fish live together if the tank is big enough? No. A bigger tank fixes aggression and competition, but it cannot fix non-overlapping temperature, incompatible water chemistry, or a predator-prey size gap. Space is a powerful lever for temperament, not a cure for chemistry or predation.

Is the "one inch of fish per gallon" rule reliable for compatibility? No. It ignores body mass, waste output, behavior, and adult size — a ten-inch oscar and ten one-inch neons are not the same load or the same risk. Use real bioload math in the stocking calculator instead.

Why did my peaceful community fish suddenly die for no reason? The most common hidden cause is chronic stress from water chemistry just outside a species' comfort range. The fish survives for months at the edge of its tolerance, then loses an opportunistic infection it would otherwise resist. Matching parameters precisely prevents most "mystery" losses.

Does the compatibility checker cost anything? No. The Fish Compatibility Checker and every other SpawnOS calculator are free and require no account. SpawnOS is a Blackwater Aquatics Canada product, and the public tools are free for everyone.