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.
Installer avec Codex ou Claude Copiez ce prompt, collez-le dans Codex, Claude ou un autre assistant, puis laissez-le vérifier la page du skill et l'installer pour vous.
Une commande directe contourne le prompt de vérification. Examinez la source avant de l'exécuter.
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
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.
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 inrange(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
