> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nvidia.com/ai-workbench/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/ai-workbench/_mcp/server.

# Use the preBuild.bash Script

## Overview

**The preBuild.bash script runs before packages install during the container build.**

Use it to set up the environment and prepare for package installation.
Commands run automatically when you rebuild the container.

**The script runs as the container user with passwordless sudo access.**

You can install system packages, modify permissions, and configure services.
Changes persist across container restarts because they're baked into the image.

**The build context is separate from the project.**

The script cannot access files in the */project/* directory during build.
Install from external sources like GitHub, PyPI, or URLs instead.

## Key Concepts

**preBuild.bash**

Optional bash script in the project root that runs before package installation.
Used for environment setup and system preparation.

**Build Order**

Container build follows: base image --> preBuild.bash --> package installation --> postBuild.bash --> completed image.
The `onStart.bash` script runs later, each time a container starts from that image.

**Build Context**

Separate folder containing only the containerfile, package files, and build scripts.
Does not include project files, so the script cannot access */project/* during build.

**Passwordless Sudo**

The script can run commands with sudo without password prompts.
Allows system-level changes during the build.

## Edit preBuild.bash in the Desktop App

**Step One: Open the script editor.**

1. Select **Project Tab > Project Container > Scripts**
2. Select **preBuild.bash**
3. Select **Edit Script**

**Step Two: Add your commands to the script.**

1. Type or paste your bash commands in the editor
2. Select **Save**

**Step Three: Rebuild the container to apply changes.**

1. Select **Project Tab > Project Container > Start Build**

**Success: The container rebuilds with your script changes applied.**

## Edit preBuild.bash Directly

**Step One: Open the script file in your project root.**

1. Open *preBuild.bash* in any text editor

**Step Two: Add your commands to the script.**

1. Write bash commands in the file
2. Save the file

**Step Three: Rebuild the container.**

1. Select **Project Tab > Project Container > Start Build**

**Success: The container rebuilds with your script changes applied.**

## What preBuild.bash Can and Cannot Access

**The script CANNOT access the following.**

- Files in the project (anything in */project/*)
- Environment variables defined in *variables.env*
- Data files or models in your project

**The script CAN access the following.**

- System package managers (apt, yum, etc.)
- Python package managers (pip, conda)
- External resources (GitHub, PyPI, URLs with curl/wget)
- System directories and files being created during the build
- Build-time environment variables you set in the script itself

### Common Mistakes to Avoid

**Don't try to copy files from /project/**

This will fail because */project/* doesn't exist during build:

```bash
# This FAILS
cp /project/my-config.yaml /opt/app/
```

**Don't try to pip install from local project files**

This will fail because the files aren't in the build context:

```bash
# This FAILS
pip install /project/my-package/
```

**Don't reference environment variables from variables.env**

These aren't set during the build:

```bash
# This FAILS
echo $MY_CUSTOM_VAR  # Variable from variables.env
```

### Workarounds

**Install from external sources instead**

Download from GitHub or other external locations:

```bash
# Install a Python package from GitHub
pip install git+https://github.com/user/repo.git
```

**Set build-time variables in the script**

Define variables you need in the build script itself:

```bash
# Set a variable for use in this script
export MY_BUILD_VAR="value"
echo $MY_BUILD_VAR
```

## Use Cases for preBuild.bash

**Add apt repositories or signing keys before packages install.**

> ```bash
> #!/bin/bash
> # Add a custom apt repository
> sudo add-apt-repository ppa:example/repo
> sudo apt-get update
> ```

**Create directories that will be needed later.**

> ```bash
> #!/bin/bash
> # Create directories for data and models
> sudo mkdir -p /opt/data /opt/models
> sudo chown workbench:workbench /opt/data /opt/models
> ```

**Install tools needed for compiling packages.**

> ```bash
> #!/bin/bash
> # Install build essentials
> sudo apt-get update
> sudo apt-get install -y build-essential cmake
> ```

**Configure custom package sources or mirrors.**

> ```bash
> #!/bin/bash
> # Add custom pip index
> mkdir -p /home/workbench/.pip
> echo "[global]" > /home/workbench/.pip/pip.conf
> echo "index-url = https://internal-pypi.company.com/simple" >> /home/workbench/.pip/pip.conf
> ```

**Fix base image issues before package installation.**

> ```bash
> #!/bin/bash
> # Fix locale settings
> sudo locale-gen en_US.UTF-8
> sudo update-locale LANG=en_US.UTF-8
> ```

## Best Practices

**Use set -e for error handling**

Exit immediately if any command fails:

```bash
#!/bin/bash
set -e
```

**Add comments to explain complex operations**

Document what your script does:

```bash
# Add custom repository for latest Python build tools
# Required for building machine learning packages
```

**Use absolute paths for file operations**

Avoid issues with working directories:

```bash
sudo mkdir -p /opt/myapp
# Not: mkdir -p myapp
```

**Test scripts in isolation when possible**

Run commands manually in a container to verify they work before adding to scripts.

## Related Topics

- [Use the postBuild.bash Script](/ai-workbench/how-to/environments/postbuild-script) - Configure the container after package installation
- [Use the onStart.bash Script](/ai-workbench/how-to/environments/onstart-script) - Initialize the running container at each start
- [Package Management](/ai-workbench/how-to/environments/package-management) - Add packages to your container
- [Configure Runtime Settings](/ai-workbench/how-to/environments/runtime-configuration) - Set environment variables and mounts
- [Use a Custom Container](/ai-workbench/how-to/use-custom-container) - Use your own base image