pantry

A modern dependency manager for your system and your projects. Effortlessly manage development tools, runtime environments, and project dependencies with automatic environment isolation. Think Homebrew meets project-aware dependency management.

What is pantry

pantry is a comprehensive dependency management solution that bridges the gap between system-wide package management and project-specific environments. Whether you're setting up a new development machine, managing system tools, or working on projects with specific dependency requirements, pantry provides a unified interface for all your dependency needs.

System Management:

• Install and manage development tools system-wide
• Automatic PATH configuration and shell integration
• Cross-platform compatibility (macOS, Linux, Windows)
• Smart permission handling and installation paths

Project Management:

• Automatic project environment detection and activation
• Isolated dependency environments per project
• Version-specific tool installation
• Seamless switching between project contexts

At its core, pantry hosts its own package registry with 1700+ system packages, 50+ desktop apps, and pre-built binaries — all served from CDN. No external dependency managers required.

Learn more in the docs: Why pantry, Quick Start.

Implementation contracts: Package Manager · Registry

Features

pantry transforms how you manage dependencies across your entire development workflow:

System-Wide Dependency Management

• 📦 Global Tool Installation — Install development tools and runtimes system-wide with automatic PATH management
• 🔧 Smart Installation Paths — Automatically chooses /usr/local for system-wide access or ~/.local for user-specific installs (pkgm compatible)
• 🔌 Shell Integration — Seamless integration with your shell for immediate tool availability
• 🪟 Cross-Platform Support — Consistent experience across macOS, Linux, and Windows

Service Management

• ⚡ 68 Pre-configured Services — PostgreSQL, Redis, Kafka, Prometheus, Grafana, Vault, and more
• 🚀 One-Command Service Control — Start, stop, restart services with automatic configuration
• 🏥 Health Monitoring — Built-in health checks with automatic status detection
• 🔧 Auto-Configuration — Default configuration files generated for each service
• 🔐 Configurable Database Credentials — Customize database usernames, passwords, and authentication methods
• 🖥️ Cross-Platform Service Management — Uses launchd on macOS, systemd on Linux

Project-Aware Environment Management

• 🌍 Automatic Environment Isolation — Project-specific environments that activate when you enter a project directory
• 🎯 Dependency Detection — Automatically reads deps.yaml, dependencies.yaml, package.json, pyproject.toml, and other project files
• 🔄 Context Switching — Seamlessly switch between different project environments
• 📋 Version Management — Install and manage specific versions of tools per project
• 🗂️ Environment Management — List, inspect, clean, and remove project environments with readable identifiers

Commit Publishing (pkg-pr-new Alternative)

• 🚀 Publish from Any Commit — Publish packages directly from git commits without version bumps
• 📦 Monorepo Support — Automatically discovers and publishes all packages in a monorepo
• 🔗 Instant Install URLs — Get shareable install URLs for every published commit
• 🤖 CI/CD Ready — Drop-in replacement for pkg-pr-new in GitHub Actions

Paid Packages

• 💳 Charge for What You Publish — pantry price set my-package 9.00; metadata stays public, the tarball is gated
• 🧾 Purchases Follow the Account — buy once, install on every machine; on Team, one purchase covers everyone with a seat
• 🆓 Free Versions — keep a 1.x free while charging for 2.x, with --free-versions
• 🏦 Direct Payouts — Stripe Connect payouts to the publisher, with a configurable platform fee

For Teams

• 🛡️ Build Insurance — pantry insure mirrors every artifact you install into your own namespace; an unpublished or retagged dependency can't break your build
• 🚨 Continuous Alerts — your lockfile watched against the OSV advisory database plus your own licence policy, not just when you remember to audit
• 📜 SBOM Export — CycloneDX or SPDX with hashes computed from the bytes we stored, deterministic so it doesn't churn your repo
• 👥 Team Seats — up to 10 people share one account's packages, mirror, watch list, and paid-package purchases

Private Registries

• 🔒 Private by Default — pantry registry setup stands up your own registry where nothing — metadata, tarballs, binaries, search, the UI — is served without a credential
• 🎟️ Read-Only Tokens — Mint per-person and per-machine tokens, scoped to read or publish, revocable instantly
• 🧩 Extensible — Add routes and access policies (SSO, IP allowlists, per-team packages) as plugins, no fork of the server required
• 🏠 Runs Anywhere — One Bun process plus any S3-compatible bucket (Hetzner, Backblaze, MinIO, AWS); no AWS account needed

Desktop Apps

• 🖥️ 50+ Desktop Apps — Install VS Code, Discord, Obsidian, Spotify, and more via pantry install
• 📦 Same Pipeline — Apps go through the same registry as system packages (S3 + metadata)
• 🔄 Daily Updates — Desktop apps checked and rebuilt daily via GitHub Actions
• 🌐 Browse All — curl https://registry.pantry.dev/desktop-apps | jq

Developer Experience

• ⚡ Fast Operations — Native Zig CLI with pre-built binaries from CDN
• 🗑️ Clean Removal — Remove packages or completely uninstall with proper cleanup
• ⬆️ Self-Update — pantry upgrade to get the latest version, --canary for pre-releases
• 🎛️ Flexible Configuration — Customize behavior through config files or command-line options

Why pantry

Modern development requires managing dependencies at multiple levels - from system tools to project-specific requirements. Traditional approaches fall short:

Traditional Package Managers (Homebrew, apt, etc.):

• ❌ Global conflicts — Different projects need different versions
• ❌ Slow operations — Installing or updating can take minutes
• ❌ Manual environment management — Switching between project contexts is manual
• ❌ PATH pollution — All tools are globally available, causing conflicts

Manual Dependency Management:

• ❌ Inconsistent setups — Different team members have different environments
• ❌ Complex PATH management — Manual shell configuration is error-prone
• ❌ Version drift — Hard to maintain consistent tool versions
• ❌ Platform differences — Different setup procedures for each OS

pantry's Solution:

• ✅ Unified Management — Single tool for both system and project dependencies
• ✅ Automatic Isolation — Project environments activate automatically
• ✅ Fast Operations — Efficient package management with intelligent caching
• ✅ Consistent Experience — Same commands and behavior across all platforms
• ✅ Smart Defaults — Sensible installation paths and configuration out of the box

Read more about why we created pantry

Installation

curl -fsSL https://pantry.dev | bash

That's it. This downloads the latest pre-built binary for your platform, installs it to ~/.local/bin, and configures your PATH.

To install a specific version:

export PANTRY_VERSION=0.8.7 && curl -fsSL https://pantry.dev | bash

To install to a custom location:

export PANTRY_INSTALL_DIR=/usr/local/bin && curl -fsSL https://pantry.dev | bash

Quick Start

After installing, bootstrap your shell integration:

pantry bootstrap

This sets up:

• Shell integration for automatic project environment activation
• PATH configuration
• Global tool management

System-Wide Tool Management

Install and manage development tools across your entire system:

# Install essential development tools system-wide
pantry install node python go rust

# Install specific versions
pantry install node@22 python@3.12

# Install to /usr/local (default system-wide location)
pantry install typescript --system

# Or specify any custom path
pantry install docker --path /opt/tools

# Use shorthand for quick installs
pantry i node@22 typescript@5.7

Smart Installation Behavior:

• Default: Installs to /usr/local if writable, otherwise ~/.local
• System-wide: Use --system for explicit system installation (same as default)
• Custom paths: Use --path <directory> for any location
• Automatic PATH: Tools are immediately available in new shells

Project Environment Management

pantry automatically manages project-specific dependencies:

# Create a project with dependencies
echo "dependencies:

  - node@22
  - typescript@5.7
  - bun@1.2" > dependencies.yaml

# Environment activates automatically when you enter the directory
cd my-project
# → ✅ Environment activated for /path/to/my-project

# Tools are available in project context
node --version  # Uses project-specific Node.js
tsc --version   # Uses project-specific TypeScript

# Leave project - environment deactivates automatically
cd ..
# → 🔄 Environment deactivated

Learn more: Environment Management, Package Management, Configuration, FAQ.

Supported Project Files:

• deps.yaml / deps.yml
• dependencies.yaml / dependencies.yml
• pantry.yaml / pantry.yml
• pkgx.yaml / pkgx.yml
• package.json (Node.js projects)
• pyproject.toml (Python projects)
• Cargo.toml (Rust projects)
• And more...

Environment Management

Manage your project environments with human-readable identifiers:

# List all development environments
pantry env:list

# Inspect a specific environment
pantry env:inspect my-project_1a2b3c4d-d89abc12

# Clean up old or failed environments
pantry env:clean --dry-run

# Remove a specific environment
pantry env:remove old-project_5e6f7g8h --force

Environment Hash Format: {project-name}_{8-char-hex}-d{8-char-dep-hash}

• final-project_7db6cf06-d89abc12 - Project path hash plus dependency fingerprint
• working-test_208a31ec-d1029a7b - Human-readable with version-aware suffix
• my-app_1a2b3c4d-deadbeef - Collision-resistant, version-switching on cd

Package Management

Remove packages and manage your installation:

# Remove specific system tools
pantry remove node python

# Remove project-specific versions (using uninstall command)
pantry uninstall node@22

# See what would be removed
pantry uninstall python --dry-run

# Complete system cleanup
pantry clean --force

Service Management

Manage development services with ease:

# Start essential development services
pantry start postgres redis

# Start multiple services at once
pantry start postgres redis nginx prometheus

# Check service status
pantry status postgres
pantry services

# Stop services when done
pantry stop postgres redis

# Enable auto-start for essential services
pantry enable postgres redis

Available Services (68):

• Databases: PostgreSQL, MySQL, MariaDB, MongoDB, Redis, Valkey, InfluxDB, CockroachDB, Neo4j, ClickHouse, CouchDB, Cassandra, SurrealDB, DragonflyDB, FerretDB, TiDB, ScyllaDB, KeyDB, PocketBase
• Search: Elasticsearch, OpenSearch, Meilisearch, Typesense, Solr
• Web Servers: Nginx, Caddy, Apache (httpd), HAProxy, Traefik, Varnish, Envoy
• Message Queues: Kafka, RabbitMQ, Apache Pulsar, NATS, Mosquitto, Redpanda
• Monitoring: Prometheus, Grafana, Jaeger, Loki, Alertmanager, VictoriaMetrics
• Infrastructure: Vault, Consul, etcd, MinIO, SonarQube, Temporal, Nomad, Zookeeper
• Development & CI/CD: Jenkins, LocalStack, Verdaccio, Gitea, Mailpit
• API & Backend: Hasura, Keycloak
• AI/ML: Ollama
• DNS: CoreDNS, Unbound, dnsmasq
• Networking: Cloudflared, Tor, Syncthing, Doppler
• PHP: PHP-FPM
• Caching: Memcached

Configure services in deps.yaml

Add services to your dependency file to auto-start when the project environment activates:

# deps.yaml
dependencies:

  - node@22
  - postgresql@15

services:
  enabled: true
  autoStart:

    - postgres
    - redis

Database Configuration

Customize database credentials for all database services:

# Configure database credentials globally
export pantry_DB_USERNAME="myuser"
export pantry_DB_PASSWORD="mypassword"
export pantry_DB_AUTH_METHOD="md5"  # PostgreSQL: trust|md5|scram-sha-256

# Start databases with custom credentials
pantry start postgres mysql
# Creates project-specific databases with your configured credentials

Default Credentials (secure for development):

• Username: root
• Password: password
• Auth Method: trust (PostgreSQL)

Configuration Options:

• Environment variables: pantry_DB_USERNAME, pantry_DB_PASSWORD, pantry_DB_AUTH_METHOD
• Config file: pantry.config.ts → services.database
• Per-project databases automatically created with your credentials

Publishing to npm

Publish to npm without the npm CLI. At a monorepo root, pantry publish --npm publishes every non-private package in packages/, dependencies first. workspace: and catalog: ranges are rewritten, versions already on npm are skipped, and a package whose dependency failed in the same run is held back.

# Log in once, in the browser (saves the token to ~/.npmrc)
pantry login

# Publish every package, or just the one you're in
pantry publish --npm --access public

# Let a GitHub workflow publish with OIDC, no npm token needed
pantry publisher:add --repository my-org/my-repo --workflow release.yml

In the workflow, give the job permissions: id-token: write and run pantry publish --npm --access public. See Publishing to npm and Set up OIDC publishing for a monorepo.

Commit Publishing

Publish packages directly from git commits — a built-in replacement for pkg-pr-new:

# Publish all packages in a monorepo from the current commit
pantry publish:commit './packages/_'

# Publish a single package
pantry publish:commit ./my-package

# Dry run to see what would be published
pantry publish:commit './packages/_' --dry-run

# Use a custom registry
pantry publish:commit './packages/*' --registry https://registry.example.com

Each published package gets an install URL tied to the commit SHA:

# Install a specific commit's package
npm install https://registry.pantry.dev/commits/abc1234/@scope/my-package/tarball

GitHub Actions integration — replace pkg-pr-new in your CI:

# Before (pkg-pr-new)

- run: bunx pkg-pr-new publish './packages/_'

# After (pantry)

- run: pantry publish:commit './packages/_'

Desktop Apps

# Install desktop apps (same as system packages)
pantry install discord
pantry install obsidian
pantry install code.visualstudio.com
pantry install launchpad

# Catalog apps and fonts are inferred and activated for your user account.
# Explicit --kind remains available when a name is ambiguous.
pantry install fira-code
pantry install --dry-run launchpad

# Browse available apps
curl https://registry.pantry.dev/desktop-apps | jq
curl https://registry.pantry.dev/desktop-apps?category=Development | jq

Self-Update

# Upgrade pantry to the latest stable release
pantry upgrade

# Upgrade to the latest canary (pre-release) build
pantry upgrade --canary

# Check what would be upgraded without making changes
pantry upgrade --dry-run

Advanced Operations

# Create executable shims
pantry shim node@22 typescript@5.7

# List all installed packages
pantry list

# Update packages
pantry update node python --latest

# Cache management
pantry cache:stats     # Show cache statistics
pantry cache:clean     # Clean old cached packages
pantry cache:clear     # Clear all cache

# Install additional tools
pantry bootstrap  # Bootstrap essential tools
pantry bun     # Install Bun runtime

Configuration

Customize pantry's behavior for your system and projects:

import type { PantryConfig } from 'ts-pantry'

const config: PantryConfig = {
  // System-wide installation preferences
  installationPath: '/usr/local', // Default system location
  sudoPassword: '', // Password for sudo operations, can be loaded from `SUDO_PASSWORD` environment variable

  // Development environment settings
  devAware: true, // Enable dev-aware installations
  symlinkVersions: true, // Create version-specific symlinks
  forceReinstall: false, // Force reinstall if already installed

  // Operation settings
  verbose: true, // Detailed logging
  maxRetries: 3, // Retry failed operations
  timeout: 60000, // Operation timeout in milliseconds

  // PATH and shell integration
  shimPath: '~/.local/bin', // Custom shim location
  autoAddToPath: true, // Automatic PATH management

  // Shell message configuration
  showShellMessages: true,
  shellActivationMessage: '✅ Environment activated for {path}',
  shellDeactivationMessage: 'Environment deactivated',

  // Service management configuration
  services: {
    enabled: true, // Enable service management
    dataDir: '~/.local/share/pantry/services', // Services data directory
    logDir: '~/.local/share/pantry/logs', // Services log directory
    autoRestart: true, // Auto-restart failed services
    startupTimeout: 30, // Service startup timeout
    shutdownTimeout: 10, // Service shutdown timeout
  },

  // Registry and installation method
  useRegistry: true, // Use package registry
  installMethod: 'curl', // Installation method
  installPath: '/usr/local', // Installation path (same as installationPath)
}

export default config

See Configuration Guide for all options.

GitHub Action

Integrate pantry into your CI/CD workflows:

- name: Setup Development Environment

  uses: pantry-pm/pantry-installer@v1
  with:
    packages: node@22 typescript@5.7 bun@1.2.14

See GitHub Action Documentation for details.

Advanced Usage

Explore advanced dependency management topics:

• Paid Packages (price a package, get paid, buyers install with their account)
• Build Insurance, Alerts & SBOMs (never lose a build to an unpublished dependency)
• Plans & Fees (Free / Pro $9 / Team $29 — private packages, build insurance, priority builds)
• Run Your Own Registry (one command, and it's private by default — only authenticated members can download)
• Extending the Registry (custom routes and access policies without forking server.ts)
• Publishing to npm (monorepos, OIDC trusted publishing, pantry login)
• Commit Publishing (pkg-pr-new alternative)
• Service Management
• Project Environment Configuration
• Custom Shims and Tool Management
• Cross-platform Compatibility
• Performance Optimization
• API Reference

Comparing to Alternatives

vs Traditional Package Managers (Homebrew, apt, yum)

• 🎯 Project Awareness: Automatic project environment management vs manual setup
• ⚡ Speed: Faster installations with intelligent caching
• 🔒 Isolation: Project-specific versions vs global conflicts
• 🌍 Cross-Platform: Consistent experience across all operating systems
• ⚙️ Service Management: Built-in service management vs manual configuration

vs Language-Specific Managers (nvm, pyenv, rbenv)

• 🔄 Unified Interface: Single tool for all languages vs multiple managers
• 🤖 Automatic Switching: Context-aware environment activation
• 📦 Broader Scope: Manages system tools beyond just language runtimes
• 🛠️ Integrated Workflow: Seamless integration between system and project dependencies

vs Container-Based Solutions (Docker, devcontainers)

• 🚀 Lightweight: Native performance without virtualization overhead
• 💻 System Integration: Tools available in your native shell and IDE
• 🔧 Flexible: Mix system-wide and project-specific tools as needed
• ⚡ Instant: No container startup time or resource overhead
• 🎛️ Service Management: Native service management without containers

Changelog

Please see our releases page for information on changes.

Contributing

See release publication and recovery for native artifact verification and accepted npm upload readback.

Please see CONTRIBUTING for details.

Community

For help or discussion:

• Discussions on GitHub
• Join the Stacks Discord Server

Postcardware

"Software that is free, but hopes for a postcard." We love receiving postcards from around the world showing where Stacks is being used! We showcase them on our website too.

Our address: Stacks.js, 12665 Village Ln #2306, Playa Vista, CA 90094, United States 🌎

Credits

• Max Howell - for creating pkgx and Homebrew
• pkgm & dev - thanks for the inspiration
• Chris Breuer
• All Contributors

Sponsors

We would like to extend our thanks to the following sponsors for funding Stacks development. If you are interested in becoming a sponsor, please reach out to us.

• JetBrains
• The Solana Foundation

License

The MIT License (MIT). Please see LICENSE for more information.

Made with 💙