Frequently Asked Questions (FAQ)

When you leave the directory, everything is automatically restored.

Why isn't my environment activating

Check shell integration:

# Should show function definition
type __pantry_chpwd

# If not working, add integration
echo 'eval "$(pantry dev:shellcode)"' >> ~/.zshrc
source ~/.zshrc

Check dependency file:

# Verify file exists and syntax is correct
cat dependencies.yaml
pantry dev:dump --dryrun

Why didn't my tool version switch after I changed deps.yaml

When you cd into a project, pantry now derives the environment directory from:

• a hash of the project path, and
• a dependency fingerprint (md5 of the dependency file content),

producing a path like:

~/.local/share/pantry/envs/<project>_<hash>-d<dep_hash>

Changing versions in deps.yaml (or dependencies.yml, pkgx.yml, pantry.yml, package.json, pyproject.toml, etc.) changes the fingerprint, so a new env dir is selected and the correct versions are installed/activated automatically.

Recognized dependency files include:

• deps.yaml / deps.yml
• dependencies.yaml / dependencies.yml
• pkgx.yaml / pkgx.yml
• pantry.yaml / pantry.yml
• package.json
• pyproject.toml

To see this live, enable verbose logging and cd into the project:

export PANTRY_VERBOSE=true
cd my-project

You’ll see a line like:

🔍 Env target: env_dir=… dep_file=… dep_hash=…

If the env didn’t change, confirm the depfile is the one you edited and that dephash differs from the previous run. You can also inspect cache decisions:

🔍 Cache check: dep=… dep_mtime=… cache_mtime=… fp_match=yes|no
🔁 Cache invalid: dependency newer than cache
🔁 Cache invalid: fingerprint mismatch

Tip: if you previously activated a project and then edited dependencies, simply cd .. && cd my-project to pick up the new env.

Can I disable shell messages

Yes! You have several options:

# Disable all messages
export pantry_SHOW_ENV_MESSAGES=false

# Customize messages
export pantry_SHELL_ACTIVATION_MESSAGE="🔧 {path}"
export pantry_SHELL_DEACTIVATION_MESSAGE="Done"

# Or configure in pantry.config.ts
echo 'export default { showShellMessages: false }' > pantry.config.ts

How do I clean up old environments

# Remove environments older than 30 days
pantry env:clean --older-than 30

# Remove all unused environments
pantry env:clean --force

# Remove specific environment
pantry env:remove environment_hash_here

How do I safely clean up without removing essential tools

Use the --keep-global option to preserve global dependencies during cleanup:

# Safe cleanup that preserves global dependencies
pantry clean --keep-global --force

# Preview what would be preserved
pantry clean --keep-global --dry-run

# Combine with other options
pantry clean --keep-global --keep-cache --force

What gets preserved?

• Any package marked with global: true in dependency files

Example global dependency file (~/.dotfiles/deps.yaml):

global: true
dependencies:
  bun.sh: ^1.2.16
  gnu.org/bash: ^5.2.37
  gnu.org/grep: ^3.12.0
  starship.rs: ^1.23.0
  cli.github.com: ^2.73.0

Why use --keep-global?

• Prevents accidental removal of essential tools
• Avoids breaking your development environment
• Maintains system stability during cleanup
• Preserves tools you rely on globally across projects

Can multiple projects share the same environment

Currently, each project gets its own isolated environment based on its path. This ensures complete isolation but means:

• Different paths=Different environments (even with identical dependencies)
• Same path=Same environment (environment is reused)

This design prevents conflicts between projects but may use more disk space.

Package Management

Why do I need to specify versions

pantry requires explicit versions for predictability and isolation:

# ✅ Explicit version (recommended)
pantry install node@22

# ❌ This won't work
pantry install node

This ensures:

• Reproducible environments across team members
• No surprise updates that break your project
• Clear dependency tracking

How do I find available package versions

# Search with pantry's built-in search
pantry search node

# Get detailed package information including versions
pantry info node --versions

Can I install packages not available in pkgx

Currently, pantry uses the pkgx registry through ts-pkgx. If a package isn't available, you can:

# Check what packages are available
pantry search package-name

# Or install manually with your system package manager
brew install some-package  # macOS
apt install some-package   # Ubuntu/Debian

How do I update packages

pantry uses immutable packages - instead of updating, you install new versions:

# Install new version
pantry install node@23

# Remove old version if needed
pantry remove node@22

# Or update dependency file
# dependencies.yaml: node@23 (instead of node@22)

Why can't I install packages globally

pantry encourages project-specific environments instead of global installations:

Instead of global:

npm install -g typescript  # Global installation

Use project environments:

# dependencies.yaml
dependencies:

  - node@22
  - typescript@5.0

env:
  NODE_ENV: development

This provides better isolation and avoids version conflicts.

However, if you need global installations, you can use the global flag in your dependencies:

# dependencies.yaml - Global installation with pantry
dependencies:
  node@22:
    version: 22.1.0
    global: true # Install globally to /usr/local
  typescript@5.0:
    version: 5.0.4
    global: true # Available system-wide

env:
  NODE_ENV: development

Or apply global installation to all packages:

# dependencies.yaml - All packages global
global: true
dependencies:

  - node@22
  - typescript@5.0
  - bun@1.2.3

env:
  NODE_ENV: development

Global vs Project-Local Benefits:

• Global installation (global: true): Tools available system-wide, shared across projects
• Project-local installation (default): Perfect isolation, no version conflicts between projects
• Mixed approach: Core tools global, project-specific tools local

Configuration & Customization

Where should I put my configuration file

pantry looks for configuration in this order:

1. pantry.config.ts (current directory)
2. pantry.config.js (current directory)
3. pantry.config.json (current directory)
4. .pantryrc (home directory)
5. ~/.config/pantry/config.json

How do I configure pantry for my team

Project-specific configuration:

// pantry.config.ts (commit to version control)
export default {
  verbose: true,
  showShellMessages: true,
  shellActivationMessage: '🚀 {path} environment ready',
  installationPath: '/usr/local' // or ~/.local for user installs
}

Individual preferences:

# Personal shell messages (.zshrc)
export pantry_SHELL_ACTIVATION_MESSAGE="💻 Working on {path}"

Can I use pantry in CI/CD

Absolutely! pantry works great in CI/CD:

# GitHub Actions example

- name: Install pantry

  run: npm install -g ts-pantry

- name: Bootstrap environment

  run: pantry bootstrap --skip-shell-integration

- name: Install project dependencies

  run: pantry dev:on

Troubleshooting

My shell is slow after installing pantry

This is usually caused by:

1. Too many old environments - Clean them up:

`bash

pantry env:clean --older-than 7

`

1. Large environments - Remove unused ones:

`bash

pantry env:list --verbose # Find large environments

pantry env:remove largeenvironmenthash

`

1. Shell integration conflicts - Check for conflicts:

`bash

grep -E "(nvm|rbenv|pyenv)" ~/.zshrc

`

Package installation fails with permission errors

Fix /usr/local permissions:

sudo chown -R $(whoami) /usr/local/bin /usr/local/sbin

Or use user-local installation:

pantry install --path ~/.local node@22

Commands not found after installation

Check PATH order:

echo $PATH  # pantry directories should come first

Verify shell integration:

source ~/.zshrc  # Reload shell configuration

Manual activation:

cd my-project
pantry dev:on  # Force activation

Environment variables not working

Check dependency file syntax:

# Correct format
dependencies:

  - node@22

env:
  NODE_ENV: development # ✅ This will be set
  API_URL: 'https://api.example.com'

Test manually:

pantry dev:dump --verbose  # Shows what would be set

Performance & Limits

How much disk space does pantry use

• Base installation: ~50MB (pkgx + Bun)
• Per environment: 10MB - 500MB depending on packages
• Large environments: Python/Node with many packages can be 1GB+

Monitor usage:

pantry env:list --verbose  # Shows sizes
du -sh ~/.local/share/pantry/envs/*

Is there a limit on the number of environments

No hard limit, but consider:

• Disk space - Each environment uses storage
• Performance - Many environments can slow shell activation
• Management - Use env:clean to remove old environments

How fast is package installation

pantry is significantly faster than traditional package managers:

• pkgx caching - Packages are cached after first download
• Parallel downloads - Multiple packages install simultaneously
• No compilation - Uses pre-built binaries when available

Migration & Compatibility

Can I migrate from nvm/rbenv/pyenv

Yes! See our Migration Guide for detailed steps. The general process:

1. Install pantry alongside existing tools
2. Create dependencies.yaml files for projects
3. Test each project with pantry environments
4. Gradually remove old version managers

Will this break my existing projects

No! pantry is designed for safe migration:

• Coexists with existing package managers
• Project-specific - only affects directories with dependencies.yaml
• Reversible - Easy to disable or uninstall

How do I convert .nvmrc files

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

  - node@${NODE_VERSION}

env:
  NODE_ENV: development
EOF

Does pantry work with Starship prompt

Yes! pantry is fully compatible with Starship. However, you might see timeout warnings when Starship tries to detect tool versions:

[WARN] - (starship::utils): Executing command "/path/to/bin/bun" timed out.

Quick fix - Increase Starship's timeout in ~/.config/starship.toml:

# Add this at the top of your starship.toml
command_timeout = 5000

# Rest of your configuration
[git_branch]
symbol = "🌱 "

[bun]
symbol = "🐰 "

This gives Starship 5 seconds (instead of the default) to execute commands, which eliminates timeout warnings while keeping your prompt responsive.

Why this happens: When you enter a pantry-managed project, the environment activation process temporarily affects how quickly binaries respond, causing Starship's version detection to timeout with its default settings.

Advanced Usage

Can I create custom package templates

Yes! Create reusable templates:

# Create template directory
mkdir ~/.pantry-templates

# Create Node.js template
cat > ~/.pantry-templates/node-webapp.yaml << EOF
dependencies:

  - node@22
  - yarn@1.22
  - typescript@5.0

env:
  NODE_ENV: development
  PORT: 3000
EOF

# Use template
cp ~/.pantry-templates/node-webapp.yaml ./dependencies.yaml

Can I use pantry in Docker

Yes! pantry works in containers:

FROM ubuntu:22.04

# Install pantry
RUN curl -fsSL https://bun.sh/install | bash
RUN /root/.bun/bin/bun add -g ts-pantry

# Bootstrap and install dependencies
COPY dependencies.yaml .
RUN pantry bootstrap --skip-shell-integration
RUN pantry dev:on

How do I script with pantry

Environment activation in scripts:

# !/bin/bash
cd my-project

# Activate environment
eval "$(pantry dev:shellcode)"
source <(pantry dev:script)

# Now use project-specific tools
node --version
python --version

Getting Help

Where can I get support

• Documentation: https://pantry.sh
• GitHub Discussions: Ask questions
• Discord: Real-time chat
• Issues: Report bugs

How do I report a bug

When reporting issues, include:

1. System information: pantry --version, OS, shell
2. Error messages: Full error output
3. Steps to reproduce: What you did before the error
4. Configuration: Your pantry.config.ts (sanitized)
5. Environment: Output of pantry env:list

How can I contribute

• Documentation: Improve guides and examples
• Code: Submit pull requests
• Community: Help others in Discord/Discussions
• Testing: Report bugs and edge cases
• Feedback: Share your use cases and feature requests

Is pantry open source

Yes! pantry is open source under the MIT license:

• GitHub: https://github.com/home-lang/pantry
• License: MIT License
• Contributing: Contribution Guidelines