Skip to content

Upgrading to v8

This is the migration guide for upgrading from v7 to v8.

Not the version you are looking for?

Breaking changes

Removed ability to change the locale on existing Faker instances


If you are using only the default (en) locale, then you don't have to change anything.

In order to facilitate better and easier locale fallback mechanics, we removed the methods to change the locales on existing Faker instances. Now, we expose specific faker instances for each locale that you can use:


import { faker } from '@faker-js/faker';

// or
faker.locale = 'de_CH';
faker.localeFallback = 'en';


import { fakerDE_CH as faker } from '@faker-js/faker';

This also fixes issues where more than two locales are required:


import { faker, Faker } from '@faker-js/faker';

const { de_CH, de, en } = faker.locales;
const customFaker = new Faker({
  locale: 'de_CH', // the expected locale
  localeFallback: 'de', // ensure we have a German fallback for addresses
  locales: { de_CH, de, en },
const a =;
customFaker.locale = 'en'; // neither 'de_CH' nor 'de' have emojis
const b = customFaker.internet.emoji();


import { base, de, de_CH, en, Faker } from '@faker-js/faker';

// same as fakerDE_CH
export const customFaker = new Faker({
  // Now multiple fallbacks are supported
  locale: [de_CH, de, en, base],
const a =;
const b = customFaker.internet.emoji();

If you wish to create entries for multiple locales, you can still do so:


import { faker } from '@faker-js/faker';

for (let user of users) {
  const lang = faker.helpers.arrayElement(['de', 'en', 'fr']);
  faker.locale = lang; =;


import { faker, fakerDE, fakerEN, fakerFR } from '@faker-js/faker';

for (let user of users) {
  const currentFaker = faker.helpers.arrayElement([fakerDE, fakerEN, fakerFR]); =;

For more information refer to our Localization Guide.

For missing locale data, Faker will now throw instead of returning undefined or a-c


The following section mostly applies to custom-built Faker instances.

Previously, for example if en didn't have data for, then would have returned one of a, b or c (arrayElement's default value). These values aren't expected/useful as a fallback and potentially also violate the method's defined return type definitions (in case it doesn't return a string).

We have now addressed this by changing the implementation so that an error is thrown, prompting you to provide/contribute the missing data. This will also give you detailed information which data are missing. If you want to check for data you can either use entry in faker.definitions.category or use faker.rawDefinitions.category?.entry instead.

import { es, Faker, fakerES } from '@faker-js/faker';

const fakerES_noFallbacks = new Faker({
  locale: [es],
});; // 'I Want to Hold Your Hand' (fallback from en)
// Previously:
//; // 'b'
// Now:; // throws a FakerError

This also has an impact on data that aren't applicable to a locale, for example Hong Kong (en_HK) doesn't use ZIP codes/postcodes.

import { fakerEN_HK, fakerEN_US } from '@faker-js/faker';
fakerEN_US.location.zipCode(); // 90210
fakerEN_HK.location.zipCode(); // throws a FakerError

faker.mersenne and faker.helpers.repeatString removed

faker.mersenne and faker.helpers.repeatString were only ever intended for internal use, and are no longer available.


The faker.location.zipCodeByState method has been deprecated, but will also now throw an error if the current locale does not have a postcode_by_state definition.

Methods will throw on empty data set inputs

The methods faker.helpers.arrayElement and faker.helpers.arrayElements previously defaulted the array argument to a simple string array if none was provided. This behavior is no longer supported, as the default value has been removed. You are now required to provide an argument.

Additionally, when passing in an empty array argument ([]), the functions previously returned undefined. This behavior violated the expected return type of the method. The methods will now throw an FakerError instead.

The same thing happens now if you provide an empty object {} to faker.helpers.objectKey or faker.helpers.objectValue.


const allTags = ['dogs', 'cats', 'fish', 'horses', 'sheep'];
const tags = faker.helpers.arrayElements(allTags, { min: 0, max: 3 });
// `tags` might be an empty array which was no problem in v7
const featuredTag = faker.helpers.arrayElement(tags);
// `featureTag` will be typed as `string` but could actually be `undefined`


const allTags = ['dogs', 'cats', 'fish', 'horses', 'sheep'];
const tags = faker.helpers.arrayElements(allTags, { min: 0, max: 3 });
// `tags` might be an empty array which will throw in v8
const featuredTag =
  tags.length === 0 ? undefined : faker.helpers.arrayElement(tags);
// `featureTag` has to be explicitly set to `undefined` on your side

// OR

const allTags = ['dogs', 'cats', 'fish', 'horses', 'sheep'];
const tags = faker.helpers.arrayElements(allTags, { min: 0, max: 3 });
let featuredTag: string | undefined;
try {
  featuredTag = faker.helpers.arrayElement(post.tags);
} catch (e) {
  // handle error and do something special

Other deprecated methods removed/replaced

Old methodNew method
faker.uniquefaker.helpers.unique (⚠️ please check #1785)
faker.commerce.colorfaker.color.human direct replacement, see documentation for direct replacement, see documentation for, replace with faker.person.fullName
faker.image.lorempixelRemoved, as the LoremPixel service is no longer available

Definitions removed

Some data definitions, which were only available via the faker.helpers.fake method, or the undocumented faker.definitions, have been removed.

Removed dataAlternative

Deprecations and other changes

This is not an exhaustive list of all deprecations in v8.0.0. Many methods and parameters have been renamed in this release. You can:

  • use the warnings which are shown at runtime to guide you to the new names
  • use a suitable plugin to find usages of deprecated code
  • Review the full list of deprecations here and here
  • Ignore the deprecations for now: the old names will continue to work for v8.x.x, however you will need to make changes before upgrading to v9.x.x. changed to faker.person

The whole module is now located at faker.person, as it contains more information than just names. The* methods will continue to work as an alias in v8 and v9, but it is recommended to change to faker.person.*

Old methodNew method, replace with faker.person.fullName

faker.address changed to faker.location

The whole faker.address module is now located at faker.location, as it contains more information than just addresses. The faker.address.* methods will continue to work as an alias in v8 and v9, but it is recommended to change to faker.location.*

Old methodNew method

Number methods of faker.datatype moved to new faker.number module

The number-related methods previously found in faker.datatype have been moved to a new faker.number module. For the old faker.datatype.number method you should replace with or faker.number.float depending on the precision required.

By default, faker.number.float no longer defaults to a precision of 0.01

// OLD
faker.datatype.number(); // 88999 (NOTE: The default max was 99999)
faker.datatype.number({ max: 100 }); // 35
faker.datatype.number({ max: 100, precision: 0.01 }); // 35.21
faker.datatype.float({ max: 100 }); // 35.21
faker.datatype.float({ max: 100, precision: 0.001 }); // 35.211

// NEW{ max: 99999 }); // 88999 (NOTE: the default max is now Number.MAX_SAFE_INTEGER){ max: 100 }); // 35
faker.number.float({ max: 100 }); // 35.21092065742612
faker.number.float({ max: 100, precision: 0.01 }); // 35.21
Old methodNew method or faker.number.float

Deprecation of faker.datatype.array

The method faker.datatype.array has been deprecated and will be removed in v9. If you need an array of useful values, you are better off creating your own one using faker.helpers.multiple.

faker.datatype.datetime deprecated in favor of and

The datetime method previously found in faker.datatype has been deprecated, use or instead.

faker.helpers.regexpStyleStringParse deprecated in favor of faker.helpers.fromRegExp

The regexpStyleStringParse method in faker.helpers has been deprecated in Faker 8.1. A likely replacement is the more powerful faker.helpers.fromRegExp.

faker.helpers.regexpStyleStringParse('a{3,6}'); // aaaaa
faker.helpers.fromRegExp('a{3,6}'); // aaaaa

However, please note that faker.helpers.fromRegExp is not an exact replacement for faker.helpers.regexpStyleStringParse as fromRegExp cannot handle numeric ranges. This will now need to be handled separately.

faker.helpers.regexpStyleStringParse('a{3,6}[1-100]'); // "aaaa53", etc.
faker.helpers.fromRegExp('a{3,6}') +{ min: 1, max: 100 });

allowLeadingZeros behavior change in faker.string.numeric

The allowLeadingZeros boolean parameter in faker.string.numeric (in the new string module) now defaults to true. faker.string.numeric will now generate numeric strings that could have leading zeros by default.

Simplified MIME type data

The functions faker.system.mimeType, faker.system.fileType and faker.system.fileExt now return data from a smaller set of more common MIME types, filetypes and extensions.

faker.helpers.unique is planned to be outsourced

The faker.helpers.unique method is planned to be outsourced to a separate package.
Please check issue #1785 for more details.

Locales renamed

The en_IND (English, India) locale was renamed to en_IN for consistency with other locales.

The cz (Czech) locale was renamed to cs_CZ to use the standard ISO codes for language and country.

The ge (Georgian) locale was renamed to ka_GE to use the standard ISO codes for language and country.

Released under the MIT License.