## Introduction

The `--no-cache-dir` flag tells pip to skip reading from and writing to its local package cache. The primary use case is reducing Docker image size, since cached wheels and source archives can add hundreds of megabytes to a container layer. It is also useful in CI pipelines where you want guaranteed fresh downloads, and in disk-constrained environments.

## How pip Caching Works

By default, pip caches two things:

1. **HTTP responses** from PyPI (the index server), stored so pip can skip network requests for packages it has already resolved.
2. **Built wheels**, stored so pip does not need to rebuild packages from source on subsequent installs.

### Cache Locations

| Platform | Default Cache Directory |
|---|---|
| Linux | `~/.cache/pip` |
| macOS | `~/Library/Caches/pip` |
| Windows | `C:\Users\<username>\AppData\Local\pip\Cache` |

You can check your cache location and size:

```bash
pip cache dir
pip cache info
pip cache list
```

Example output:

```
Package index page cache location (pip v23.1+): /home/user/.cache/pip/http
Wheels location: /home/user/.cache/pip/wheels
Number of locally built wheels: 47
Total size: 342.1 MB
```

## When to Use `--no-cache-dir`

### 1. Docker Builds (Most Common Use Case)

The pip cache is stored inside the container layer during `RUN pip install`. Since Docker layers are additive, that cache persists in the final image even if no subsequent install uses it.

**Without `--no-cache-dir`:**

```dockerfile
FROM python:3.12-slim
COPY requirements.txt .
RUN pip install -r requirements.txt
# Image includes ~/.cache/pip with all downloaded wheels -- wasted space
```

**With `--no-cache-dir`:**

```dockerfile
FROM python:3.12-slim
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
# No cache stored -- image is smaller
```

The size difference depends on your dependencies. For a typical data science stack (numpy, pandas, scikit-learn), the cache can be 200-400 MB.

### Alternative: Docker Cache Mounts (Better Approach for Build Speed)

Docker BuildKit supports cache mounts that persist across builds but do not end up in the final image:

```dockerfile
FROM python:3.12-slim
COPY requirements.txt .
RUN --mount=type=cache,target=/root/.cache/pip \
    pip install -r requirements.txt
```

This gives you the speed benefit of caching (subsequent builds reuse downloaded packages) without the image size penalty. If your Docker version supports BuildKit (18.09+), this is generally better than `--no-cache-dir`.

### 2. CI/CD Pipelines

In CI, you may want to ensure every build downloads packages fresh from the index to catch issues like yanked releases or incompatible new versions:

```yaml
# GitHub Actions example
- name: Install dependencies
  run: pip install --no-cache-dir -r requirements.txt
```

However, most CI systems provide their own caching mechanisms (GitHub Actions `actions/cache`, GitLab CI cache directives) that are more efficient than pip's built-in cache. Consider using those instead.

### 3. Disk-Constrained Environments

On systems with limited disk space (small VMs, embedded systems, serverless functions), the cache can consume significant space over time:

```bash
# Check current cache size
pip cache info

# Install without caching
pip install --no-cache-dir some-package

# Or purge existing cache
pip cache purge
```

### 4. Troubleshooting Corrupted Cache

If pip behaves unexpectedly (installing wrong versions, failing with hash mismatches), a corrupted cache may be the cause:

```bash
# Quick fix: bypass cache for this install
pip install --no-cache-dir problematic-package

# Permanent fix: purge and rebuild
pip cache purge
pip install problematic-package
```

## When NOT to Use `--no-cache-dir`

- **Local development.** The cache saves significant time when reinstalling packages or recreating virtual environments. A warm cache means `pip install -r requirements.txt` takes seconds instead of minutes.
- **Repeated builds on the same machine.** If you build frequently on a persistent build server, the cache accelerates every build after the first.
- **Large packages with compiled C extensions.** Packages like numpy, scipy, and cryptography require compilation from source if no pre-built wheel is available. Caching the built wheel avoids recompilation, which can take several minutes per package.

## Related Flags

| Flag | Effect |
|---|---|
| `--no-cache-dir` | Disables both reading and writing cache |
| `--cache-dir /path` | Overrides the default cache directory |
| `pip cache purge` | Deletes all cached files |
| `pip cache remove <pattern>` | Deletes cached files matching a pattern |
| `--force-reinstall` | Reinstalls even if already installed (still uses cache unless `--no-cache-dir` is added) |
| `--no-binary :all:` | Forces building from source (does not affect HTTP cache) |

### Combining Flags

```bash
# Force fresh download AND rebuild from source
pip install --no-cache-dir --no-binary :all: numpy

# Force reinstall from cache (uses cached wheel if available)
pip install --force-reinstall numpy

# Force reinstall without cache (downloads and builds fresh)
pip install --force-reinstall --no-cache-dir numpy
```

## Setting `--no-cache-dir` as Default

If you always want to disable caching (not recommended for development), you can set it in pip's configuration:

```ini
# pip.conf (Linux/macOS: ~/.config/pip/pip.conf, Windows: %APPDATA%\pip\pip.ini)
[global]
no-cache-dir = true
```

Or via environment variable:

```bash
export PIP_NO_CACHE_DIR=1
```

## Common Pitfalls

- **Using `--no-cache-dir` in local development.** This forces pip to download every package from the network on every install, turning a 5-second operation into a 2-minute one. Only use it in Docker builds and CI.
- **Assuming `--no-cache-dir` makes pip ignore already-installed packages.** It does not. If a package is already installed in the current environment, pip will skip it regardless of cache settings. Use `--force-reinstall` to reinstall.
- **Forgetting to also delete the cache directory in Docker.** If you run `pip install` without `--no-cache-dir` and then try to delete the cache in a separate `RUN` layer, the cache still exists in the earlier layer (Docker layers are immutable). Either use `--no-cache-dir` or combine install and cleanup in one `RUN`:
  ```dockerfile
  RUN pip install -r requirements.txt && rm -rf /root/.cache/pip
  ```
- **Confusing `--no-cache-dir` with `--no-deps`.** `--no-deps` skips installing dependencies, which is completely unrelated to caching.
- **Not using BuildKit cache mounts.** In modern Docker workflows, `--mount=type=cache` is almost always better than `--no-cache-dir` because it provides caching across builds without inflating the final image.

## Summary

- `--no-cache-dir` prevents pip from storing downloaded packages and built wheels in its local cache.
- The primary use case is reducing Docker image size. A typical pip cache adds 100-400 MB to a container image.
- In CI, it ensures fresh downloads, but CI-level caching (GitHub Actions cache, GitLab CI cache) is usually more appropriate.
- Do not use it in local development. The cache significantly speeds up virtual environment creation and package reinstallation.
- In Docker, consider `--mount=type=cache,target=/root/.cache/pip` as an alternative that provides both caching speed and small image size.
- Use `pip cache info` to see how much space the cache is using, and `pip cache purge` to clear it.