# How to manage dependencies in Replit

- Tool: Replit
- Difficulty: Beginner
- Time required: 15-20 minutes
- Compatibility: All Replit plans. Starter: ~2 GiB storage. Core: 50 GiB storage. Pro: 50+ GiB storage.
- Last updated: March 2026

## TL;DR

Manage dependencies in a large Replit project using three layers: language-level package managers (npm for Node.js, pip for Python), system-level Nix packages for native binaries, and the GUI package manager in the Tools dock. Use replit.nix for system dependencies like image libraries or database clients, package.json or requirements.txt for application dependencies, and the onBoot command to ensure everything installs automatically on startup.

## Manage Dependencies in Large Replit Projects with npm, pip, and Nix

Large projects often need more than just npm packages — they need system-level libraries, database clients, image processors, or other native binaries that package managers alone cannot provide. Replit uses a layered dependency system: language package managers (npm, pip, poetry) for application code, Nix for system-level packages, and a GUI tool for quick installs. This tutorial explains how all three layers work together and how to configure them for a large, stable project.

## Before you start

- A Replit account on any plan (Core or Pro recommended for large projects)
- A Replit App with existing code
- Basic familiarity with the Shell tab and package managers
- No prior experience with Nix required

## Step-by-step guide

### 1. Install application dependencies with npm or pip

Open the Shell tab and use your language's package manager to install dependencies. For Node.js projects, use npm install. For Python, use pip install. These install packages into your project directory (node_modules for npm, a virtual environment for pip). Always use --save or --save-dev flags with npm so dependencies are recorded in package.json. For pip, generate a requirements.txt file after installing packages so the list is reproducible.

```
# Node.js — install and save to package.json
npm install express cors dotenv
npm install --save-dev jest typescript

# Python — install and freeze to requirements.txt
pip install flask requests sqlalchemy
pip freeze > requirements.txt
```

**Expected result:** Packages are installed and recorded in package.json or requirements.txt. Running 'npm ls' or 'pip list' in Shell shows the installed packages.

### 2. Use the GUI package manager for quick installs

Replit provides a graphical package manager accessible from the Tools dock. Click the Dependencies tool (or search for 'Packages' in the search bar) to open it. Type a package name to search, then click the install button. The GUI handles the installation command for you and adds the package to your dependency file automatically. This is useful for beginners or when you want to browse available packages without memorizing exact names.

**Expected result:** Packages install through the GUI and appear in your package.json or requirements.txt the same way as Shell-installed packages.

### 3. Configure replit.nix for system-level dependencies

Some packages need system libraries that npm or pip cannot provide — for example, image processing libraries need libvips, database clients need PostgreSQL headers, and PDF generation needs poppler. Replit uses Nix to manage these system-level dependencies. Open .replit (enable 'Show hidden files'), then open replit.nix. Add the required system packages to the deps array. Search for available packages at search.nixos.org/packages. After editing replit.nix, type 'exit' in Shell to restart the environment and load the new packages.

```
# replit.nix — system-level dependencies
{ pkgs }: {
  deps = [
    pkgs.nodejs-20_x
    pkgs.nodePackages.typescript-language-server
    pkgs.python311
    pkgs.postgresql
    pkgs.libvips
    pkgs.ffmpeg
    pkgs.imagemagick
  ];
}
```

**Expected result:** After running 'exit' in Shell, the system packages are available. You can verify by running the package command (e.g., 'ffmpeg --version' or 'psql --version') in Shell.

### 4. Add quick Nix packages via the .replit file

For simpler system dependencies, you can skip editing replit.nix and add packages directly in the .replit file under the [nix] section. This is a quicker method for small additions. The packages listed here are installed alongside those in replit.nix. Make sure the Nix channel is set to a recent stable version to ensure package compatibility.

```
# .replit file — quick Nix packages
[nix]
channel = "stable-24_05"
packages = ["cowsay", "htop", "curl", "jq"]
```

**Expected result:** The listed packages are available in Shell after the environment restarts. Running 'htop' or 'jq --version' confirms availability.

### 5. Set up onBoot for automatic dependency installation

To ensure dependencies install automatically whenever the Repl starts (especially after a restart or when a collaborator opens the project), add an onBoot command to your .replit file. This runs once at startup and handles the initial setup. For projects that use both npm and pip, chain the commands with &&.

```
# .replit file
onBoot = "npm install && pip install -r requirements.txt"
```

**Expected result:** Opening the Repl automatically installs all application dependencies. Collaborators do not need to manually run npm install or pip install.

### 6. Monitor storage usage and manage dependency sizes

Large projects with many dependencies can hit storage limits, especially on the Starter plan (approximately 2 GiB). Check your current storage usage by clicking the Resources panel (stacked computers icon in the left sidebar). It shows RAM, CPU, and storage breakdown. To reduce dependency size, remove unused packages with npm prune or pip uninstall, avoid installing heavy packages globally, and use .replit hidden to hide large directories like node_modules from the file tree without deleting them.

```
# Check disk usage from Shell
du -sh node_modules/
du -sh .local/

# Remove unused npm packages
npm prune

# Remove a specific unused package
npm uninstall unused-package-name
```

**Expected result:** You can see your current storage usage in the Resources panel and identify which directories consume the most space.

## Complete code example

File: `.replit`

```toml
# .replit — dependency management for a large project

entrypoint = "src/index.js"
modules = ["nodejs-20:v8-20230920-bd784b9"]

# Install dependencies automatically on startup
onBoot = "npm install"

# Run the application
run = "node src/index.js"

# Quick system packages
[nix]
channel = "stable-24_05"
packages = ["curl", "jq"]

# Environment variables for development
[run.env]
NODE_ENV = "development"

# Deployment configuration
[deployment]
build = ["sh", "-c", "npm ci && npm run build"]
run = ["sh", "-c", "NODE_ENV=production node dist/index.js"]
deploymentTarget = "cloudrun"

# Port configuration
[[ports]]
localPort = 3000
externalPort = 80

# Hide large/generated directories from file tree
hidden = [
  ".config",
  "package-lock.json",
  "node_modules",
  ".local",
  "dist",
  ".cache"
]
```

## Common mistakes

- **Not running 'exit' in Shell after editing replit.nix, so new system packages are not loaded** — undefined Fix: After any change to replit.nix, type 'exit' in Shell. This restarts the Nix environment and loads the new packages.
- **Using the wrong package name format in replit.nix (e.g., 'nodejs' instead of 'pkgs.nodejs-20_x')** — undefined Fix: Search for the exact package name at search.nixos.org/packages. Always use the pkgs. prefix in replit.nix.
- **Running out of storage on the Starter plan due to large node_modules** — undefined Fix: Run 'npm prune' to remove unused packages. Check 'du -sh node_modules/' to see the size. Consider upgrading to Core (50 GiB) for large projects.
- **Installing packages globally instead of as project dependencies** — undefined Fix: Use 'npm install package-name' (not npm install -g) so packages are project-scoped and available to all collaborators and deployments.

## Best practices

- Always record dependencies in package.json (npm) or requirements.txt (pip) so the project is reproducible
- Use replit.nix for system-level libraries and npm/pip for application-level packages — do not mix their responsibilities
- Set onBoot in .replit to automatically install dependencies when the Repl starts
- Run 'exit' in Shell after editing replit.nix to reload the Nix environment
- Use the Resources panel to monitor storage and identify oversized dependency directories
- Hide node_modules, .local, and .cache in the .replit hidden array to keep the file tree navigable
- Use npm ci instead of npm install in deployment builds for deterministic, faster installations
- Search for Nix packages at search.nixos.org/packages to find exact package names before adding them to replit.nix

## Frequently asked questions

### What is the difference between npm packages and Nix packages?

npm packages are JavaScript/Node.js libraries for your application code (Express, React, etc.). Nix packages are system-level binaries and libraries (PostgreSQL, FFmpeg, ImageMagick) that run on the operating system. You need both for projects that depend on native system tools.

### How much storage do I get for dependencies?

Starter plan provides approximately 2 GiB. Core plan provides 50 GiB. Pro plan provides 50+ GiB. Nix packages from Replit's prebuilt cache do not count against your quota.

### Do I need to install dependencies again after restarting the Repl?

npm packages in node_modules persist across restarts. However, setting onBoot = "npm install" in .replit ensures any missing packages are restored automatically. Nix packages are always available after replit.nix is configured.

### Can Replit Agent install dependencies for me?

Yes. Agent v4 automatically installs dependencies when building applications. It configures package.json, replit.nix, and installs packages as needed. You can also prompt Agent directly: 'Install PostgreSQL client and image processing libraries for this project.'

### What happens to dependencies when I deploy?

The deployment build step runs in a clean environment. Include npm ci or npm install in the [deployment] build command. Nix packages from replit.nix are available in deployments automatically.

### How do I use both npm and pip in the same project?

Replit supports polyglot projects. Add both Node.js and Python modules to your .replit file. Use npm install for JavaScript packages and pip install for Python packages. Set onBoot to install both: 'npm install && pip install -r requirements.txt'.

### Why does my Nix package installation fail?

Common causes: wrong package name (check search.nixos.org), outdated Nix channel (update to stable-24_05 or later), or unfree packages not enabled. Check the exact error by running 'cat /run/replit/env/error' in Shell.

### What if dependency management becomes overwhelming in a large project?

For projects with complex dependency trees, native module conflicts, or multi-language requirements, the RapidDev team can help set up a clean, scalable dependency management strategy that prevents version conflicts and keeps builds fast.

---

Source: https://www.rapidevelopers.com/replit-tutorial/how-to-use-replit-s-container-environment-to-manage-dependencies-for-a-large-project
© RapidDev — https://www.rapidevelopers.com/replit-tutorial/how-to-use-replit-s-container-environment-to-manage-dependencies-for-a-large-project