Migration Guide

This guide helps you migrate from other package managers to pantry, whether you want to replace them entirely or use pantry alongside your existing tools.

Migration Philosophy

pantry is designed to coexist peacefully with other package managers rather than replace them entirely. This means you can:

• Keep using Homebrew for GUI applications and system tools
• Use pantry for development environments and project-specific tools
• Gradually migrate projects at your own pace
• Maintain both systems without conflicts

From Homebrew

Understanding the Difference

Homebrew installs to /opt/homebrew (Apple Silicon) or /usr/local (Intel) pantry installs to /usr/local by default (or ~/.local for user installs)

On Apple Silicon Macs, this means zero conflicts since they use different directories.

Audit Your Current Setup

# List all Homebrew packages
brew list > homebrew-packages.txt

# Categorize your packages
echo "= GUI Applications =" >> migration-plan.txt
brew list --cask >> migration-plan.txt

echo "= Development Tools =" >> migration-plan.txt
brew list | grep -E "(node|python|go|rust|java)" >> migration-plan.txt

echo "= System Tools =" >> migration-plan.txt
brew list | grep -E "(git|curl|wget|jq)" >> migration-plan.txt

Migration Strategy

Option 1: Parallel Installation (Recommended)

Keep Homebrew for some packages, use pantry for others:

# Install pantry
bun add -g ts-pantry
pantry bootstrap

# Keep using Homebrew for GUI apps
brew install --cask visual-studio-code
brew install --cask docker

# Use pantry for development tools
pantry install node@22 python@3.12 go@1.21

# Both coexist peacefully
brew list           # Homebrew packages
pantry list      # pantry packages

Option 2: Project-by-Project Migration

Gradually migrate projects to use pantry environments:

# Start with a new project
mkdir new-project && cd new-project
cat > dependencies.yaml << EOF
dependencies:

  - node@22
  - yarn@1.22

env:
  NODE_ENV: development
EOF

# Environment automatically activates
# ✅ Environment activated for /path/to/new-project

# Old projects continue using Homebrew versions
cd ../old-project
node --version  # Uses Homebrew version

Option 3: Complete Migration

Replace Homebrew development tools with pantry:

# 1. Install pantry
bun add -g ts-pantry
pantry bootstrap

# 2. Install development tools via pantry
pantry install node@22 python@3.12 go@1.21 rust

# 3. Update your PATH to prioritize pantry
# (pantry bootstrap already does this)

# 4. Verify new tools are used
which node    # Should point to pantry installation
which python  # Should point to pantry installation

# 5. Remove Homebrew development tools (optional)
brew uninstall node python go rust

Command Mapping

From Node Version Manager (nvm)

Current State Analysis

# Check current Node versions
nvm list

# Check current default
nvm current

# See which projects use which versions
find . -name ".nvmrc" -exec echo {} \; -exec cat {} \; -exec echo \;

Migration Steps

1. Install pantry:

   bun add -g ts-pantry
   pantry bootstrap
   

2. Create project-specific environments:

For each project, replace .nvmrc with dependencies.yaml

cd my-project

If you have .nvmrc

NODE_VERSION=$(cat .nvmrc) cat > dependencies.yaml << EOF dependencies:

 - node@${NODE_VERSION}
 - yarn@1.22  # or npm, depending on preference

env: NODE_ENV: development EOF

3. **Set up shell integration:**

```bash
echo 'eval "$(pantry dev:shellcode)"' >> ~/.zshrc
source ~/.zshrc

4. Test the migration:

   cd my-project  # Should automatically activate environment
   node --version # Should show the version from dependencies.yaml
   

5. Gradually remove nvm (optional):

After verifying all projects work

nvm deactivate

Remove nvm lines from ~/.zshrc

Uninstall nvm

### Benefits Over nvm

- **Automatic activation** - No need to run `nvm use`
- **Multiple runtimes** - Include Python, Go, etc. in the same environment
- **Environment variables** - Set project-specific env vars
- **Isolation** - Each project gets its own install directory

## From Python Virtual Environments

### From virtualenv/venv


<!--BUNPRESS_CODE_5-->


### From Poetry


<!--BUNPRESS_CODE_6-->


### From Conda


<!--BUNPRESS_CODE_7-->


## From rbenv/rvm (Ruby)

### From rbenv


<!--BUNPRESS_CODE_8-->


### From rvm


<!--BUNPRESS_CODE_9-->


## From Docker Development Environments

### Simple Replacement


<!--BUNPRESS_CODE_10-->



<!--BUNPRESS_CODE_11-->


### Complex Multi-Runtime Setup


<!--BUNPRESS_CODE_12-->



<!--BUNPRESS_CODE_13-->


## Migration Best Practices

### 1. Start Small

Begin with new projects or non-critical environments:


<!--BUNPRESS_CODE_14-->


### 2. Migrate Gradually

Don't migrate everything at once:


<!--BUNPRESS_CODE_15-->


### 3. Document Your Configuration

Keep track of your pantry configurations:


<!--BUNPRESS_CODE_16-->


### 4. Verify Before Cleanup

Always verify pantry is working before removing old tools:


<!--BUNPRESS_CODE_17-->


## Troubleshooting Migration Issues

### PATH Conflicts


<!--BUNPRESS_CODE_18-->


### Shell Integration Conflicts


<!--BUNPRESS_CODE_19-->


### Package Compatibility


<!--BUNPRESS_CODE_20-->


## Rollback Plan

If you need to revert:

1. **Keep old package managers during transition**
2. **Document your original configuration**
3. **Test thoroughly before cleanup**
4. **Use pantry's uninstall command**


<!--BUNPRESS_CODE_21-->


## Migration Success Stories

### Example: Node.js Project Migration

**Before (nvm):**


<!--BUNPRESS_CODE_22-->


**After (pantry):**


<!--BUNPRESS_CODE_23-->


**Benefits achieved:**

- ✅ Automatic environment activation
- ✅ Included yarn in project environment
- ✅ Project-specific environment variables
- ✅ No manual `nvm use` commands

### Example: Python Data Science Migration

**Before (Conda):**


<!--BUNPRESS_CODE_24-->


**After (pantry):**


<!--BUNPRESS_CODE_25-->



<!--BUNPRESS_CODE_26-->


**Benefits achieved:**

- ✅ Automatic environment activation
- ✅ Project-specific Python paths
- ✅ Custom environment variables
- ✅ Easier to version control

## Getting Help During Migration

- **GitHub Discussions**: [Ask migration questions](https://github.com/home-lang/pantry/discussions)
- **Discord**: [Real-time help](https://discord.gg/stacksjs)
- **Examples**: Check the [Examples](./examples.md) page for migration patterns
- **Troubleshooting**: See [Troubleshooting](./troubleshooting.md) for common issues

Remember: Migration should be **gradual**and**reversible**. Take your time and verify each step works before proceeding to the next.