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.designprimers(seqargs, 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 -- PRIMERPAIR0 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 SEQUENCETEMPLATE 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 PRIMERPAIR_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. PRIMERMIN/PRIMERMAX are HARD filters (a candidate outside them is eliminated); PRIMEROPT plus the PRIMERWT 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 (PRIMERPAIRWTDIFFTM for Tm mismatch, product-size deviation, cross-complementarity). Pairs are sorted ascending by PRIMERPAIR<i>PENALTY; index 0 is the minimum. Two consequences the agent must act on: (a) raise PRIMERPAIRWTDIFF_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

Decision Tree by Scenario

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 seqargs under SEQUENCE keys; put run-wide settings (Tm/GC/size bounds, salt) in globalargs 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 (PRIMERFIRSTBASE_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.
• SEQUENCEINCLUDEDREGION = [start, length] -- primers are CONFINED within it; no part of a primer may fall outside.
• SEQUENCEEXCLUDEDREGION = [[start, length], ...] -- no primer may OVERLAP any listed interval (even by one base).
• SEQUENCEPRIMERPAIROKREGION_LIST = [[lstart, llen, rstart, rlen], ...] -- per-pair windows for the left and right primer independently (-1 leaves a side free).
• SEQUENCEOVERLAPJUNCTIONLIST = [pos, ...] with PRIMERMIN3PRIMEOVERLAPOFJUNCTION (default 4) and PRIMERMIN5PRIMEOVERLAPOF_JUNCTION (default 7) -- at least one primer must straddle a junction; the 3' overlap is the specificity-determining knob.
• SEQUENCEFORCELEFTSTART/RIGHTSTART (fix the 5' end) and LEFTEND/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 (PRIMERGCCLAMP, 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 PRIMERMAXEND_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 (Taopt = 0.3Tmprimer + 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 PRIMERPAIR0 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 PRIMERMINTM/MAXTM 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 PRIMERPAIRMAXDIFFTM ~2 C and/or raise PRIMERPAIRWTDIFF_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 PRIMERFIRSTBASE_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 SEQUENCEEXCLUDEDREGION.

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

Diagnose a Zero-Pair Run

When PRIMERPAIRNUMRETURNED == 0 this is a constraint problem, not a bug. Set PRIMEREXPLAINFLAG = 1 and read PRIMERLEFTEXPLAIN, PRIMERRIGHTEXPLAIN, PRIMERPAIR_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

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