> ## Documentation Index
> Fetch the complete documentation index at: https://www.jetify.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# devbox.json Reference

> Your devbox configuration is stored in a `devbox.json` file, located in your project's root directory. This file can be edited directly, or using the [devbox CLI](/docs/devbox/cli-reference/devbox/).

```json theme={null}
{
  "packages": [] | {},
  "env": {},
  "shell": {
    "init_hook": "...",
    "scripts": {}
  },
  "include": []
}
```

### Packages[​](#packages "Direct link to Packages")

This is a list or map of Nix packages that should be installed in your Devbox shell and containers.
These packages will only be installed and available within your shell, and will have precedence over
any packages installed in your local machine. You can search for Nix packages using
[Nix Package Search](https://search.nixos.org/packages).

You can add packages to your devbox.json using `devbox add <package_name>`, and remove them using
`devbox rm <package_name>`.

Packages can be structured as a list of package names (`<packages>@<version>`) or
[flake references](#adding-packages-from-flakes):

```json theme={null}
{
  "packages": ["go@latest", "golangci-lint@latest"]
}
```

If you need to provide more options to your packages (such as limiting which platforms will install
the package), you can structure packages as a map, where each package follows the schema below:

```json theme={null}
{
  "packages": {
    // If only a version is specified, you can abbreviate as:
    // "package_name": "version"
    "package_name": string,
    "package_name": {
      // Version of the package to install. Defaults to "latest"
      "version": string,
      // Whether native library patching is enabled for this package.
      // Defaults to `auto`, can be `always` or `never`
      "patch": ["auto" | "always" | "never"],
      // List of platforms to install the package on.
      // Defaults to all platforms
      "platforms": [string],
      // List of platforms to exclude this package from.
      // Defaults to no excluded platforms
      "excluded_platforms": [string],
      // Whether to disable a built-in plugin, if one exists.
      // Defaults to false
      "disable_plugin": boolean
    }
  }
}
```

For example:

```json theme={null}
{
  "packages": {
    "go": "latest",
    "golangci-lint": "latest",
    "glibcLocales": {
      "version": "latest",
      "platforms": ["x86_64-linux, aarch64-linux"]
    }
  }
}
```

Note that `devbox add` will automatically format `packages` based on the options and packages that
you provide.

#### Pinning a Specific Version of a Package[​](#pinning-a-specific-version-of-a-package "Direct link to Pinning a Specific Version of a Package")

You can pin a specific version of a package by adding a `@` followed by the version number to the
end of the package name. For example, to pin the `go` package to version `1.19`, you can run
`devbox add go@1.19`, or add `go@1.19` to the packages list in your `devbox.json`:

```json theme={null}
{
  "packages": ["go@1.19"]
}
```

Where possible, pinned packages follow semver. For example, if you pin `python@3`, it will install
the latest version of `python` with major version `3`.

To see a list of packages and their available versions, you can run `devbox search <pkg>`.

#### Adding Packages from Flakes[​](#adding-packages-from-flakes "Direct link to Adding Packages from Flakes")

You can add packages from flakes by adding a reference to the flake in the `packages` list in your
`devbox.json`. We currently support installing Flakes from Github and local paths.

```json theme={null}
{
  "packages": [
    // Add the default package from a github repository
    "github:numtide/flake-utils",
    // Install a specific attribute or package from a Github flake
    "github:nix-community/fenix#stable.toolchain",
    // Install a package from a specific channel of Nixpkgs
    "github:nixos/nixpkgs/21.05#hello",
    // Install a package from a specific commit of Nixpkgs
    "github:nixos/nixpkgs/5233fd2ba76a3accb5aaa999c00509a11fd0793c#hello",
    // Install a package from a local flake.
    // This should point to a directory with a flake.nix file.
    "path:../my-flake#my-package"
  ]
}
```

To learn more about using flakes, see the [Using Flakes](/docs/devbox/guides/using-flakes/) guide.

#### Adding Platform Specific Packages[​](#adding-platform-specific-packages "Direct link to Adding Platform Specific Packages")

You can choose to include or exclude your packages on specific platforms by adding a `platforms` or
`excluded_platforms` field to your package definition. This is useful if you need to install
packages or libraries that are only available on specific platforms (such as `busybox` on Linux, or
`utm` on macOS):

```json theme={null}
{
  "packages": {
    // Only install busybox on linux
    "busybox": {
      "version": "latest",
      "platforms": ["x86_64-linux", "aarch64-linux"]
    },
    // Exclude UTM on Linux
    "utm": {
      "version": "latest",
      "excluded_platforms": ["x86_64-linux", "aarch64-linux"]
    }
  }
}
```

Note that a package can only specify one of `platforms` or `excluded_platforms`.

Valid Platforms include:

* `aarch64-darwin`
* `aarch64-linux`
* `x86_64-darwin`
* `x86_64-linux`

The platforms below are also supported, but require you to build packages from source:

* `i686-linux`
* `armv7l-linux`

#### Disabling Built-in Plugins[​](#disabling-built-in-plugins "Direct link to Disabling Built-in Plugins")

Some packages include builtin plugins or services that are automatically started when the package is
installed. You can disable these plugins using `devbox add <package> --disable-plugin`, or by
setting the `disable_plugin` field to `true` in your package definition:

```json theme={null}
{
  "packages": {
    "glibcLocales": {
      "version": "latest",
      "disable_plugin": true
    }
  }
}
```

### Env[​](#env "Direct link to Env")

This is a a map of key-value pairs that should be set as Environment Variables when activating
`devbox shell`, running a script with `devbox run`, or starting a service. These variables will only
be set in your Devbox shell, and will have precedence over any environment variables set in your
local machine or by [Devbox Plugins](/docs/devbox/guides/plugins/).

For example, you could set variable `$FOO` to `bar` by adding the following to your `devbox.json`:

```json theme={null}
{
  "env": {
    "FOO": "bar"
  }
}
```

Currently, you can only set values using string literals, `$PWD`, and `$PATH`. Any other values with
environment variables will not be expanded when starting your shell.

### Env From[​](#env-from "Direct link to Env From")

Env from takes a string for loading environment variables into your shells and scripts. Currently it
supports loading from two sources: .env files, and Jetify Secrets.

#### .env Files[​](#env-files "Direct link to .env Files")

You can load environment variables from a `.env` file by adding the path to the file in the
`env_from` field (the file must end with `.env`). This is useful for loading secrets or other
sensitive information that you don't want to store in your `devbox.json`.

```json theme={null}
{
  "env_from": "path/to/.env"
}
```

This will load the environment variables from the `.env` file into your shell when you run
`devbox shell` or `devbox run`. Note that environment variables set in the `.env` file will be
overridden if the same variable is set directly in your `devbox.json`

#### Jetify Secrets[​](#jetify-secrets "Direct link to Jetify Secrets")

You can securely load secrets from Jetify Secrets by running `devbox secrets init` and creating a
project in Jetify Cloud. This will add the `jetify-cloud` field to `env_from` in your project.

```json theme={null}
{
  "env_from": "jetify-cloud"
}
```

Note that setting secrets securely with Jetify Secrets requires a Jetify Cloud account. For more
information, see the [Jetify Secrets](/docs/cloud/secrets/) guide.

### Shell[​](#shell "Direct link to Shell")

The Shell object defines init hooks and scripts that can be run with your shell. Right now two
fields are supported: `init_hook`, which run a set of commands every time you start a devbox shell,
and `scripts`, which are commands that can be run using `devbox run`

#### Init Hook[​](#init-hook "Direct link to Init Hook")

The init hook is used to run shell commands before the shell finishes setting up. This hook runs
after any other `~/.*rc` scripts, allowing you to override environment variables or further
customize the shell.

The init hook will run every time a new shell is started using `devbox shell` or `devbox run`, and
is best used for setting up environment variables, aliases, or other quick setup steps needed to
configure your environment. For longer running tasks, you should consider using a Script.

This is an example `devbox.json` that customizes the prompt and prints a welcome message:

```json theme={null}
{
  "shell": {
    "init_hook": [
      "export PS1='📦 devbox> '",
      "echo 'Welcome! See CONTRIBUTING.md for tips on contributing to devbox.'"
    ]
  }
}
```

When run, you'll see:

```
> devbox shell
Installing nix packages. This may take a while...
Starting a devbox shell...
Welcome! See CONTRIBUTING.md for tips on contributing to devbox.
📦 devbox>
```

#### Scripts[​](#scripts "Direct link to Scripts")

Scripts are commands that are executed in your Devbox shell using `devbox run <script_name>`. They
can be used to start up background process (like databases or servers), or to run one off commands
(like setting up a dev DB, or running your tests).

Scripts can be defined by giving a name, and one or more commands. Single command scripts can be
added by providing a name, and a string:

```json theme={null}
{
  "shell": {
    "scripts": {
      "print_once": "echo \"Hello Once!\""
    }
  }
}
```

To run multiple commands in a single script, you can pass them as an array:

```json theme={null}
{
  "shell": {
    "scripts": {
      "print_twice": ["echo \"Hello Once!\"", "echo \"Hello Twice!\""]
    }
  }
}
```

### Include[​](#include "Direct link to Include")

Includes can be used to explicitly add extra configuration from
[plugins](/docs/devbox/guides/plugins/) to your Devbox project. Plugins are parsed and merged in the
order they are listed.

Note that in the event of a conflict, plugins near the end of the list will override plugins at the
beginning of the list. Likewise, if a setting in your project config conflicts with a plugin (e.g.,
your `devbox.json` has a script with the same name as a plugin script), your project config will
take precedence.

```json theme={null}
{
    "include": [
        // Include a plugin from a Github Repo. The repo must have a plugin.json in it's root,
        // or in the directory specified by ?dir
        "github:org/repo/ref?dir=<path-to-plugin>"
        // Include a local plugin. The path must point to a plugin.json
        "path:path/to/plugin.json"
        // Force activate a builtin plugin
        "plugin:php-config"
    ]
}
```

### Example: A Rust Devbox[​](#example-a-rust-devbox "Direct link to Example: A Rust Devbox")

An example of a devbox configuration for a Rust project called `hello_world` might look like the
following:

```json theme={null}
{
  "packages": ["rustup@latest", "libiconv@latest"],
  "env": {
    "PROJECT_DIR": "$PWD"
  },
  "shell": {
    "init_hook": [". conf/set-env.sh", "rustup default stable", "cargo fetch"],
    "scripts": {
      "build-docs": "cargo doc",
      "start": "cargo run",
      "run_test": ["cargo test -- --show-output"]
    }
  }
}
```

[Edit this page](https://github.com/jetify-com/docs/tree/main/docs/devbox/configuration/index.mdx)