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

Homebrew	pantry	Notes
`brew install node`	`pantry install node` or `pantry install node@22`	Versions are optional; pin them when you need determinism
`brew uninstall node`	`pantry remove node`	pantry removes all versions by default
`brew list`	`pantry list`	Both show installed packages
`brew upgrade`	N/A	pantry uses immutable packages
`brew doctor`	`pantry --version`	Basic health check

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

Install pantry:

`bash

bun add -g ts-pantry

pantry bootstrap

Create project-specific environments:

`bash

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

Set up shell integration:

`bash

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

source ~/.zshrc

Test the migration:

`bash

cd my-project # Should automatically activate environment

node --version # Should show the version from dependencies.yaml

Gradually remove nvm (optional):

`bash

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

# Current workflow
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

# pantry workflow
cat > dependencies.yaml << EOF
dependencies:

  - python@3.12
  - pip

env:
  PYTHONPATH: ./src
  VIRTUAL_ENV: ./.venv  # For compatibility
EOF

# Environment automatically activates when entering directory

From Poetry

# Current workflow
poetry install
poetry shell

# pantry workflow
cat > dependencies.yaml << EOF
dependencies:

  - python@3.12
  - poetry@1.5

env:
  PYTHONPATH: ./src
EOF

# Then use poetry as normal within the environment
poetry install
# No need for poetry shell - environment is already active

From Conda

# Current workflow
conda create -n myproject python=3.12
conda activate myproject
conda install numpy pandas

# pantry workflow
cat > dependencies.yaml << EOF
dependencies:

  - python@3.12
  - pip

env:
  PYTHONPATH: ./src
  PROJECT_NAME: myproject
EOF

# Install packages with pip instead of conda
pip install numpy pandas

From rbenv/rvm (Ruby)

From rbenv

# Current workflow
rbenv install 3.1.0
rbenv local 3.1.0
bundle install

# pantry workflow
cat > dependencies.yaml << EOF
dependencies:

  - ruby@3.1.0

env:
  BUNDLE_PATH: ./vendor/bundle
EOF

bundle install  # Uses pantry's Ruby version

From rvm

# Current workflow
rvm install 3.1.0
rvm use 3.1.0
bundle install

# pantry workflow
cat > dependencies.yaml << EOF
dependencies:

  - ruby@3.1.0

env:
  GEM_HOME: ./.gems
  GEM_PATH: ./.gems
EOF

From Docker Development Environments

Simple Replacement

# Current Dockerfile for development
FROM node:22
WORKDIR /app
COPY package.json .
RUN npm install
CMD ["npm", "start"]

# pantry dependencies.yaml
dependencies:

  - node@22
  - yarn@1.22

env:
  NODE_ENV: development
  PORT: 3000

Complex Multi-Runtime Setup

# Current complex Dockerfile
FROM ubuntu:22.04
RUN apt-get update && apt-get install -y \
    nodejs npm python3 python3-pip postgresql-client

# pantry equivalent
dependencies:

  - node@22
  - python@3.12
  - postgresql@15

env:
  NODE_ENV: development
  PYTHON_ENV: development
  DATABASE_URL: postgresql://localhost:5432/myapp

Migration Best Practices

1. Start Small

Begin with new projects or non-critical environments:

# Create a test project to verify pantry works
mkdir test-pantry && cd test-pantry
cat > dependencies.yaml << EOF
dependencies:

  - node@22

env:
  TEST_VAR: hello-pantry
EOF

# Test that it works
echo $TEST_VAR
node --version

2. Migrate Gradually

Don't migrate everything at once:

# Week 1: Install pantry, test basic functionality
# Week 2: Migrate one small project
# Week 3: Migrate more projects
# Week 4: Consider removing old tools

3. Document Your Configuration

Keep track of your pantry configurations:

# Create a central template repository
mkdir ~/.pantry-templates
cp successful-project/dependencies.yaml ~/.pantry-templates/node-web-app.yaml

4. Verify Before Cleanup

Always verify pantry is working before removing old tools:

# Test checklist
cd my-project
echo "Node version: $(node --version)"
echo "Python version: $(python --version)"
echo "Environment: $pantry_ENV_HASH"
npm test  # or your test command

Troubleshooting Migration Issues

PATH Conflicts

# Check PATH order
echo $PATH

# Ensure pantry directories come first
# /usr/local/bin should appear before /opt/homebrew/bin

Shell Integration Conflicts

# Check for conflicts with other version managers
grep -E "(nvm|rbenv|pyenv|rvm)" ~/.zshrc ~/.bashrc

# Temporarily disable other tools to test pantry
# Comment out conflicting lines and reload shell

Package Compatibility

# Some packages might not be available
# Check availability first
pantry search package-name

# Get detailed package information
pantry info package-name

Rollback Plan

If you need to revert:

Keep old package managers during transition
Document your original configuration
Test thoroughly before cleanup
Use pantry's uninstall command

# Complete rollback
pantry uninstall --force

# Remove shell integration
sed -i '/pantry dev:shellcode/d' ~/.zshrc

# Re-enable old tools
# Uncomment nvm, rbenv, etc. in shell config

Migration Success Stories

Example: Node.js Project Migration

Before (nvm):

# .nvmrc
v22.0.0

# Terminal commands every time
cd project
nvm use
npm install
npm start

After (pantry):

# dependencies.yaml
dependencies:

  - node@22.0.0
  - yarn@1.22

env:
  NODE_ENV: development
  API_URL: http://localhost:3001

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):

conda create -n data-science python=3.12 numpy pandas jupyter
conda activate data-science

After (pantry):

# dependencies.yaml
dependencies:

  - python@3.12
  - pip

env:
  PYTHONPATH: ./src
  JUPYTER_CONFIG_DIR: ./.jupyter
  DATA_DIR: ./data

# Additional setup
pip install numpy pandas jupyter

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
Discord: Real-time help
Examples: Check the Examples page for migration patterns
Troubleshooting: See Troubleshooting for common issues

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