---
name: bio-primer-design-primer-basics
description: Designs and ranks PCR primer pairs for a target template with primer3-py (design_primers), returning pairs with nearest-neighbor Tm, GC, product size, and complementarity scores. Covers why primer3 is a LOCAL weighted-penalty minimizer over the single template supplied (so PRIMER_PAIR_0 is the lowest-penalty pair under the given bounds, never a genome-specificity guarantee), why Tm is a salt/concentration-dependent SantaLucia prediction not a fixed property, why the two primers must be Tm-matched, the seq_args/global_args tag semantics (SEQUENCE_TARGET/INCLUDED/EXCLUDED/OVERLAP_JUNCTION/FORCE_*, 0-based [start,length]), 3'-end and GC-clamp mechanism, 5'-tail handling, masking SNPs under 3' ends, and diagnosing zero-pair runs. Use when designing standard PCR, cloning, genotyping, or sequencing primers, flanking a target, or screening pairs by Tm/size/GC. Genome off-target checking is primer-specificity; dimers/hairpins primer-validation; qPCR and probes qpcr-primers.
tool_type: python
primary_tool: primer3-py
---

## Version Compatibility

Reference examples tested with: primer3-py 2.3+.

Before using code patterns, verify installed versions match. If versions differ:
- Python: `pip show primer3-py` then `help(primer3.design_primers)` to check signatures

If code throws ImportError, AttributeError, or TypeError, introspect the installed
package and adapt the example to match the actual API rather than retrying.

# PCR Primer Design -- Ranked Pairs Under Local Thermodynamic Constraints

**"Design primers to amplify this region"** -> Search candidate primer pairs that satisfy Tm/GC/size/complementarity constraints on the supplied template and rank them by a weighted penalty -- because primer3 sees only that one template, so its top pair certifies LOCAL good behavior, not that the primers bind the target uniquely in the genome.
- Python: `primer3.design_primers(seq_args, global_args)` returns a flat dict of ranked pairs with per-primer Tm/GC and a pair penalty.

Scope: designing and ranking PCR primer pairs for a template under thermodynamic and positional constraints, including cloning (5' tails), genotyping (flanking), and single sequencing primers. Genome-wide off-target / in-silico PCR specificity -> primer-specificity. Dimer/hairpin/end-stability validation of chosen oligos -> primer-validation. qPCR primers and hydrolysis/beacon probes -> qpcr-primers. OUT OF SCOPE: degenerate/consensus primers for divergent targets (primer3 does not model IUPAC degeneracy -- use a dedicated consensus designer); long-range PCR amplicons over ~3-5 kb (different polymerase and primer regime); and bisulfite/methylation (MSP/BSP) primers (different rules -- avoid CpGs in the body, account for C->T strand asymmetry -- use a bisulfite-specific designer such as MethPrimer). Fetching the template -> database-access/entrez-fetch. Reverse-complement / subsequence extraction -> sequence-manipulation/seq-objects.

## The Single Most Important Modern Insight -- PRIMER_PAIR_0 Is the Argmin of a Penalty the User Partly Authors, on the Only Template primer3 Sees

1. **primer3 optimizes locally and is blind to the rest of the genome.** It solves a constrained penalty minimization over the ONE `SEQUENCE_TEMPLATE` string: it scores Tm, GC, length, self-/cross-complementarity, hairpins, and 3'-end stability, then returns the lowest-penalty pairs. It never asks whether those primers also bind 50 other loci. So `PRIMER_PAIR_0` means "lowest penalty under the chosen weights and bounds, on this one template" -- it is a hypothesis, not a result. The catastrophic, common error is ordering the top pair without a genome specificity pass (-> primer-specificity).
2. **Tm is a prediction, not a property.** primer3 computes a nearest-neighbor Tm (SantaLucia 1998 *PNAS* 95:1460) at a specific oligo concentration and salt; change the salt/Mg/DNA-conc inputs and the same sequence reports a different Tm. Use predicted Tm to MATCH the two primers (within ~1-2 C) and to RANK candidates, not as the literal anneal temperature. The single largest predicted-vs-bench divergence is free Mg2+ (dNTPs chelate Mg2+ roughly 1:1, so free Mg2+ ~= total Mg - total dNTP; Owczarzy 2008 *Biochemistry* 47:5336).
3. **Bounds and weights do different jobs.** `PRIMER_MIN_*`/`PRIMER_MAX_*` are HARD filters (a candidate outside them is eliminated); `PRIMER_OPT_*` plus the `PRIMER_WT_*` weights only RANK the survivors. Over-tightening BOUNDS is what returns zero pairs; changing weights only re-orders. The defaults are an opinionated weight vector (Tm and size dominate; GC-percent weights are 0 by default), not an objective truth.

## How primer3 Scores: Weighted Penalty Minimization

Each tunable property has an `OPT` target and a weight (often split into `_LT`/`_GT` for below/above optimum). The per-oligo penalty is the weighted sum of deviations; the pair penalty adds pair terms (`PRIMER_PAIR_WT_DIFF_TM` for Tm mismatch, product-size deviation, cross-complementarity). Pairs are sorted ascending by `PRIMER_PAIR_<i>_PENALTY`; index 0 is the minimum. Two consequences the agent must act on: (a) raise `PRIMER_PAIR_WT_DIFF_TM` if a Tm-matched pair matters more than tight product size, and a different pair rises to index 0; (b) to forbid something use a BOUND, to merely discourage it raise a WEIGHT.

## Tool Taxonomy

| Tool / method | Citation | Mechanism / role | When |
|---------------|----------|------------------|------|
| primer3-py `design_primers` | Untergasser 2012 *Nucleic Acids Res* 40:e115 | constraint-satisfaction search + nearest-neighbor Tm; returns ranked pairs | the default PCR primer designer |
| Nearest-neighbor Tm (SantaLucia) | SantaLucia 1998 *PNAS* 95:1460 | salt/concentration-dependent thermodynamic Tm from stacking parameters | every Tm value primer3 reports |
| primer3 Tm/salt implementation | Koressaar & Remm 2007 *Bioinformatics* 23:1289 | the Tm + divalent-cation salt correction primer3 uses | when matching primer3 Tm to bench conditions |
| Mispriming library (`misprime_lib`) | Untergasser 2012 *Nucleic Acids Res* 40:e115 | penalizes similarity to a curated repeat library (HUMREP/RODENT) | keep primers off known repeats (NOT a genome check) |
| Genome BLAST / in-silico PCR | (route OUT) | predicts off-target amplicons from the PAIR | confirm the pair amplifies only the target -> primer-specificity |

## Decision Tree by Scenario

| Scenario | Recommended | Why |
|----------|-------------|-----|
| Standard amplicon over one target | `design_primers` with `SEQUENCE_TARGET` flanking the feature | both primers flank, amplicon spans the feature |
| Amplify within a clean window (one exon) | `SEQUENCE_INCLUDED_REGION` confines primers | no primer falls outside the window |
| Keep primers off a SNP/repeat | `SEQUENCE_EXCLUDED_REGION` (no overlap) | excluding beats N-masking (N-masking still allows a primer with <= MAX_NS_ACCEPTED Ns) |
| Left primer from region A, right from region B | `SEQUENCE_PRIMER_PAIR_OK_REGION_LIST` quadruples | constrains the two primers independently, per pair |
| cDNA-specific (avoid unspliced gDNA) | `SEQUENCE_OVERLAP_JUNCTION_LIST` + `PRIMER_MIN_3_PRIME_OVERLAP_OF_JUNCTION` | a primer straddling the splice junction cannot prime contiguous gDNA |
| One Sanger sequencing primer | `PRIMER_PICK_LEFT_PRIMER=1`, `PRIMER_PICK_RIGHT_PRIMER=0` | single-primer mode; leave >=30-50 bp buffer to the feature |
| Cloning / adapters (restriction, Gibson, T7) | design the binding core in primer3, append the 5' tail afterward | a non-templated tail does not anneal in early cycles |
| Genotype a SNP by allele-specific PCR (ARMS) | discriminating base at the 3' terminus + a second -2/-3 mismatch; allele-specific primer + common reverse | the 3' anchor discriminates the allele, the second mismatch widens it |
| Choose the annealing temperature | Ta ~3-5 C below the lower primer Tm; gradient to optimize; touchdown for hard specificity | predicted Tm is not Ta; the reaction is non-equilibrium |
| Divergent / unknown-reference target (degenerate primers) | a consensus/degenerate designer, NOT primer3 | primer3 cannot model IUPAC degeneracy; design in conserved blocks, keep the 3' anchor non-degenerate |
| Amplicon over ~3-5 kb (long-range PCR) | longer high-Tm primers (24-30 nt), proofreading/long-range polymerase | the enzyme tolerates less mispriming over long extensions; raise OPT_TM/OPT_SIZE, tighten end-stability |
| Confirm the pair is unique genome-wide | -> primer-specificity | primer3 scores thermodynamics, not specificity |
| Check the chosen pair for dimers/hairpins | -> primer-validation | thermodynamic structure prediction of the oligos |

Default when uncertain: standard amplicon with `SEQUENCE_TARGET`, Tm 58-62 C, GC 40-60%, product 100-1000 bp, then route the top pairs to primer-specificity before ordering.

## Design a Tm-Matched Primer Pair

**Goal:** Get ranked primer pairs that amplify the target region within the desired size and Tm window, Tm-matched between the two primers.

**Approach:** Put per-template data (the sequence and any positional constraint) in `seq_args` under `SEQUENCE_*` keys; put run-wide settings (Tm/GC/size bounds, salt) in `global_args` under `PRIMER_*` keys; call `design_primers`; read the ranked pairs from the flat result dict. Supply the real reaction salt so the reported Tm is meaningful.

```python
import primer3

template = 'ATGC...'  # the only sequence primer3 sees

result = primer3.design_primers(
    seq_args={
        'SEQUENCE_ID': 'amp1',
        'SEQUENCE_TEMPLATE': template,
        'SEQUENCE_TARGET': [400, 60],          # [start, length], 0-based; both primers must flank this
    },
    global_args={
        'PRIMER_PICK_LEFT_PRIMER': 1,
        'PRIMER_PICK_RIGHT_PRIMER': 1,
        'PRIMER_NUM_RETURN': 5,
        'PRIMER_OPT_SIZE': 20, 'PRIMER_MIN_SIZE': 18, 'PRIMER_MAX_SIZE': 25,
        'PRIMER_OPT_TM': 60.0, 'PRIMER_MIN_TM': 58.0, 'PRIMER_MAX_TM': 62.0,
        'PRIMER_PAIR_MAX_DIFF_TM': 2.0,        # keep the pair within 2 C of each other
        'PRIMER_MIN_GC': 40.0, 'PRIMER_MAX_GC': 60.0,
        'PRIMER_PRODUCT_SIZE_RANGE': [[150, 400]],
        'PRIMER_SALT_MONOVALENT': 50.0,        # mM; match the reaction (drives Tm)
        'PRIMER_SALT_DIVALENT': 1.5,           # mM Mg2+
        'PRIMER_DNTP_CONC': 0.6,               # mM; subtracted from Mg2+ to get free Mg2+
        'PRIMER_DNA_CONC': 50.0,               # nM oligo
        'PRIMER_EXPLAIN_FLAG': 1,              # so a zero-pair run is diagnosable
    })

for i in range(result['PRIMER_PAIR_NUM_RETURNED']):
    print(result[f'PRIMER_LEFT_{i}_SEQUENCE'], result[f'PRIMER_RIGHT_{i}_SEQUENCE'],
          round(result[f'PRIMER_LEFT_{i}_TM'], 1), round(result[f'PRIMER_RIGHT_{i}_TM'], 1),
          result[f'PRIMER_PAIR_{i}_PRODUCT_SIZE'], round(result[f'PRIMER_PAIR_{i}_PENALTY'], 2))
```

## Positional Constraints: Get the Tag Semantics Right

These are the most error-prone keys; the distinctions are load-bearing. All coordinates are 0-based by default (`PRIMER_FIRST_BASE_INDEX`), and every interval is `[start, length]`, NOT `[start, end]`.

- `SEQUENCE_TARGET = [start, length]` -- a legal pair must FLANK the target (both primers outside, amplicon spans it). Use to force the amplicon to cover a feature.
- `SEQUENCE_INCLUDED_REGION = [start, length]` -- primers are CONFINED within it; no part of a primer may fall outside.
- `SEQUENCE_EXCLUDED_REGION = [[start, length], ...]` -- no primer may OVERLAP any listed interval (even by one base).
- `SEQUENCE_PRIMER_PAIR_OK_REGION_LIST = [[lstart, llen, rstart, rlen], ...]` -- per-pair windows for the left and right primer independently (-1 leaves a side free).
- `SEQUENCE_OVERLAP_JUNCTION_LIST = [pos, ...]` with `PRIMER_MIN_3_PRIME_OVERLAP_OF_JUNCTION` (default 4) and `PRIMER_MIN_5_PRIME_OVERLAP_OF_JUNCTION` (default 7) -- at least one primer must straddle a junction; the 3' overlap is the specificity-determining knob.
- `SEQUENCE_FORCE_LEFT_START/_RIGHT_START` (fix the 5' end) and `_LEFT_END/_RIGHT_END` (fix the 3' end) -- pin a primer to a known oligo while primer3 picks the partner.

## The 3' End Governs Priming -- and 5' Tails Do Not Anneal

Polymerase extends only from a base-paired 3'-OH, so the terminal ~5 nt are the priming anchor: a 3'-terminal mismatch suppresses extension by orders of magnitude (Kwok 1990 *Nucleic Acids Res* 18:999), which is why primer3 weights 3'-end (`_END`) complementarity far above internal (`_ANY`). A GC clamp (`PRIMER_GC_CLAMP`, default 0; set 1) stabilizes the anchor, but a too-stable 3' end is double-edged -- it also anchors at off-target sites, so cap it with `PRIMER_MAX_END_STABILITY` (a positive stability magnitude for the 3'-terminal pentamer in kcal/mol, NOT a signed dG; library default 100.0 = effectively off; lowering to ~9 as a heuristic forbids over-stable ends). For a primer carrying a non-templated 5' tail (restriction site, Gibson arm, T7 promoter, universal tail): design the template-binding CORE in primer3 so its Tm reflects only the annealing region, then prepend the tail in software; pasting the full tailed oligo into a Tm calculator overestimates the anneal Tm. The tail still exists physically, so check dimers/hairpins on the FULL tailed oligo (-> primer-validation).

## Predicted Tm Is Not the Annealing Temperature

The Tm primer3 reports is an equilibrium midpoint against a perfect complement at the supplied oligo/salt concentration; the annealing temperature (Ta) the thermocycler runs is a separate operating point in a non-equilibrium reaction. A workable default is Ta ~3-5 C below the LOWER of the two primers' predicted Tm, then optimize empirically: a gradient PCR brackets the Ta giving a single product, and Rychlik's optimum (Ta_opt = 0.3*Tm_primer + 0.7*Tm_product - 14.9; Rychlik 1990 *Nucleic Acids Res* 18:6409) accounts for the product. When specificity is hard (paralogs, high background), use touchdown PCR (Don 1991 *Nucleic Acids Res* 19:4008): start Ta several degrees ABOVE the expected Tm so only the perfect target nucleates, then step down each cycle -- the specific product established first outcompetes later mispriming.

## Allele-Specific (ARMS) Primers Exploit the 3' End Constructively

The same 3'-terminal sensitivity that causes allele dropout is the basis of allele-specific PCR: place the discriminating base at the primer's 3' TERMINUS so the off-allele mismatches the anchor and fails to extend, and add a second deliberate mismatch at the -2 or -3 position so the off-allele carries two destabilizing mismatches and the discrimination widens (Newton 1989 *Nucleic Acids Res* 17:2503). Design one allele-specific primer per allele sharing a common reverse primer, and confirm discrimination with no-template and opposite-allele controls. (This is the constructive inverse of the SNP-under-3'-end failure mode below.)

## Per-Method Failure Modes

### Top pair ordered without a specificity check
**Trigger:** Treating `PRIMER_PAIR_0` as final. **Mechanism:** primer3 never sees off-target loci; a thermodynamically perfect pair can prime paralogs, pseudogenes, or repeats. **Symptom:** multiple bands on a gel; off-target amplicon in sequencing. **Fix:** route every chosen pair through primer-specificity (Primer-BLAST / in-silico PCR) before ordering.

### Tm mismatch between forward and reverse
**Trigger:** Wide `PRIMER_MIN_TM`/`MAX_TM` with no pair-difference cap. **Mechanism:** the lower-Tm primer is under-annealed at the anneal step, so one strand dominates. **Symptom:** weak/biased amplification, smeary product. **Fix:** set `PRIMER_PAIR_MAX_DIFF_TM` ~2 C and/or raise `PRIMER_PAIR_WT_DIFF_TM`.

### Coordinate or tag confusion
**Trigger:** Passing `[start, end]` instead of `[start, length]`, assuming 1-based, or swapping TARGET (force-flank) / INCLUDED (confine) / EXCLUDED (no-overlap). **Mechanism:** every region shifts or the wrong constraint applies. **Symptom:** primers land in the wrong place, or zero pairs return. **Fix:** use `[start, length]`, keep `PRIMER_FIRST_BASE_INDEX` at 0, and match the tag to intent from the Decision Tree.

### SNP under the 3' end
**Trigger:** A common variant beneath a primer's last ~5 nt. **Mechanism:** the primer matches one allele and mismatches the other at the anchor (Kwok 1990 *Nucleic Acids Res* 18:999), so the alternate allele is under-amplified. **Symptom:** allele dropout / spurious homozygosity. **Fix:** pull common SNPs (dbSNP/gnomAD, MAF >= 1%) and add them to `SEQUENCE_EXCLUDED_REGION`.

### 5'-tail folded into the Tm
**Trigger:** Including a non-templated tail in the annealing-Tm calculation. **Mechanism:** the tail does not pair in early cycles but inflates the computed Tm. **Symptom:** annealing temperature set too high, early-cycle failure. **Fix:** design the core in primer3, append the tail after, re-check dimers on the full oligo.

## Quantitative Thresholds

| Threshold | Source | Rationale |
|-----------|--------|-----------|
| Primer length 18-25 nt (opt 20) | Rozen & Skaletsky 2000 *Methods Mol Biol* 132:365 | long enough for specificity, short enough to anneal fast; primer3 default OPT 20 |
| Tm 58-62 C, pair within <=2 C | Koressaar & Remm 2007 *Bioinformatics* 23:1289 | matched Tm so both primers anneal at one Ta; predicted Tm is salt/conc-dependent |
| GC 40-60% | Rozen & Skaletsky 2000 *Methods Mol Biol* 132:365 | default 20-80 is far too wide; extremes prime poorly |
| GC clamp 1 (max 2 in last 5) | community/vendor practice (3'-anchor stability per SantaLucia 1998 *PNAS* 95:1460) | a stable 3' anchor aids extension; >=3 G/C invites mispriming (a design heuristic, not from the NN paper) |
| `PRIMER_MAX_END_STABILITY` ~9 (heuristic) | community practice (param: Untergasser 2012 *Nucleic Acids Res* 40:e115) | positive stability magnitude (kcal/mol) of the 3'-pentamer; library default 100 is off; cap to curb mispriming |
| `PRIMER_MAX_POLY_X` 4 | Untergasser 2012 *Nucleic Acids Res* 40:e115 | homopolymer 3' ends slip-register on repetitive template |
| Product 100-1000 bp (standard PCR) | -- | routine amplicon band; set per assay (qPCR 70-150 -> qpcr-primers) |
| Free Mg2+ ~= total Mg - total dNTP | Owczarzy 2008 *Biochemistry* 47:5336 | only free Mg2+ stabilizes the duplex; the #1 predicted-vs-bench Tm gap |

## Diagnose a Zero-Pair Run

When `PRIMER_PAIR_NUM_RETURNED == 0` this is a constraint problem, not a bug. Set `PRIMER_EXPLAIN_FLAG = 1` and read `PRIMER_LEFT_EXPLAIN`, `PRIMER_RIGHT_EXPLAIN`, `PRIMER_PAIR_EXPLAIN` -- each tallies how many candidates failed for each reason ("considered 4500, GC content failed 1200, low tm 800, ... ok 0"). The dominant bucket names the single constraint to loosen. Loosen ONE constraint at a time and re-read; typical order of suspects: product-size range too narrow, Tm window too tight (or wrong salt/DNA-conc), GC window too tight, positional over-constraint, then complementarity ceilings.

## Common Errors

| Error / symptom | Cause | Solution |
|-----------------|-------|----------|
| `AttributeError: designPrimers` | camelCase deprecated since primer3-py 1.0.0 | use `primer3.design_primers` (snake_case) |
| Zero pairs returned | bounds too tight / region too short / N-masked template | `PRIMER_EXPLAIN_FLAG=1`, loosen one constraint at a time |
| Tm differs from another tool | different salt-correction model or concentrations | match `PRIMER_SALT_*`, `PRIMER_DNTP_CONC`, `PRIMER_DNA_CONC`; compare like for like |
| Primers amplify multiple bands | no genome specificity check | route the pair to primer-specificity (BLAST / in-silico PCR) |
| A `SEQUENCE_*`/`PRIMER_*` key is ignored | wrong dict (SEQUENCE in global_args or vice versa) | put `SEQUENCE_*` in seq_args, `PRIMER_*` in global_args |
| Allele dropout in some samples | SNP under a primer 3' end | exclude common variants from the primer-binding region |
| GC-rich/structured template will not amplify | high effective Tm and secondary structure | add DMSO/betaine/7-deaza-dGTP to lower effective Tm and disrupt structure -- a reagent lever orthogonal to redesign (primer3 does not model additives) |

## References

- Untergasser A, Cutcutache I, Koressaar T, et al. 2012. Primer3 - new capabilities and interfaces. *Nucleic Acids Res* 40:e115.
- Koressaar T, Remm M. 2007. Enhancements and modifications of primer design program Primer3. *Bioinformatics* 23:1289-1291.
- SantaLucia J Jr. 1998. A unified view of polymer, dumbbell, and oligonucleotide DNA nearest-neighbor thermodynamics. *PNAS* 95:1460-1465.
- Owczarzy R, Moreira BG, You Y, et al. 2008. Predicting stability of DNA duplexes in solutions containing magnesium and monovalent cations. *Biochemistry* 47:5336-5353.
- Kwok S, Kellogg DE, McKinney N, et al. 1990. Effects of primer-template mismatches on the polymerase chain reaction: human immunodeficiency virus type 1 model studies. *Nucleic Acids Res* 18:999-1005.
- Rychlik W, Spencer WJ, Rhoads RE. 1990. Optimization of the annealing temperature for DNA amplification in vitro. *Nucleic Acids Res* 18:6409-6412.
- Don RH, Cox PT, Wainwright BJ, et al. 1991. 'Touchdown' PCR to circumvent spurious priming during gene amplification. *Nucleic Acids Res* 19:4008.
- Newton CR, Graham A, Heptinstall LE, et al. 1989. Analysis of any point mutation in DNA. The amplification refractory mutation system (ARMS). *Nucleic Acids Res* 17:2503-2516.
- Rozen S, Skaletsky H. 2000. Primer3 on the WWW for general users and for biologist programmers. *Methods Mol Biol* 132:365-386.

## Related Skills

- primer-validation - Check chosen primers for dimers, hairpins, and 3'-end stability
- primer-specificity - Confirm the pair amplifies only the target genome-wide (in-silico PCR / Primer-BLAST)
- qpcr-primers - Design qPCR primers and hydrolysis/molecular-beacon probes
- database-access/entrez-fetch - Fetch the template sequence to design against
- sequence-manipulation/seq-objects - Reverse-complement and extract subsequences
- sequence-io/read-sequences - Read the target FASTA