bunenv - Bun Virtual Environment

Create isolated Bun environments, similar to Python's virtualenv. Inspired by and adapted from nodeenv.

[!NOTE] Docs were autogenerated with a docs agent, so don't expect much :) Or maybe expect too much..?

Why bunenv?

• Isolated Bun installations - Keep different Bun versions per project
• No global pollution - Install packages without affecting system Bun
• Easy version management - Switch between Bun versions effortlessly
• Python integration - Works alongside Python virtual environments
• Cross-platform - Supports macOS, Linux, and Windows

Installation

Using uv (Recommended)

uv tool install bunenv

Using pip

pip install bunenv

From source

git clone https://github.com/JacobCoffee/bunenv.git
cd bunenv
uv pip install -e .

Quick Start

Create a Bun environment

# Create environment with latest Bun
bunenv myenv

# Create with specific version
bunenv myenv --bun=1.3.3

# List available Bun versions
bunenv --list

Activate the environment

# On macOS/Linux
source myenv/bin/activate

# On Windows
myenv\Scripts\activate.bat

Use Bun

bun --version          # Check version
bun init               # Initialize a project
bun add express        # Install packages
bun run index.ts       # Run scripts

Deactivate

deactivate_bun

Usage Examples

Development Workflow

# Create project environment
bunenv .venv --bun=latest

# Activate
source .venv/bin/activate

# Your project is now using isolated Bun
bun install
bun run dev

Multiple Projects, Different Versions

# Legacy project with Bun 1.0
bunenv ~/projects/legacy/.bunenv --bun=1.0.0
cd ~/projects/legacy
source .bunenv/bin/activate

# New project with latest Bun
bunenv ~/projects/new/.bunenv --bun=latest
cd ~/projects/new
source .bunenv/bin/activate

CI/CD Integration

GitHub Actions (Recommended)

Use the official bunenv GitHub Action for the simplest setup:

# Use the bunenv action (easiest!)
- name: Setup Bun
  uses: JacobCoffee/bunenv@v1
  with:
    bun-version: '1.3.3'

- name: Build and test
  run: |
    bun install
    bun test

See ACTION.md for complete documentation and advanced usage.

Manual Setup

# Manual installation
- name: Setup Bun environment
  run: |
    pip install bunenv
    bunenv .bunenv --bun=1.3.3
    source .bunenv/bin/activate
    bun install
    bun test

Python + Bun Projects

# Create Python virtualenv
python -m venv .venv
source .venv/bin/activate

# Install bunenv in the virtualenv
pip install bunenv

# Create Bun environment inside Python virtualenv
bunenv --python-virtualenv --bun=latest

# Now you have both Python and Bun isolated!
python --version
bun --version

Command-Line Options

Basic Options

bunenv [OPTIONS] DEST_DIR

Bun Version Options

Installation Options

Integration Options

Customization Options

Configuration File

Create ~/.bunenvrc to set defaults:

[bunenv]
bun = latest
variant =
github_token = ghp_xxxxxxxxxxxxx
ignore_ssl_certs = False

You can also use .bun-version file in your project:

echo "1.3.3" > .bun-version
bunenv .venv  # Will use version from .bun-version

Requirements File

Create a requirements.txt with packages to install:

# requirements.txt
express
typescript
@types/node

Install with:

bunenv myenv --requirements=requirements.txt

Platform Support

Supported Platforms

• macOS: Intel (x64) and Apple Silicon (aarch64)
• Linux: x64, aarch64, with glibc or musl (Alpine, Void)
• Windows: x64

Variants

# Auto-detect best variant
bunenv myenv

# Force baseline for old CPU
bunenv myenv --variant=baseline

# Use musl on Alpine Linux (auto-detected)
bunenv myenv  # Will use musl variant automatically

Environment Variables

When activated, bunenv sets:

• BUN_VIRTUAL_ENV - Path to the environment
• BUN_INSTALL - Bun install directory
• BUN_INSTALL_BIN - Binary installation directory
• PATH - Prepended with environment's bin directory

Comparison with Other Tools

Real-World Example: Byte Bot

The Byte Bot project uses Bun for frontend tooling (TailwindCSS, Biome linter) alongside Python (uv). With bunenv:

# Setup isolated environment
bunenv .bunenv --bun=latest
source .bunenv/bin/activate

# Frontend development
bun install
bun run format    # Biome formatting
bun run lint      # Biome linting

Troubleshooting

GitHub API Rate Limits

If you see rate limit errors:

# Create a GitHub token (read-only, public repos)
# https://github.com/settings/tokens

# Use with bunenv
bunenv myenv --github-token=ghp_xxxxx

# Or set in ~/.bunenvrc
echo "github_token = ghp_xxxxx" >> ~/.bunenvrc

Architecture Detection

On ARM systems:

# Bunenv auto-detects and uses aarch64 binaries
bunenv myenv  # Uses bun-darwin-aarch64 or bun-linux-aarch64

# Fallback to x64 if needed (Rosetta on macOS)
bunenv myenv --variant=baseline

Alpine Linux / musl

# Auto-detected on Alpine/Void Linux
bunenv myenv  # Automatically uses bun-linux-x64-musl

# Force musl variant
bunenv myenv --variant=musl

Development

Running Tests

# Clone repository
git clone https://github.com/JacobCoffee/bunenv.git
cd bunenv

# Install development dependencies
uv sync

# Run tests
uv run pytest

# Run linter
uv run ruff check

Building Documentation

# Install docs dependencies
uv sync --group docs

# Build docs
cd docs
uv run make html

Differences from nodeenv

Bunenv is adapted from the excellent nodeenv project. Key differences:

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

See CONTRIBUTING.md for details.

License

BSD-3-Clause License. See LICENSE for details.

Based on nodeenv by Eugene Kalinin.

Acknowledgments

• Eugene Kalinin - Original nodeenv author
• Oven.sh - Bun runtime creators
• All contributors to nodeenv and bunenv

Links

• GitHub: https://github.com/JacobCoffee/bunenv
• PyPI: https://pypi.org/project/bunenv/
• Documentation: https://bunenv.readthedocs.io/
• Bun: https://bun.sh
• nodeenv: https://github.com/ekalinin/nodeenv