# Settings

> jup uses environment variables, project declarations, `jup.lock`, and a small
> supported part of `.npmrc`. It has no general config file or plugin system.

Prefer `JUP_*` names. Only settings that existed in Corepack also accept their
matching `COREPACK_*` name. `JUP_*` wins when both are present, even when its
value is empty.

## Project behavior

| Variable | Useful values | Purpose | Project env? |
| --- | --- | --- | --- |
| `JUP_ENABLE_PROJECT_SPEC` | `0` | Ignore project pins and version files. | Yes |
| `JUP_ENABLE_STRICT` | `0` | Let a different package manager use its fallback. | Yes |
| `JUP_ENABLE_AUTO_PIN` | `1` | Add a package-manager pin when a project has none. | Yes |
| `JUP_DEFAULT_TO_LATEST` | `0` | Use jup's built-in default instead of querying latest. | Yes |
| `JUP_DEFAULT_TTL` | hours, default `24` | How long jup keeps a remembered global default before re-checking it. `0` never re-checks. | Yes |
| `JUP_ENABLE_PRERELEASES` | `1` | Include prereleases in implicit selection. | Yes |
| `JUP_MINIMUM_RELEASE_AGE` | hours | Exclude younger implicit choices. | Yes |
| `JUP_FROZEN_LOCKFILE` | `1` | Refuse creation, refresh, or removal of `jup.lock` entries. | Yes |
| `JUP_ENABLE_PM_LOCKFILE` | `0` | Ignore the package manager's own lockfile: the version it recorded there, and the major its `lockfileVersion` implies for a project with no spec. | Yes |
| `JUP_SPEC_FILE` | path | Read project pin fields from another file. | No |

An exact request is not filtered by minimum release age, and neither is `jup
self-upgrade`, which fetches jup itself rather than a package manager. Invalid or
negative age values are errors.

A global default that jup chose for you is re-checked once a day, and the version
you had is kept if the check fails or you are offline. A default you set yourself
with `jup cache install -g` is never re-checked; run `jup cache install -g <name>@latest` to
move it. `jup info` marks each recorded default `(pinned)` or `(expired)`.

## Network and registry

| Variable | Useful values | Purpose | Project env? |
| --- | --- | --- | --- |
| `JUP_ENABLE_NETWORK` | `0` | Refuse jup's network requests. | Yes |
| `JUP_NPM_REGISTRY` | URL | Registry for the built-in table. | Yes |
| `JUP_REGISTRY_<NAME>` | URL | Registry/mirror for one tool. | Yes |
| `JUP_NETWORK_TIMEOUT` | milliseconds | Connection and idle timeout. | Yes |
| `JUP_NETWORK_RETRIES` | integer | GET retry attempts, capped at 10. | Yes |
| `JUP_NPM_TOKEN` | secret | Bearer authentication. | No |
| `JUP_NPM_USERNAME` | string | Basic-auth user. | No |
| `JUP_NPM_PASSWORD` | secret | Basic-auth password. | No |
| `JUP_CAFILE` | path | Add a PEM CA bundle. | No |
| `JUP_STRICT_SSL` | `0` | Disable TLS checks and warn. | No |

The default timeout is 30 seconds. Retry `0` disables retries. Standard proxy
variables are also supported; see [Registries](./registry).

## Verification and downloads

| Variable | Useful values | Purpose | Project env? |
| --- | --- | --- | --- |
| `JUP_REQUIRE_SIGNATURES` | `1` | Refuse registry-integrity fallback. | Yes |
| `JUP_ALLOW_UNVERIFIED` | `1` | Allow an otherwise unverified artifact and warn. | No |
| `JUP_INTEGRITY_KEYS` | JSON, `0`, empty | Replace or disable trusted registry keys. | No |
| `JUP_ENABLE_UNSAFE_CUSTOM_URLS` | `1` | Allow a known tool to use a custom URL. | No |

Every artifact download prints `↓ Downloading <name> <version> from <url>` to stderr,
through the `jup` command and through a tool shim alike. It is a notice, not a
question: jup never waits for an answer and never reads stdin, so a run behaves
the same in a terminal, in a pipeline and in CI. There is no setting to turn it
off, and a cached run downloads nothing and prints nothing.

## Paths, shims, and execution

| Variable | Purpose | Project env? |
| --- | --- | --- |
| `JUP_HOME` | Root of the store and managed state. | No |
| `JUP_ENV_FILE` | Choose an env file path, or `0` to disable env files. | No |
| `JUP_SHIM_DIRECTORY` | Default directory for `enable` and `disable`. | No |
| `JUP_NODE_EXECPATH` | Node.js used when a JavaScript entry must be spawned. | No |
| `JUP_HOST_RUNTIME` | Durable runtime used when pinning shim interpreters. | No |
| `JUP_QUIET_ADVISORIES` | `1` hides optional advisory `⚠` lines. | No |

Default `JUP_HOME` is under `$XDG_CACHE_HOME/jup`, `%LOCALAPPDATA%\jup` on
Windows, or the platform home cache directory.

`JUP_QUIET_ADVISORIES` does not hide errors, download notices, auto-pin notices,
validation warnings, or Yarn Switch notices.

## Project env files

jup searches for the nearest `.jup.env`. If it is absent in a directory, jup
tries `.corepack.env` there. The nearest file wins, and the search stops at the
project boundary.

Example:

```dotenv
JUP_ENABLE_STRICT=0
JUP_NETWORK_TIMEOUT=60000
JUP_REQUIRE_SIGNATURES=1
```

Only `JUP_` and `COREPACK_` keys are considered. A real environment value wins.
Protected variables are ignored; security-sensitive attempts print a warning.
`JUP_ENV_FILE=0` disables this feature. When you set an explicit env-file path,
there is no fallback filename.

## Corepack-compatible names

These settings also accept `COREPACK_` in place of `JUP_`:

- `ENABLE_PROJECT_SPEC`, `ENABLE_STRICT`, `ENABLE_AUTO_PIN`;
- `DEFAULT_TO_LATEST`, `ENABLE_NETWORK`;
- `ENABLE_UNSAFE_CUSTOM_URLS`;
- `ENV_FILE`, `HOME`;
- `NPM_REGISTRY`, `NPM_TOKEN`, `NPM_USERNAME`, `NPM_PASSWORD`;
- `INTEGRITY_KEYS`.

New jup-only settings do **not** accept a made-up `COREPACK_` form.

## Variables jup sets

jup sets both old and new spellings for:

- `JUP_ROOT` / `COREPACK_ROOT` — jup's installation root;
- `JUP_MIGRATE_FROM` / `COREPACK_MIGRATE_FROM` — the previous pin during
  `use`/`up`, or `unknown`.

For native child chains it can also forward `JUP_HOST_RUNTIME`.

## Ambient variables

jup also reads normal host variables for proxies, home/cache locations, `PATH`,
`PATHEXT`, shell hints, npm's global prefix, CI detection, debug logging, and
color. Set `DEBUG` to a value containing `jup` or `corepack` for diagnostics.
Use `NO_COLOR` or `FORCE_COLOR` to control jup's own styling.

Run `jup info` to inspect effective settings without making a request.