User Guides

Welcome to the bunenv user guides! This section provides comprehensive documentation organized by learning style.

Note

New to bunenv? Start with the Quick Start Tutorial tutorial to get your first environment running in 5 minutes.

Getting Started

The quickstart tutorial walks you through creating your first Bun environment step-by-step. Perfect for first-time users who want to see bunenv in action.

How-To Guides

Task-oriented guides for specific goals:

Common Workflows

Real-world usage patterns including CI/CD, Python integration, monorepos, and platform-specific scenarios. Copy-paste ready examples for common tasks.

Configuration Guide

Complete reference for configuration files (.bunenvrc, setup.cfg), environment variables, and command-line options. Learn to customize bunenv for your needs.

Advanced Topics

Advanced Topics

Deep dives into binary variants, GitHub API integration, custom activation scripts, offline installations, security considerations, and edge cases.

Troubleshooting

Solutions to common problems, error messages explained, platform-specific issues, and diagnostic techniques. Your first stop when things don’t work.

Contributing

Contributing to bunenv

Development setup, coding guidelines, testing, documentation, and the pull request process. Everything you need to contribute to bunenv.

Additional Resources

Comparison with Other Tools

How bunenv compares to nodeenv, asdf, mise, and other version managers. Understand bunenv’s unique value proposition.

Migrating to bunenv

Migrate from nodeenv, system Bun, or Docker-based workflows to bunenv. Step-by-step migration guides with examples.

Quick Reference

Common Commands

# Create environment
bunenv myenv                          # Latest Bun
bunenv myenv --bun=1.3.3             # Specific version
bunenv myenv --variant=baseline      # Older CPU support

# List available versions
bunenv --list

# Activate
source myenv/bin/activate             # macOS/Linux
myenv\Scripts\activate.bat            # Windows cmd
myenv\Scripts\Activate.ps1            # Windows PowerShell

# Use Bun
bun --version
bun init
bun install

# Deactivate
deactivate_bun

Configuration Files

User defaults (~/.bunenvrc):

[bunenv]
bun = latest
github_token = ghp_your_token_here

Project version (.bun-version):

1.3.3

Project config (setup.cfg or tox.ini):

[bunenv]
bun = 1.3.3
variant = baseline

Environment Variables

When activated, bunenv sets:

  • BUN_VIRTUAL_ENV - Environment path

  • BUN_INSTALL - Bun installation directory

  • BUN_INSTALL_BIN - Binary directory

  • PATH - Prepended with bin directory

Documentation Organization

This documentation follows the Diátaxis framework:

Tutorials (Learning-oriented)

Step-by-step lessons for newcomers. Start here if you’re new to bunenv.

How-To Guides (Task-oriented)

Recipes for specific goals. Use these when you know what you want to achieve.

Reference (Information-oriented)

Technical descriptions of bunenv’s machinery. Use for looking up specific details.

Explanation (Understanding-oriented)

Background and context. Use to deepen your understanding of concepts.

Finding What You Need

I want to…

…get started quickly

→ Quick Start Tutorial

…set up CI/CD

→ Common Workflows → CI/CD Integration

…fix an error

→ Troubleshooting

…use with Python

→ Common Workflows → Python Integration

…understand all options

→ Configuration Guide

…contribute code

→ Contributing to bunenv

…compare with other tools

→ Comparison with Other Tools

I’m wondering…

…how bunenv works internally

→ Advanced Topics → Understanding the Activation Mechanism

…which variant I need

→ Advanced Topics → Binary Variants Deep Dive

…how to migrate from X

→ Migrating to bunenv

…why my environment isn’t activating

→ Troubleshooting → Activation Issues

Need More Help?

Can’t find what you’re looking for?

📖 Use the search box at the top of this page

🐛 Report issues: GitHub Issues

💬 Ask questions: GitHub Discussions

📚 API Reference: API Reference for technical details

🔧 CLI Reference: Command-Line Interface for all command-line options

External Resources