Quick Reference · realistic test-data generation

faker · cheat sheet

One idea underneath everything: fake = Faker() is a generator that bundles providers (person, internet, address…). Every call — fake.name() — is forwarded to format(), which picks a value from that provider's dataset using a shared random.Random. Seed the random, and the data becomes reproducible.

setup & core person / company internet / contact location text · dates · numbers control & extend gotcha ★ most common

Introspected from Faker 40.36.0 (installed & run) & cross-checked with: faker.readthedocs.io · pypi.org/project/Faker · github.com/joke2k/faker · Faker pytest-fixtures docs · factory_boy docs · re-verified 2026-08-30: Faker 40.37.0 (21 Aug 2026) current

How a call becomes fake data — and the four surfaces that control it
THE CALL PIPELINE Faker(locale) the generator bundled providers person · company internet · address lorem · date · python format(name) dispatch by name random.Random picks from dataset 'Allison Hill' a fresh value each call fake.name() FOUR CONTROL SURFACES — same generator, tuned Faker.seed(0) pins the shared random → same data every run. reproducible tests .unique.email() never repeats a value for this instance until cleared. primary keys / emails .optional.x(prob) returns the value — or None at the given chance. nullable columns fake['ja_JP'] subscript pins one locale on a multi-locale generator. region-specific data A call = fake.<provider-method>(). There is no separate namespace — every provider's methods live flat on the generator. Chain a surface before the call: fake.unique['en_US'].first_name() — unique + locale, together. seed → provider → random pick → value · the whole library is variations on this one line
quickstart · the 10 lines that cover 90% of use
from faker import Faker

fake = Faker()                 # en_US generator
Faker.seed(0)                 # reproducible: class-level, shared RNG

fake.name()                     # 'Allison Hill'
fake.email()                    # 'jason41@example.net'
fake.address()                  # '9402 Peterson Drives\nPort Matthew, CO 50298'
fake.unique.email()             # guaranteed distinct for this instance
fake.optional.phone_number(prob=0.5)   # value or None
[fake.name() for _ in range(100)]   # bootstrap a table
01Setup & the core ideaimport · construct
02Personprovider · person
03Internet & contactprovider · internet
04Addressprovider · address
05Phone & geophone_number · geo
06Company & jobcompany · job
07Text · loremprovider · lorem
08Date & timeprovider · date_time
09Numbers & pickingpython · baseprovider
10IDs, hashes & blobsprovider · misc
11Finance & IDscredit_card · bank · ssn
12Colors, codes & agentscolor · barcode · automotive
13Whole recordsprovider · profile
14String templatingpattern → value
15Reproducibility · seedingthe control surface
16Unique & optionalproxies on the stream
17Extend itcustom providers
18In testspytest · factory_boy · CLI

Four ideas that make the rest obvious

Everything above is one of these four patterns in disguise. Learn the shapes, not the method list.

one fake = one method on one provider

The generator flattens every provider's methods onto itself — there's no fake.person.name(), just fake.name().

fake person internet address .name() .first_name() .email() .ipv4() .city() .zipcode() …all callable flat on fake

same seed → same stream

Faker.seed(0) resets the shared RNG, so two runs emit the identical sequence — the backbone of reproducible tests.

seed(0) seed(0) run A run B Norma Ryan Mary Norma Ryan Mary — identical —

plain · unique · optional

Three ways to draw from the same method. unique filters out repeats; optional injects None; plain does neither.

fake.x() a a b c c any .unique.x() a a̶ b c c̶ no dup .optional.x() a None None c None nullable

locale & fallback

A locale supplies its own datasets; anything it lacks falls back to en_US. A list rotates locales per call.

Faker('it_IT') has it_IT data? use it → 'Palumbo' else → en_US Faker(['en','ja_JP']) each call rotates locale Leslie 鈴木 陽一 ['ja_JP'] pins

Worth memorizing

Faker.seed()classmethod → seeds the shared RNG; seed_instance() isolates one
not stable across versionspin Faker==x.y.z if you hardcode outputs
.unique ≠ freelow-cardinality fakes raise UniquenessException (birthday paradox)
.unique.clear()resets seen values; uniqueness is per instance
email() can collideuse fake.unique.email() for keys / unique columns
.optional is a proxyfake.optional.x(prob=) → value or None; not optional()
locale fallbackmissing provider in a locale falls back to en_US
use_weighting=Falsefaster & uniform — you lose real-world frequency
flat namespaceno fake.person.name() — every method is on fake
pytest faker fixtureseed 0, reseeded + .unique cleared before each test
dict = weighted pickrandom_element({'a':0.9,'b':0.1}) biases the draw
CLIpython -m faker -l de_DE -r 5 name