# flux, the fast, open source package manager for JavaScript.

> Flux is a free, open source, MIT licensed command line package manager for JavaScript and Node.js that installs packages from the npm registry faster than npm and pnpm, and ships both as an npm package and as a single self contained binary with no runtime.

- Name: flux
- Package: @iamgautamsuthar/flux
- Version: 0.2.1 (alpha)
- License: MIT
- Author: Gautam Suthar
- Website: https://flux.gautamsuthar.in
- Documentation: https://flux.gautamsuthar.in/docs
- Source: https://github.com/callmegautam/flux
- Package page: https://www.npmjs.com/package/@iamgautamsuthar/flux
- Generated: 2026-09-06T12:02:07.840Z

## Status

flux 0.2.1 is alpha software. It installs direct dependencies only, does not walk
the dependency tree, and has no lockfile, so installs are not reproducible. Use it on side
projects and experiments, and keep npm or pnpm for anything you ship.

## Why flux

### Faster than npm and pnpm

Flux keeps a shared tarball cache, skips the bookkeeping the older clients carry, and gets out of the way. Cold or warm, an install finishes before you have finished reading the line you typed.

### Open source, end to end

MIT licensed, developed in the open, no telemetry and no account. Read the source, file an issue, or fork it. Every release is built from the same public repository you are looking at.

### One binary, no runtime

Take it as an npm package if Node is already there, or as a single self contained binary if it is not. Nothing to configure, nothing to keep in sync.

## Install

```sh
npm install -g @iamgautamsuthar/flux            # needs Node.js 18 or later
curl -fsSL https://raw.githubusercontent.com/callmegautam/flux/main/install.sh | sh   # Linux and macOS, no runtime needed
irm https://raw.githubusercontent.com/callmegautam/flux/main/install.ps1 | iex        # Windows PowerShell
```

The npm package needs Node.js 18 or later. The standalone binary carries no runtime and works
on a machine with no Node.js installed. Every release ships a SHA256SUMS file, which both
install scripts verify.

### Prebuilt targets

- linux-x64: Linux, Intel / AMD 64-bit
- linux-arm64: Linux, ARM 64-bit
- darwin-x64: macOS, Intel
- darwin-arm64: macOS, Apple silicon
- windows-x64: Windows, 64-bit

## Commands

- `flux init` (aliases: create): Create a package.json in the current directory.
- `flux install [package]` (aliases: add): Install one package and record it in package.json, or install every dependency already listed there.
- `flux uninstall [package]` (aliases: remove, rm, delete): Remove one package, or all of them, from the project and node_modules.
- `flux reinstall [package]` (aliases: re, re-i): Wipe and reinstall one package, or all of them.
- `flux update [package]` (aliases: upgrade): Fetch the latest published version of one package, or all of them.
- `flux list` (aliases: ls, show): Print every dependency currently installed.
- `flux outdated` (aliases: out, old, new): Compare installed versions against what the registry publishes.
- `flux info <package>` (aliases: i): Show registry metadata for a package.
- `flux run <script>` (aliases: r): Run a script defined in package.json.
- `flux clear` (aliases: c): Delete the download cache.

Pass `--flux` to `install` to resolve tarballs through the Flux registry instead of npm.

## Configuration

### Cache location

- Linux: $XDG_CACHE_HOME/flux, or ~/.cache/flux
- macOS: ~/Library/Caches/flux
- Windows: %LOCALAPPDATA%\flux\Cache

### Environment variables

- `FLUX_CACHE_DIR`: Where downloaded tarballs are kept. Defaults to platform cache directory.
- `FLUX_VERSION`: Read by both install scripts. Defaults to latest release.
- `FLUX_INSTALL_DIR`: Where the standalone binary lands. Defaults to ~/.local/bin  ·  %LOCALAPPDATA%\flux\bin.

## Limitations

- Direct dependencies only: Flux installs what is listed in your package.json. It does not walk the dependency tree, so most real packages will not work end to end.
- No lockfile: Installs are not reproducible. Two runs of the same project can resolve to different versions.
- No semver range resolution: A range like ^1.2.3 is not resolved against. Flux installs whatever the registry currently publishes as latest.
- No test suite: There is no automated coverage yet. Treat every release as unverified until you have tried it yourself.

## Roadmap

- Full dependency tree resolution
- A lockfile, for reproducible installs
- Registry search from the CLI
- A dependency tree viewer
- Parallel installs
- Workspace support
- Vulnerability scanning

## Frequently asked questions

### What is flux?

Flux is an open source command line package manager for JavaScript and Node.js projects. It installs, updates, lists and removes packages from the npm registry, runs the scripts in your package.json, and ships either as an npm package or as a single self contained binary.

### Is flux faster than npm and pnpm?

Yes. Flux keeps every downloaded tarball in one shared per user cache, so a second project asking for the same package copies it from disk instead of the network. It also starts with no plugin pipeline to boot and no store to reconcile, so the process begins working immediately.

### Is flux free and open source?

Flux is MIT licensed and developed in the open at github.com/callmegautam/flux. It is free for personal and commercial use, there is no paid tier, no account to create, and no telemetry. Every published binary is built from the same public repository you can read.

### Is flux ready for production?

Not yet. Flux is alpha software. It installs direct dependencies only, it does not walk the dependency tree, and it has no lockfile, so installs are not reproducible. Use it on side projects and experiments, and keep npm or pnpm for anything you ship.

### How do I install flux?

With Node 18 or later already installed, run npm install -g @iamgautamsuthar/flux. Without Node, run the install script: curl -fsSL https://raw.githubusercontent.com/callmegautam/flux/main/install.sh | sh on Linux and macOS, or the matching irm command in PowerShell on Windows.

### Does flux need Node.js?

Only if you install it from npm, where Node 18 or later is required. The standalone binary carries no runtime, so it works on a machine with no Node installed at all. Prebuilt binaries cover Linux, macOS and Windows on both Intel and ARM.

### Does flux replace npm?

It aims to. Flux talks to the same npm registry, reads and writes the same package.json, and installs into the same node_modules directory, so a project stays compatible with every other client. Until dependency tree resolution and a lockfile land, treat it as a companion rather than a replacement.

### Where does flux cache packages?

In your platform cache directory: $XDG_CACHE_HOME/flux or ~/.cache/flux on Linux, ~/Library/Caches/flux on macOS, and %LOCALAPPDATA%\flux\Cache on Windows. Set FLUX_CACHE_DIR to move it somewhere else, and run flux clear to empty it.