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

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).
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).
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.

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.3Tm_primer + 0.7Tm_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