# gpm install

Install packages with multi-engine support and automatic game engine detection.

## Usage

```bash
gpm install [package[@version]...] [flags]
```

## Arguments

* `[package[@version]...]` - One or more package names with optional versions

## Flags

| Flag                   | Description                          | Default           |
| ---------------------- | ------------------------------------ | ----------------- |
| `--version <version>`  | Specific version to install          | Latest            |
| `--save`               | Save to package.json dependencies    | `false`           |
| `--save-dev`           | Save to package.json devDependencies | `false`           |
| `--global, -g`         | Install package globally             | `false`           |
| `--unity`              | Force Unity engine adapter           | Auto-detect       |
| `--unreal`             | Force Unreal Engine adapter          | Auto-detect       |
| `--godot`              | Force Godot engine adapter           | Auto-detect       |
| `--cocos`              | Force Cocos Creator engine adapter   | Auto-detect       |
| `--project-dir <path>` | Project directory                    | Current directory |
| `--registry <url>`     | Override registry URL                | From config       |

## Description

Install packages with automatic game engine detection. GPM automatically detects your game engine project and uses the appropriate package management system.

### Engine Detection

GPM looks for these indicators:

* **Unity**: `Assets/`, `ProjectSettings/`, `Packages/manifest.json`
* **Unreal**: `*.uproject` files and `Content/` directory
* **Godot**: `project.godot` file
* **Cocos Creator**: `project.json` and `assets/` directory

### Supported Sources

* **Registry**: Standard GPM registry packages
* **Git**: `git+https://github.com/user/repo.git`
* **Local File**: `file:../local-package`

## Examples

### Basic Installation

```bash
# Install from package.json (auto-detect engine)
gpm install

# Install single package
gpm install com.unity.textmeshpro

# Install specific version
gpm install com.unity.analytics@2.1.0

# Install multiple packages
gpm install pkg1 pkg2 pkg3
```

### Engine-Specific Installation

```bash
# Force Unity engine
gpm install --unity com.unity.textmeshpro

# Force Unreal engine
gpm install --unreal adjust-sdk

# Force Godot engine
gpm install --godot godot-analytics

# Force Cocos Creator engine
gpm install --cocos cocos-analytics
```

### Registry and Project Options

```bash
# Use custom registry
gpm install --registry https://homa.gpm.sh homa-analytics

# Specify project directory
gpm install --project-dir /path/to/project package-name
```

### Advanced Installation

```bash
# Install from Git
gpm install git+https://github.com/user/repo.git

# Install from local directory
gpm install file:../local-package

# Install and save to package.json
gpm install --save com.unity.analytics

# Install as dev dependency
gpm install --save-dev com.unity.test-framework
```

## Engine-Specific Behavior

### Unity

For Unity projects, `gpm install` will:

1. Detect Unity project structure
2. Modify `Packages/manifest.json`
3. Configure scoped registries automatically
4. Add dependencies with proper versioning

**Example manifest.json update:**

```json
{
  "dependencies": {
    "com.unity.textmeshpro": "3.0.6",
    "com.unity.analytics": "2.1.0"
  },
  "scopedRegistries": [
    {
      "name": "GPM",
      "url": "https://registry.gpm.sh",
      "scopes": ["com.unity"]
    }
  ]
}
```

### Unreal Engine (Planned)

For Unreal projects, `gpm install` will:

* Manage plugins directory
* Update `.uproject` files
* Handle plugin dependencies

### Godot (Planned)

For Godot projects, `gpm install` will:

* Manage `addons/` folder
* Update `project.godot`
* Handle addon dependencies

### Cocos Creator (Planned)

For Cocos Creator projects, `gpm install` will:

* Handle extensions
* Manage asset dependencies
* Update project configuration

## Package Specification

### Registry Packages

```bash
# Latest version
gpm install package-name

# Specific version
gpm install package-name@1.2.3

# Version range
gpm install package-name@^1.0.0
gpm install package-name@~1.2.0
gpm install package-name@>=1.0.0
```

### Git Packages

```bash
# From main branch
gpm install git+https://github.com/user/repo.git

# From specific branch
gpm install git+https://github.com/user/repo.git#develop

# From specific tag
gpm install git+https://github.com/user/repo.git#v1.0.0
```

### Local Packages

```bash
# From local directory
gpm install file:../local-package

# From absolute path
gpm install file:/path/to/package
```

## Output

### Detection Results

```
Multi-Engine Package Installation
────────────────────────────────────
Detected Engine: Unity
Confidence:      High
Version:         2022.3.15f1
Project Path:    /path/to/project
────────────────────────────────────
Installing:      com.unity.textmeshpro@3.0.6
Registry:        https://registry.gpm.sh
Package installed successfully
```

### Error Handling

```
Warning: Multiple engines detected:
  1. Unity (High confidence)
  2. Unreal Engine (Medium confidence)

Error: Ambiguous engine detection
Hint: Use an explicit engine flag: --unity, --unreal, --godot, or --cocos
```

## Error Handling

### Common Errors

* **No engine detected**: `No game engine project detected`
* **Ambiguous detection**: `Multiple engines detected`
* **Low confidence**: `Low confidence engine detection`
* **Package not found**: `Package not found: package-name`
* **Version not found**: `Version 1.0.0 not found for package-name`

### Troubleshooting

1. **Engine not detected**: Ensure you're in a valid game project directory
2. **Multiple engines**: Use explicit engine flags (`--unity`, `--unreal`, etc.)
3. **Package not found**: Check package name and registry configuration
4. **Installation failed**: Check project permissions and disk space

## Related Commands

* [`gpm add`](/cli-reference/cli/package-management/add.md) - Add package to project (Unity-focused)
* [`gpm uninstall`](https://github.com/gpm-sh/docs/blob/main/cli/package-management/uninstall.md) - Remove packages
* [`gpm list`](https://github.com/gpm-sh/docs/blob/main/cli/package-management/list.md) - List installed packages
* [`gpm update`](https://github.com/gpm-sh/docs/blob/main/cli/package-management/update.md) - Update packages
* [`gpm detect`](https://github.com/gpm-sh/docs/blob/main/cli/project/detect.md) - Detect project type

## See Also

* [Package Management Overview](https://github.com/gpm-sh/docs/blob/main/cli/package-management/README.md)
* [Engine Support](https://github.com/gpm-sh/docs/blob/main/engines/README.md)
* [Auto Detection](https://github.com/gpm-sh/docs/blob/main/engines/auto-detection.md)
* [Package Naming Convention](/package-guidelines/packages/naming.md)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.gpm.sh/cli-reference/cli/package-management/install.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.