bun install

import Install from "/ru/snippets/cli/install.mdx";

Основное использование

bash

bun install react
bun install react@19.1.1 # конкретная версия
bun install react@latest # конкретный тег

CLI bun содержит совместимый с Node.js менеджер пакетов, предназначенный для значительно более быстрой замены npm, yarn и pnpm. Это автономный инструмент, который будет работать в существующих проектах Node.js; если в вашем проекте есть package.json, bun install поможет вам ускорить рабочий процесс.

NOTE

⚡️ В 25 раз быстрее — Переключитесь с npm install на bun install в любом проекте Node.js, чтобы ускорить установки до 25 раз.

Для пользователей Linux

Рекомендуемая минимальная версия ядра Linux — 5.6. Если вы используете ядро Linux 5.1 - 5.5, bun install будет работать, но HTTP-запросы будут медленными из-за отсутствия поддержки операции connect() io_uring.

Если вы используете Ubuntu 20.04, вот как установить новое ядро:

bash

# Если это возвращает версию >= 5.6, вам не нужно ничего делать
uname -r

# Установить официальное ядро аппаратного обеспечения Ubuntu
sudo apt install --install-recommends linux-generic-hwe-20.04

Для установки всех зависимостей проекта:

bash

bun install

Запуск bun install выполнит:

Установит все dependencies, devDependencies и optionalDependencies. Bun установит peerDependencies по умолчанию.
Запустит скрипты вашего проекта {pre|post}install и {pre|post}prepare в соответствующее время. По соображениям безопасности Bun не выполняет скрипты жизненного цикла установленных зависимостей.
Запишет файл блокировки bun.lock в корень проекта.

Логирование

Для изменения детализации логирования:

bash

bun install --verbose # отладочное логирование
bun install --silent  # без логирования

Скрипты жизненного цикла

В отличие от других клиентов npm, Bun не выполняет произвольные скрипты жизненного цикла, такие как postinstall, для установленных зависимостей. Выполнение произвольных скриптов представляет потенциальный риск для безопасности.

Чтобы разрешить Bun выполнять скрипты жизненного цикла для конкретного пакета, добавьте пакет в trustedDependencies в вашем package.json.

json

{
  "name": "my-app",
  "version": "1.0.0",
  "trustedDependencies": ["my-trusted-package"] 
}

Затем переустановите пакет. Bun прочитает это поле и выполнит скрипты жизненного цикла для my-trusted-package.

Скрипты жизненного цикла будут выполняться параллельно во время установки. Для настройки максимального количества одновременных скриптов используйте флаг --concurrent-scripts. По умолчанию это удвоенное количество сообщаемых процессоров или GOMAXPROCS.

bash

bun install --concurrent-scripts 5

Bun автоматически оптимизирует скрипты postinstall для популярных пакетов (таких как esbuild, sharp и т.д.), определяя, какие скрипты нужно выполнить. Чтобы отключить эти оптимизации:

bash

BUN_FEATURE_FLAG_DISABLE_NATIVE_DEPENDENCY_LINKER=1 bun install
BUN_FEATURE_FLAG_DISABLE_IGNORE_SCRIPTS=1 bun install

Рабочие области

Bun поддерживает "workspaces" в package.json. Полную документацию см. в Менеджер пакетов > Рабочие области.

json

{
  "name": "my-app",
  "version": "1.0.0",
  "workspaces": ["packages/*"], 
  "dependencies": {
    "preact": "^10.5.13"
  }
}

Установка зависимостей для конкретных пакетов

В монорепозитории вы можете установить зависимости для подмножества пакетов, используя флаг --filter.

bash

# Установить зависимости для всех рабочих областей, кроме pkg-c
bun install --filter '!pkg-c'

# Установить зависимости только для pkg-a в ./packages/pkg-a
bun install --filter './packages/pkg-a'

Дополнительную информацию о фильтрации с bun install см. в Менеджер пакетов > Фильтрация

Переопределения и разрешения

Bun поддерживает "overrides" от npm и "resolutions" от Yarn в package.json. Это механизмы для указания диапазона версий мета-зависимостей — зависимостей ваших зависимостей. Полную документацию см. в Менеджер пакетов > Переопределения и разрешения.

json

{
  "name": "my-app",
  "dependencies": {
    "foo": "^2.0.0"
  },
  "overrides": { 
    "bar": "~4.4.0"
  } 
}

Глобальные пакеты

Для глобальной установки пакета используйте флаг -g/--global. Обычно это используется для установки инструментов командной строки.

bash

bun install --global cowsay # или `bun install -g cowsay`
cowsay "Bun!"

txt

 ______
< Bun! >
 ------
        \   ^__^
         \  (oo)\_______
            (__)\       )\/\
                ||----w |
                ||     ||

Режим production

Для установки в режиме production (т.е. без devDependencies или optionalDependencies):

bash

bun install --production

Для воспроизводимых установок используйте --frozen-lockfile. Это установит точные версии каждого пакета, указанные в файле блокировки. Если ваш package.json не согласуется с bun.lock, Bun завершится с ошибкой. Файл блокировки не будет обновлен.

bash

bun install --frozen-lockfile

Дополнительную информацию о файле блокировки Bun bun.lock см. в Менеджер пакетов > Файл блокировки.

Исключение зависимостей

Для исключения dev, peer или опциональных зависимостей используйте флаг --omit.

bash

# Исключить devDependencies из установки. Это применится к
# корневому пакету и рабочим областям, если они существуют. Транзитивные зависимости
# не будут иметь devDependencies.
bun install --omit dev

# Установить только зависимости из dependencies
bun install --omit=dev --omit=peer --omit=optional

Сухой запуск

Для выполнения сухого запуска (т.е. фактической установки ничего):

bash

bun install --dry-run

Зависимости не из npm

Bun поддерживает установку зависимостей из Git, GitHub и локальных или удаленно размещенных tarball. Полную документацию см. в Менеджер пакетов > Зависимости Git, GitHub и tarball.

json

{
  "dependencies": {
    "dayjs": "git+https://github.com/iamkun/dayjs.git",
    "lodash": "git+ssh://github.com/lodash/lodash.git#4.17.21",
    "moment": "git@github.com:moment/moment.git",
    "zod": "github:colinhacks/zod",
    "react": "https://registry.npmjs.org/react/-/react-18.2.0.tgz",
    "bun-types": "npm:@types/bun"
  }
}

Стратегии установки

Bun поддерживает две стратегии установки пакетов, которые определяют, как зависимости организуются в node_modules:

Установки с поднятием

Традиционный подход npm/Yarn, который выравнивает зависимости в общий каталог node_modules:

bash

bun install --linker hoisted

Изолированные установки

Подобный pnpm подход, который создает строгую изоляцию зависимостей для предотвращения фантомных зависимостей:

bash

bun install --linker isolated

Изолированные установки создают центральное хранилище пакетов в node_modules/.bun/ с символическими ссылками в верхнеуровневом node_modules. Это гарантирует, что пакеты могут получать доступ только к своим объявленным зависимостям.

Стратегия по умолчанию

Стратегия компоновщика по умолчанию зависит от того, начинаете ли вы с нуля или имеете существующий проект:

Новые рабочие области/монорепозитории: isolated (предотвращает фантомные зависимости)
Новые проекты с одним пакетом: hoisted (традиционное поведение npm)
Существующие проекты (созданные до v1.3.2): hoisted (сохраняет обратную совместимость)

По умолчанию управляется полем configVersion в вашем файле блокировки. Подробное объяснение см. в Менеджер пакетов > Изолированные установки.

Минимальный возраст релиза

Для защиты от атак на цепочку поставок, когда вредоносные пакеты быстро публикуются, вы можете настроить требование минимального возраста для пакетов npm. Версии пакетов, опубликованные позже указанного порога (в секундах), будут отфильтрованы во время установки.

bash

# Установить только версии пакетов, опубликованные как минимум 3 дня назад
bun add @types/bun --minimum-release-age 259200 # секунды

Вы также можете настроить это в bunfig.toml:

toml

[install]
# Установить только версии пакетов, опубликованные как минимум 3 дня назад
minimumReleaseAge = 259200 # секунды

# Исключить доверенные пакеты из проверки возраста
minimumReleaseAgeExcludes = ["@types/node", "typescript"]

Когда активен фильтр минимального возраста:

Влияет только на новое разрешение пакетов — существующие пакеты в bun.lock остаются неизменными
Все зависимости (прямые и транзитивные) фильтруются для соответствия требованию возраста при разрешении
Когда версии блокируются фильтром возраста, проверка стабильности обнаруживает шаблоны быстрых исправлений ошибок
- Если несколько версий были опубликованы близко друг к другу juste за пределами вашего фильтра возраста, он расширяет фильтр, чтобы пропустить эти потенциально нестабильные версии, и выбирает более старую, более зрелую версию
- Ищет до 7 дней после фильтра возраста, однако если все еще находит быстрые релизы, игнорирует проверку стабильности
- Запросы точных версий (как package@1.1.1) все еще соблюдают фильтр возраста, но обходят проверку стабильности
Версии без поля time считаются прошедшими проверку возраста (реестр npm должен всегда предоставлять временные метки)

Для более продвинутого сканирования безопасности, включая интеграцию с сервисами и пользовательской фильтрацией, см. Менеджер пакетов > API сканера безопасности.

Конфигурация

Конфигурация `bun install` с `bunfig.toml`

bunfig.toml ищется в следующих путях при bun install, bun remove и bun add:

$XDG_CONFIG_HOME/.bunfig.toml или $HOME/.bunfig.toml
./bunfig.toml

Если найдены оба, результаты объединяются.

Конфигурация с bunfig.toml необязательна. Bun в целом стремится быть без конфигурации, но это не всегда возможно. Поведение bun install по умолчанию можно настроить в bunfig.toml. Значения по умолчанию показаны ниже.

toml

[install]

# устанавливать ли optionalDependencies
optional = true

# устанавливать ли devDependencies
dev = true

# устанавливать ли peerDependencies
peer = true

# эквивалент флага `--production`
production = false

# эквивалент флага `--save-text-lockfile`
saveTextLockfile = false

# эквивалент флага `--frozen-lockfile`
frozenLockfile = false

# эквивалент флага `--dry-run`
dryRun = false

# эквивалент флага `--concurrent-scripts`
concurrentScripts = 16 # (количество процессоров или GOMAXPROCS) x2

# стратегия установки: "hoisted" или "isolated"
# по умолчанию зависит от configVersion файла блокировки и рабочих областей:
# - configVersion = 1: "isolated" при использовании рабочих областей, иначе "hoisted"
# - configVersion = 0: "hoisted"
linker = "hoisted"


# конфигурация минимального возраста
minimumReleaseAge = 259200 # секунды
minimumReleaseAgeExcludes = ["@types/node", "typescript"]

Конфигурация с переменными окружения

Переменные окружения имеют более высокий приоритет, чем bunfig.toml.

Имя	Описание
`BUN_CONFIG_REGISTRY`	Установить реестр npm (по умолчанию: https://registry.npmjs.org)
`BUN_CONFIG_TOKEN`	Установить токен аутентификации (в настоящее время ничего не делает)
`BUN_CONFIG_YARN_LOCKFILE`	Сохранить yarn.lock в стиле Yarn v1
`BUN_CONFIG_LINK_NATIVE_BINS`	Указать `bin` в package.json на платформо-специфичную зависимость
`BUN_CONFIG_SKIP_SAVE_LOCKFILE`	Не сохранять файл блокировки
`BUN_CONFIG_SKIP_LOAD_LOCKFILE`	Не загружать файл блокировки
`BUN_CONFIG_SKIP_INSTALL_PACKAGES`	Не устанавливать никакие пакеты

Bun всегда пытается использовать самый быстрый доступный метод установки для целевой платформы. На macOS это clonefile, а на Linux — hardlink. Вы можете изменить, какой метод установки используется, с помощью флага --backend. Когда недоступен или при ошибке, clonefile и hardlink переходят к платформо-специфичной реализации копирования файлов.

Bun хранит установленные пакеты из npm в ~/.bun/install/cache/${name}@${version}. Обратите внимание, что если версия semver имеет суффикс build или pre, он заменяется хэшем этого значения. Это уменьшает вероятность ошибок от длинных путей к файлам, но, к сожалению, усложняет определение того, где пакет был установлен на диске.

Когда папка node_modules существует, перед установкой Bun проверяет, совпадает ли "name" и "version" в package/package.json в ожидаемой папке node_modules с ожидаемыми name и version. Так он определяет, следует ли устанавливать. Он использует собственный JSON-парсер, который прекращает анализ, как только находит "name" и "version".

Когда bun.lock не существует или package.json изменил зависимости, tarball загружаются и извлекаются eagerly при разрешении.

Когда bun.lock существует и package.json не изменился, Bun загружает отсутствующие зависимости лениво. Если пакет с совпадающими name и version уже существует в ожидаемом расположении в node_modules, Bun не будет пытаться загрузить tarball.

CI/CD

Используйте официальное действие oven-sh/setup-bun для установки bun в конвейере GitHub Actions:

yaml

name: bun-types
jobs:
  build:
    name: build-app
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repo
        uses: actions/checkout@v4
      - name: Install bun
        uses: oven-sh/setup-bun@v2
      - name: Install dependencies
        run: bun install
      - name: Build app
        run: bun run build

Для сред CI/CD, которые хотят обеспечить воспроизводимые сборки, используйте bun ci, чтобы завершить сборку с ошибкой, если package.json не синхронизирован с файлом блокировки:

bash

bun ci

Это эквивалентно bun install --frozen-lockfile. Он устанавливает точные версии из bun.lock и завершается с ошибкой, если package.json не совпадает с файлом блокировки. Для использования bun ci или bun install --frozen-lockfile вы должны зафиксировать bun.lock в системе контроля версий.

И вместо запуска bun install выполните bun ci.

yaml

name: bun-types
jobs:
  build:
    name: build-app
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repo
        uses: actions/checkout@v4
      - name: Install bun
        uses: oven-sh/setup-bun@v2
      - name: Install dependencies
        run: bun ci
      - name: Build app
        run: bun run build

Платформо-специфичные зависимости?

Bun хранит нормализованные значения cpu и os из npm в файле блокировки вместе с разрешенными пакетами. Он пропускает загрузку, извлечение и установку пакетов, отключенных для текущей цели во время выполнения. Это означает, что файл блокировки не будет изменяться между платформами/архитектурами, даже если пакеты, в конечном итоге установленные, изменятся.

Флаги `--cpu` и `--os`

Вы можете переопределить целевую платформу для выбора пакетов:

bash

bun install --cpu=x64 --os=linux

Это устанавливает пакеты для указанной платформы вместо текущей системы. Полезно для кроссплатформенных сборок или при подготовке развертываний для различных сред.

Принятые значения для --cpu: arm64, x64, ia32, ppc64, s390x

Принятые значения для --os: linux, darwin, win32, freebsd, openbsd, sunos, aix

Peer-зависимости?

Peer-зависимости обрабатываются аналогично yarn. bun install автоматически установит peer-зависимости. Если зависимость помечена как опциональная в peerDependenciesMeta, существующая зависимость будет выбрана, если это возможно.

Файл блокировки

bun.lock — это формат файла блокировки Bun. См. наше сообщение в блоге о текстовом файле блокировки.

До Bun 1.2 файл блокировки был бинарным и назывался bun.lockb. Старые файлы блокировки можно обновить до нового формата, выполнив bun install --save-text-lockfile --frozen-lockfile --lockfile-only, а затем удалив bun.lockb.

Кэш

Для удаления кэша:

bash

bun pm cache rm
# или
rm -rf ~/.bun/install/cache

Платформо-специфичные бэкенды

bun install использует различные системные вызовы для установки зависимостей в зависимости от платформы. Это оптимизация производительности. Вы можете принудительно использовать конкретный бэкенд с помощью флага --backend.

hardlink — бэкенд по умолчанию в Linux. Бенчмаркинг показал, что он самый быстрый в Linux.

bash

rm -rf node_modules
bun install --backend hardlink

clonefile — бэкенд по умолчанию в macOS. Бенчмаркинг показал, что он самый быстрый в macOS. Доступен только в macOS.

bash

rm -rf node_modules
bun install --backend clonefile

clonefile_each_dir — аналогично clonefile, за исключением того, что он клонирует каждый файл индивидуально для каждого каталога. Доступен только в macOS и, как правило, работает медленнее, чем clonefile. В отличие от clonefile, он не рекурсивно клонирует подкаталоги одним системным вызовом.

bash

rm -rf node_modules
bun install --backend clonefile_each_dir

copyfile — резервный вариант, используемый, когда любой из вышеперечисленных не удается, и является самым медленным. В macOS он использует fcopyfile(), а в Linux — copy_file_range().

bash

rm -rf node_modules
bun install --backend copyfile

symlink — обычно используется только для зависимостей file: (и в будущем link:) внутри. Для предотвращения бесконечных циклов он пропускает создание символических ссылок на папку node_modules.

Если вы устанавливаете с --backend=symlink, Node.js не будет разрешать node_modules зависимостей, если у каждой зависимости нет собственной папки node_modules или вы не передадите --preserve-symlinks в node или bun. См. документацию Node.js о --preserve-symlinks.

bash

rm -rf node_modules
bun install --backend symlink
bun --preserve-symlinks ./my-file.js
node --preserve-symlinks ./my-file.js # https://nodejs.org/api/cli.html#--preserve-symlinks

Метаданные реестра npm

Bun использует бинарный формат для кэширования ответов реестра NPM. Это загружается намного быстрее, чем JSON, и обычно занимает меньше места на диске. Вы увидите эти файлы в ~/.bun/install/cache/*.npm. Шаблон имени файла — ${hash(packageName)}.npm. Это хэш, чтобы не нужно было создавать дополнительные каталоги для пакетов с областью действия.

Использование Cache-Control в Bun игнорирует Age. Это улучшает производительность, но означает, что bun может отставать примерно на 5 минут от получения последних метаданных версии пакета из npm.

Миграция с pnpm

Bun автоматически мигрирует проекты с pnpm на bun. При обнаружении файла pnpm-lock.yaml и отсутствии файла bun.lock Bun автоматически мигрирует файл блокировки в bun.lock во время установки. Исходный файл pnpm-lock.yaml остается неизменным.

bash

bun install

Примечание: Миграция выполняется только при отсутствии bun.lock. В настоящее время нет флага для отказа от миграции pnpm.

Процесс миграции обрабатывает:

Миграция файла блокировки

Преобразует pnpm-lock.yaml в формат bun.lock
Сохраняет версии пакетов и информацию о разрешении
Поддерживает отношения зависимостей и peer-зависимости
Обрабатывает патченные зависимости с хэшами целостности

Конфигурация рабочей области

Когда существует файл pnpm-workspace.yaml, Bun мигрирует настройки рабочей области в ваш корневой package.json:

yaml

packages:
  - "apps/*"
  - "packages/*"

catalog:
  react: ^18.0.0
  typescript: ^5.0.0

catalogs:
  build:
    webpack: ^5.0.0
    babel: ^7.0.0

Пакеты рабочих областей и каталоги перемещаются в поле workspaces в package.json:

json

{
  "workspaces": {
    "packages": ["apps/*", "packages/*"],
    "catalog": {
      "react": "^18.0.0",
      "typescript": "^5.0.0"
    },
    "catalogs": {
      "build": {
        "webpack": "^5.0.0",
        "babel": "^7.0.0"
      }
    }
  }
}

Зависимости каталогов

Зависимости, использующие протокол catalog: от pnpm, сохраняются:

json

{
  "dependencies": {
    "react": "catalog:",
    "webpack": "catalog:build"
  }
}

Миграция конфигурации

Следующая конфигурация pnpm мигрируется как из pnpm-lock.yaml, так и из pnpm-workspace.yaml:

Переопределения: Перемещаются из pnpm.overrides в overrides корневого уровня в package.json
Патченные зависимости: Перемещаются из pnpm.patchedDependencies в patchedDependencies корневого уровня в package.json
Переопределения рабочей области: Применяются из pnpm-workspace.yaml в корневой package.json

Требования

Требуется версия файла блокировки pnpm 7 или выше
Пакеты рабочих областей должны иметь поле name в своем package.json
Все записи каталогов, на которые ссылаются зависимости, должны существовать в определении каталогов

После миграции вы можете безопасно удалить файлы pnpm-lock.yaml и pnpm-workspace.yaml.

Основное использование ​

Для пользователей Linux ​

Логирование ​

Скрипты жизненного цикла ​

Рабочие области ​

Установка зависимостей для конкретных пакетов ​

Переопределения и разрешения ​

Глобальные пакеты ​

Режим production ​

Исключение зависимостей ​

Сухой запуск ​

Зависимости не из npm ​

Стратегии установки ​

Установки с поднятием ​

Изолированные установки ​

Стратегия по умолчанию ​

Минимальный возраст релиза ​

Конфигурация ​

Конфигурация bun install с bunfig.toml ​

Конфигурация с переменными окружения ​

CI/CD ​

Платформо-специфичные зависимости? ​

Флаги --cpu и --os ​

Peer-зависимости? ​

Файл блокировки ​

Кэш ​

Платформо-специфичные бэкенды ​

Метаданные реестра npm ​

Миграция с pnpm ​

Миграция файла блокировки ​

Конфигурация рабочей области ​

Зависимости каталогов ​

Миграция конфигурации ​

Требования ​

Основное использование

Для пользователей Linux

Логирование

Скрипты жизненного цикла

Рабочие области

Установка зависимостей для конкретных пакетов

Переопределения и разрешения

Глобальные пакеты

Режим production

Исключение зависимостей

Сухой запуск

Зависимости не из npm

Стратегии установки

Установки с поднятием

Изолированные установки

Стратегия по умолчанию

Минимальный возраст релиза

Конфигурация

Конфигурация `bun install` с `bunfig.toml`

Конфигурация с переменными окружения

CI/CD

Платформо-специфичные зависимости?

Флаги `--cpu` и `--os`

Peer-зависимости?

Файл блокировки

Кэш

Платформо-специфичные бэкенды

Метаданные реестра npm

Миграция с pnpm

Миграция файла блокировки

Конфигурация рабочей области

Зависимости каталогов

Миграция конфигурации

Требования