# nuts

```
     __        __
  /\ \ \ _  __/ /______
 /  \/ / / / / __/ ___/
/ /\  / /_/ / /_(__  )   latest version 1.1.0.0 
\_\ \/\__,_/\__/____/    LTS version 1.0.0.0 
```

> **The package manager Java never had.**
> Website: https://thevpc.github.io/nuts

[![Download](https://img.shields.io/badge/download-nuts-blue)]([https://github.com/thevpc/nuts](https://thevpc.github.io/nuts/download.html))
[![License](https://img.shields.io/badge/license-LGPLv3-blue)](https://www.gnu.org/licenses/lgpl-3.0.html)

---

![Nuts in action](documentation/term-cast/nuts-install-demo.webp)


## What is Nuts?

**Nuts** is a package manager for Java applications that focuses on the application lifecycle and isolated deployments.

**Nuts** manages dependencies at runtime, not at build time, by reusing Maven descriptors directly and solving the long-standing fat-jars problem efficiently: 
- It downloads only the JARs and dependencies that are actually needed on the target machine
- Similarly, for native binaries, it retains only assets relevant for the target platform.

**Nuts** does not require any custom descriptors or build tools, does not change classloading behavior, it just solves dependency tree, builds the classpath and runs the application. 

What makes **Nuts** unique is that it shares the same workspace across all applications, enables installing multiple versions of the same app, and automatically provisions the required platform binaries (JDK).
A simple `nuts install myapp` is all you need to install the latest version of `myapp` and all its dependencies—including the required JDK—while optimizing network and disk usage.

Think of **Nuts** as **`uv`** (or `npx`/`pipx`), but for the Java ecosystem: combining runtime dependency resolution, JDK auto-provisioning, workspace isolation, and instant app execution.

---

## Installation

Nuts can be installed via enterprise packages (RPM/DEB), standalone binaries, or quick automated scripts.

### 📦 Enterprise & Download Packages (Recommended)

Visit the official **[Nuts Download Page](https://thevpc.github.io/nuts/download.html)** for:
- **RPM & DEB Packages** (RedHat / SUSE / Debian / Ubuntu)
- **GUI & Console Installers**
- **Offline Binaries & Standalone Executable JARs** (`nuts-app.jar` for zero-install execution)
- **Version Archives & Release LTS Builds**

#### Quick Standalone Execution (No Install Required):
Download `nuts-app-1.1.0.jar` from the [Download Page](https://thevpc.github.io/nuts/download.html) and run:
```bash
java -jar nuts-app-1.1.0.jar -Zy
```

---

### ⚡ Quick Script Installation (Developer / Evaluation)

#### 🐧 Linux / 🍏 macOS
```bash
# Latest Release (Recommended for Developers)
curl -s https://thevpc.net/nuts/install-latest.sh | bash

# Stable Release (Production Systems)
curl -s https://thevpc.net/nuts/install-stable.sh | bash
```

#### 🪟 Windows (PowerShell)
```powershell
# Latest Release
powershell -Command "irm https://thevpc.net/nuts/install-latest.ps1 | iex"

# Stable Release
powershell -Command "irm https://thevpc.net/nuts/install-stable.ps1 | iex"
```

*Restart your terminal, then verify:*
```bash
nuts --version
```

### Update existing installation
```bash
nuts update
```

---

## Key Features
- Works with existing Maven JARs — zero repackaging
- Supports multiple repositories simultaneously, including Maven-central and Maven-compatible repositories
- Full application lifecycle — Install, run, update, and uninstall applications — with multiple versions coexisting in the same workspace
- Filesystem isolation — Everything is isolated in a workspace compliant to the system standards (XDG for Linux, etc...)
- JDK provisioning — resolve required java version for each application and automatic provisioning
- Not just Java — can manage any application, as long as a compliant descriptor is provided

## Quick Examples

| Command                                                                        | What it does                                                                                 |
|--------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------|
| `nuts org.apache.netbeans:netbeans`                                            | install and run NetBeans IDE                                                                 |
| `nuts org.springframework.boot:spring-boot-cli init --dependencies=web my-app` | scaffold a Spring Boot project                                                               |
| `nuts org.jd:jd-gui`                                                           | decompile a JAR                                                                              |
| `nuts uninstall org.jd:jd-gui#1.6.6`                                           | uninstall version jd-gui version 1.6.6                                                       |
| `nuts update nsh`                                                              | update to the newest version of java bash compatible shell                                   |
| `nuts org.postgresql:postgresql-server initdb -D ~/pgdata`                     | initialize a portable PostgreSQL instance (not a java app)                                   |
| `nuts --at=ssh://me@myserver install myapp:2.0`                                | deploy to remote server                                                                      |
| `nuts bundle nsh`                                                              | create offline deployment bundle (air-gapped deployment) of nsh with all of its dependencies |
| `nuts search --installed --json`                                               | list installed apps as JSON                                                                  |
| `nuts net.thevpc.nsh:nsh#1.0.0`                                                | run a specific installed version of nsh                                                      |
| `nuts nsh -c "cp http://host/a.pdf ssh://user@server/b.pdf"`                   | cross-protocol file copy                                                                     |

→ [See the full showcase](documentation/tutorials/SHOWCASE.md) for more examples including databases, IDEs, security tools, and games.

---

## How Nuts relates to other tools

| Tool | What it does | Relationship to **Nuts** |
|---|---|---|
| Maven / Gradle | Compile-time dependency resolution | **Nuts** reuses their descriptors at runtime |
| uv / uvx | Python runtime provisioning, package management & instant tool execution | **Nuts** provides the equivalent all-in-one experience for the JVM (JDK auto-provisioning + Maven runtime resolution + instant app execution) |
| jbang | Run Java scripts and JARs | **Nuts** adds workspaces, platforms, lifecycle, deployment |
| sdkman / jenv | Manage JDK versions | **Nuts** subsumes this as part of workspace platform management |
| Docker | Isolated application environments | **Nuts** is lighter — no daemon, no root, no image layers |
| apt / brew / snap / flatpak | System or per-app package management | **Nuts** is per-workspace with dependencies shared across apps in the same workspace (no per-app bundling), no root required, and portable across Linux, Windows, and macOS |
| Ansible | Infrastructure and configuration management | Complementary — **Nuts** handles the Java app lifecycle layer |
| jgo | Launch Java apps from Maven coordinates (Python-based) | Similar launch model; **Nuts** is Java-native with workspaces, lifecycle, and deployment |

**Nuts** fills the space between "compile-time dependency management" and "production deployment" that the Java ecosystem has never had a clean answer for.

---

## Contribute

**Nuts** is open-source and actively developed. Contributions welcome.

[Contribute on GitHub](CONTRIBUTING.md)  
[Official documentation](https://thevpc.github.io/nuts/doc-nuts.html)

---

## License

Licensed under the GNU Lesser General Public License v3.