Quick Start Tutorial¶

Welcome! In the next 5 minutes, you’ll create your first isolated Bun environment and understand how bunenv keeps your projects organized.

What You’ll Learn¶

By the end of this tutorial, you’ll know how to:

Install bunenv
Create a Bun environment
Activate and use the environment
Install packages in isolation
Deactivate when you’re done

Prerequisites¶

Just two things:

Python 3.10+ (check with python --version)

No Bun installation needed - bunenv handles that for you!

Step 1: Install bunenv¶

Choose your preferred method:

pip install bunenv

Standard installation using pip.

uv tool install bunenv

Faster installation using uv.

pipx install bunenv

Completely isolated bunenv installation.

Verify Installation¶

Check that bunenv is installed:

bunenv --version

You should see something like 0.1.0.

Tip

If you get “command not found”, make sure your Python scripts directory is in your PATH. Try python -m bunenv --version as an alternative.

Step 2: Create Your First Environment¶

Let’s create a Bun environment for a new project:

bunenv my-first-env

You’ll see output like this:

* Install prebuilt Bun (1.3.3) ........ done.
* Creating: my-first-env/bin ... done.

What Just Happened?¶

bunenv just:

Fetched the latest Bun version from GitHub Releases
Downloaded the appropriate binary for your platform
Created a directory structure at my-first-env/
Installed activation scripts

Let’s peek at what was created:

ls -la my-first-env/

You’ll see:

my-first-env/
├── bin/                  # Bun binary and activation scripts
│   ├── bun              # The Bun executable
│   ├── activate         # Bash/zsh activation
│   ├── activate.fish    # Fish shell activation
│   └── shim            # System bun compatibility
└── src/                 # Downloaded files (optional cleanup)

Step 3: Activate the Environment¶

Time to activate! The command varies by platform:

# bash/zsh
source my-first-env/bin/activate

Or for fish shell:

# fish
source my-first-env/bin/activate.fish

# PowerShell
my-first-env\Scripts\Activate.ps1

Or for cmd.exe:

REM cmd.exe
my-first-env\Scripts\activate.bat

What Changed?¶

After activation, notice:

Your prompt changed: You’ll see (my-first-env) at the start
``bun`` is now available: It’s the isolated version, not system Bun
Environment variables are set: BUN_VIRTUAL_ENV, BUN_INSTALL, etc.

Verify it worked:

(my-first-env) $ bun --version
1.3.3

(my-first-env) $ which bun  # macOS/Linux
/path/to/my-first-env/bin/bun

Note

The (my-first-env) prefix shows you’re in an activated environment. This is your visual reminder that you’re working in isolation!

Step 4: Use Bun¶

Now let’s actually use Bun to build something. We’ll create a simple project:

Initialize a Project¶

(my-first-env) $ bun init

Bun will ask you some questions. Just press Enter to accept defaults:

bun init helps you get started with a minimal project and tries to
guess sensible defaults. Press ^C anytime to quit

package name (my-first-env):
entry point (index.ts):

Done! A package.json file was saved in the current directory.

Install a Package¶

Let’s install Express, a popular web framework:

(my-first-env) $ bun add express

You’ll see:

bun add v1.3.3
[0.51ms] installed express@4.18.2

The package is installed in node_modules/ within your project - not globally!

Create a Simple Server¶

Create a file called server.js:

// server.js
import express from 'express';

const app = express();
const port = 3000;

app.get('/', (req, res) => {
  res.send('Hello from my isolated Bun environment!');
});

app.listen(port, () => {
  console.log(`Server running at http://localhost:${port}`);
});

Run Your Server¶

(my-first-env) $ bun run server.js

Open http://localhost:3000 in your browser. You’ll see:

Hello from my isolated Bun environment!

Congratulations! You just ran a web server using your isolated Bun installation.

Press Ctrl+C to stop the server.

Step 5: Deactivate¶

When you’re done working, deactivate the environment:

(my-first-env) $ deactivate_bun

Notice:

The (my-first-env) prompt prefix disappears
bun command now points back to your system Bun (if installed)
Environment variables are restored

Test it:

$ bun --version  # Will error if you don't have system Bun

The isolated Bun is gone from your PATH. Your system is back to normal!

Important

Deactivating doesn’t delete the environment - it just stops using it. You can re-activate anytime with source my-first-env/bin/activate.

What You’ve Learned¶

In just 5 minutes, you:

✓ Installed bunenv

✓ Created an isolated Bun environment

✓ Activated and used it

✓ Installed packages that only exist in that environment

✓ Ran a real application

✓ Deactivated to return to normal

Try It Yourself: Different Versions¶

Here’s where it gets powerful. Create a second environment with a different Bun version:

# Create environment with Bun 1.0.0
bunenv old-project --bun=1.0.0

# Activate it
source old-project/bin/activate

# Check version
(old-project) $ bun --version
1.0.0

# Deactivate
(old-project) $ deactivate_bun

# Now activate the first environment
source my-first-env/bin/activate

# Check version
(my-first-env) $ bun --version
1.3.3

See? Different projects, different Bun versions, zero conflicts.

Real-World Workflow Example¶

Here’s how you’d use bunenv in a typical project:

# Clone a project
git clone https://github.com/username/my-bun-app.git
cd my-bun-app

# Create Bun environment (specific version)
bunenv .venv --bun=1.3.3

# Activate
source .venv/bin/activate

# Install project dependencies
bun install

# Run development server
bun run dev

# When done for the day
deactivate_bun

Next time you work on the project:

cd my-bun-app
source .venv/bin/activate  # Back in business!
bun run dev

Common Questions¶

Q: Do I need to install Bun separately?

No! bunenv downloads and installs Bun for you.

Q: Can I have multiple environments?

Absolutely! Create as many as you want, each with different Bun versions.

Q: What if I want the latest Bun?

That’s the default! Just use bunenv myenv without specifying --bun.

Q: How do I delete an environment?

Just delete the directory: rm -rf my-first-env

Q: Can I use this in CI/CD?

Yes! bunenv is perfect for reproducible builds. See Common Workflows for examples.

Q: Does this work on Windows?

Yes! bunenv supports Windows with PowerShell and cmd.exe.

Next Steps¶

Now that you’ve got the basics, explore:

Common Workflows

Learn patterns for CI/CD, Python integration, and more.

Common Workflows

Configuration

Set defaults, use GitHub tokens, and customize behavior.

Configuration Guide

Advanced Features

CPU variants, mirrors, requirements files, and more.

Advanced Topics

Troubleshooting

Solutions to common problems and error messages.

Troubleshooting

You’re now ready to use bunenv in your projects. Happy coding!