Skip to main content

​
Overview

Bench recognizes several environment variables that modify its behavior. These variables can be used to customize bench operations, enable development features, or configure specific behaviors in CI/CD environments.

​
Development Variables

​
BENCH_DEVELOPER

Purpose: Suppress editable install warnings during development. Type: Boolean (any non-empty value) Default: Not set Usage: 
export BENCH_DEVELOPER=1
When bench is installed in editable mode (for development), it shows a warning: 
WARN: bench is installed in editable mode!

This is not the recommended mode of installation for production.
Instead, install the package from PyPI with: `pip install frappe-bench`
Setting BENCH_DEVELOPER=1 suppresses this warning. Location: bench/cli.py:72 Example: 
# Temporary for single session
export BENCH_DEVELOPER=1
bench update

# Permanent (add to ~/.bashrc or ~/.zshrc)
echo 'export BENCH_DEVELOPER=1' >> ~/.bashrc
Only use this variable during bench development. For production installations, always install bench from PyPI.

​
DEV_SERVER

Purpose: Indicates development server is running. Type: String Set by: Bench internally when running bench start Location: bench/utils/system.py:156 This variable is set automatically by bench and shouldn’t be set manually.

​
BENCH_VERBOSE

Purpose: Enable verbose logging output. Type: Boolean Default: Not set Usage: 
export BENCH_VERBOSE=1
bench update
Alternatively, use the -v or --verbose flag: 
bench -v update

​
Build and Installation Variables

​
FRAPPE_DOCKER_BUILD

Purpose: Indicates bench is being built/run in a Docker container. Type: Boolean (any non-empty value) Default: Not set Usage: 
export FRAPPE_DOCKER_BUILD=1
When set, bench:
  • Skips certain host-specific configurations
  • Modifies dependency installation behavior
  • Adjusts process management settings
Locations:
  • bench/utils/__init__.py:144
  • bench/utils/bench.py:260
  • bench/utils/bench.py:322
  • bench/bench.py:369
This variable is primarily used by the official Frappe Docker repository and should not be set manually unless you’re building a custom Docker image.

​
PIP_VERSION

Purpose: Specify pip version to install in virtual environment. Type: String (version number) Default: Latest pip version Usage: 
export PIP_VERSION=23.0.1
bench init frappe-bench
Location: bench/bench.py:428

​
BENCH_DISABLE_UV

Purpose: Disable UV package manager and use pip instead. Type: Boolean (“true”, “1”, “yes” to disable) Default: Not set (UV is used if available) Usage: 
export BENCH_DISABLE_UV=1
bench setup requirements
Location: bench/utils/__init__.py:45 Bench can use UV, a fast Python package installer. Set this variable to force using pip instead.

​
CI/CD Variables

​
CI

Purpose: Indicates code is running in a Continuous Integration environment. Type: Boolean (any non-empty value) Default: Not set Usage: 
export CI=1
When set, bench:
  • Suppresses editable install warnings (like BENCH_DEVELOPER)
  • Skips file watching in Procfile generation
  • May skip interactive prompts
  • Modifies test behavior
Locations:
  • bench/cli.py:72
  • bench/config/procfile.py:14
  • bench/tests/test_base.py:35
  • bench/tests/test_base.py:96
  • bench/tests/test_setup_production.py:77
Common CI Systems (set automatically):
  • GitHub Actions
  • GitLab CI
  • Jenkins
  • Travis CI
  • CircleCI

​
PYTHONUNBUFFERED

Purpose: Disable Python output buffering. Type: String (“true”) Set by: Bench internally Usage: Set automatically by bench during execution Location: bench/utils/system.py:154 This ensures Python output appears immediately in logs rather than being buffered.

​
Production Variables

​
NO_SERVICE_RESTART

Purpose: Prevent automatic service restarts in production. Type: Boolean (any non-empty value) Default: Not set Usage: 
export NO_SERVICE_RESTART=1
bench setup production
Location: bench/config/production_setup.py:84 Useful when you want to manually control service restarts during production setup or updates.

​
BENCH_SERVICE_MANAGER

Purpose: Specify custom service manager. Type: String (service manager name) Default: Auto-detected (supervisor or systemd) Usage: 
export BENCH_SERVICE_MANAGER=supervisor
bench restart
Location: bench/config/production_setup.py:124 Valid values:
  • supervisor
  • systemd

​
BENCH_SERVICE_MANAGER_COMMAND

Purpose: Specify custom service manager command. Type: String (command path) Default: Standard commands for detected service manager Usage: 
export BENCH_SERVICE_MANAGER_COMMAND=/usr/local/bin/supervisorctl
bench restart
Location: bench/config/production_setup.py:127

​
System Variables

​
HOME

Purpose: User home directory. Type: String (directory path) Default: System-provided Modified by: Bench when switching to frappe user Location: bench/cli.py:186 Bench may modify this when changing to the frappe user in production setups.

​
Usage Examples

​
Development Setup

Typical environment variables for development: 
# ~/.bashrc or ~/.zshrc
export BENCH_DEVELOPER=1

​
CI/CD Pipeline

Typical environment variables for CI/CD: 
# .github/workflows/test.yml
env:
  CI: 1
  BENCH_DISABLE_UV: 1  # If UV causes issues

​
Docker Build

Typical environment variables for Docker: 
# Dockerfile
ENV FRAPPE_DOCKER_BUILD=1
ENV PYTHONUNBUFFERED=1

​
Production Deployment

Typical environment variables for production: 
# During setup
export NO_SERVICE_RESTART=1
bench setup production frappe

# Force specific service manager
export BENCH_SERVICE_MANAGER=systemd
bench restart --systemd

​
Setting Environment Variables

​
Temporary (Current Session)

export VARIABLE_NAME=value
bench command

​
Permanent (User Profile)

Add to ~/.bashrc, ~/.zshrc, or ~/.profile: 
echo 'export VARIABLE_NAME=value' >> ~/.bashrc
source ~/.bashrc

​
One-Time Use

VARIABLE_NAME=value bench command

​
System-Wide (All Users)

Add to /etc/environment (requires sudo): 
sudo echo 'VARIABLE_NAME=value' >> /etc/environment

​
Checking Environment Variables

​
View All Environment Variables

env | grep BENCH

​
View Specific Variable

echo $BENCH_DEVELOPER

​
Check if Variable is Set

if [ -n "$BENCH_DEVELOPER" ]; then
    echo "BENCH_DEVELOPER is set"
fi

​
Best Practices

Use different environment variables for development and production:Development:
  • Set BENCH_DEVELOPER=1
  • Enable verbose logging
Production:
  • Don’t set BENCH_DEVELOPER
  • Use NO_SERVICE_RESTART for controlled deployments
If you use custom environment variables in your deployment scripts, document them clearly:
# Custom variables for our deployment
export CUSTOM_DB_HOST=db.example.com
export CUSTOM_REDIS_HOST=redis.example.com
Never commit sensitive values to version control:
# .env (add to .gitignore)
DB_PASSWORD=secret123
API_KEY=abc123def456
Use tools like:
  • Environment-specific config files
  • Secret management systems
  • Docker secrets
Ensure CI environment matches production:
# .github/workflows/deploy.yml
env:
  CI: 1
  BENCH_SERVICE_MANAGER: systemd

​
Troubleshooting

​
Variable Not Taking Effect

  1. Check if variable is set: 
    echo $VARIABLE_NAME
  2. Reload shell configuration: 
    source ~/.bashrc
  3. Check for typos in variable name
  4. Verify variable is exported: 
    export VARIABLE_NAME=value

​
Conflicts Between Variables

Some variables may conflict. For example:
  • BENCH_DEVELOPER=1 and production setup
  • BENCH_DISABLE_UV=1 with caching enabled
When troubleshooting, try: 
# Clear all bench-related variables
unset BENCH_DEVELOPER
unset CI
unset FRAPPE_DOCKER_BUILD

Configuration Files

Learn about bench configuration files

Contributing

Development environment setup

Production Setup

Production deployment guide

Architecture

How bench works internally

Build docs developers (and LLMs) love

Get started for freeTalk to us