# Package Management

Manage packages in your game development projects with GPM's comprehensive package management system.

## Overview

GPM provides powerful package management commands for adding, installing, updating, and removing packages across multiple game engines. The system automatically detects your project type and uses the appropriate package management workflow.

## Commands

| Command                                                               | Description                          | Usage                         |
| --------------------------------------------------------------------- | ------------------------------------ | ----------------------------- |
| [`gpm add`](/cli-reference/cli/package-management/add.md)             | Add package to project               | `gpm add <package[@version]>` |
| [`gpm install`](/cli-reference/cli/package-management/install.md)     | Install packages with auto-detection | `gpm install [packages...]`   |
| [`gpm uninstall`](/cli-reference/cli/package-management/uninstall.md) | Remove package from project          | `gpm uninstall <package>`     |
| [`gpm update`](/cli-reference/cli/package-management/update.md)       | Update packages to latest versions   | `gpm update [packages...]`    |
| [`gpm list`](/cli-reference/cli/package-management/list.md)           | List installed packages              | `gpm list`                    |

## Quick Start

### Basic Package Operations

```bash
# Add a package to your project
gpm add com.unity.analytics

# Install packages from package.json
gpm install

# List installed packages
gpm list

# Update packages to latest versions
gpm update

# Remove a package
gpm uninstall com.unity.analytics
```

### Engine-Specific Workflows

```bash
# Unity project workflow
gpm add com.unity.analytics@2.1.0
gpm add com.unity.timeline
gpm list --depth 2

# Godot project workflow (planned)
gpm add com.company.godot-utils --engine godot
gpm install

# Unreal project workflow (planned)
gpm add com.company.unreal-plugin --engine unreal
gpm install
```

## Engine Support

### Unity (Fully Supported)

* **Package Manager Integration**: Full UPM manifest management
* **Scoped Registries**: Automatic registry configuration
* **Dependency Management**: Complete dependency resolution
* **Version Control**: Git-friendly manifest updates

### Godot (Planned)

* **Addon Management**: `addons/` directory management
* **Project Configuration**: `project.godot` integration
* **Dependency Resolution**: Addon dependency handling

### Unreal Engine (Planned)

* **Plugin Management**: `Plugins/` directory management
* **Project Configuration**: `.uproject` integration
* **Dependency Resolution**: Plugin dependency handling

## Package Naming

### Reverse-DNS Format

GPM uses Unity UPM-style reverse-DNS package naming:

```
com.unity.analytics          # Unity Technologies packages
com.gameanalytics.sdk        # Third-party game analytics
com.company.mygame.analytics # Studio-specific packages
```

### Validation Rules

* Must follow reverse-DNS format: `com.company.package`
* Lowercase letters, numbers, and hyphens only
* Minimum 3 parts, maximum 10 parts
* Must contain at least one dot (`.`)

## Access Levels

### Public Packages

* **Visibility**: Available globally without authentication
* **Publishing**: Requires authentication
* **Registry**: Global registry (`https://registry.gpm.sh`)

### Scoped Packages

* **Visibility**: Available on tenant registry without authentication
* **Publishing**: Requires authentication
* **Registry**: Tenant registry (`https://<tenant>.gpm.sh`)

### Private Packages

* **Visibility**: Available on tenant registry with authentication
* **Publishing**: Requires authentication
* **Registry**: Tenant registry (`https://<tenant>.gpm.sh`)

## Common Workflows

### Development Setup

```bash
# 1. Initialize project
gpm init

# 2. Add essential packages
gpm add com.unity.analytics
gpm add com.unity.textmeshpro

# 3. Add third-party SDKs
gpm add com.gameanalytics.sdk
gpm add com.adjust.sdk

# 4. List installed packages
gpm list
```

### Team Collaboration

```bash
# 1. Install from package.json
gpm install

# 2. Add new dependency
gpm add com.company.newpackage

# 3. Update packages
gpm update

# 4. Commit changes
git add Packages/manifest.json
git commit -m "Add new package dependency"
```

### CI/CD Integration

```bash
# 1. Install dependencies
gpm install

# 2. Verify installation
gpm list --json

# 3. Build project
# (engine-specific build commands)
```

## Advanced Features

### Dependency Management

```bash
# Show dependency tree
gpm list --depth 2

# Update specific package
gpm update com.unity.analytics

# Update all packages
gpm update
```

### Global Packages

```bash
# Install globally
gpm install com.unity.analytics --global

# List global packages
gpm list --global

# Update global packages
gpm update --global
```

### Registry Management

```bash
# Use specific registry
gpm add com.package --registry https://company.gpm.sh

# Install from custom registry
gpm install --registry https://company.gpm.sh
```

## Best Practices

### Version Management

```bash
# Use specific versions for production
gpm add com.unity.analytics@2.1.0

# Use latest versions for development
gpm add com.unity.analytics

# Update regularly
gpm update
```

### Project Organization

```bash
# Group related packages
gpm add com.unity.analytics
gpm add com.unity.timeline
gpm add com.unity.textmeshpro

# Use development dependencies
gpm add com.company.test-utils --save-dev
```

### Security

```bash
# Use private registries for sensitive packages
gpm config set registry https://company.gpm.sh

# Authenticate for private packages
gpm login
gpm add com.company.private-sdk
```

## Troubleshooting

### Common Issues

* **Package not found**: Check package name and registry
* **Engine not detected**: Specify `--engine` flag
* **Dependency conflicts**: Resolve version conflicts
* **Authentication required**: Run `gpm login`

### Debug Steps

1. Check project structure: `gpm detect`
2. List installed packages: `gpm list`
3. Check configuration: `gpm config`
4. Verify authentication: `gpm whoami`

## See Also

* [CLI Reference](/cli-reference/cli.md) - Complete command documentation
* [Engine Support](/multi-engine-support/engines.md) - Engine-specific guides
* [Package Guidelines](https://github.com/gpm-sh/docs/blob/main/packages/README.md) - Package naming and access
* [Troubleshooting](https://github.com/gpm-sh/docs/blob/main/troubleshooting/README.md) - Common issues and solutions


---

# 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.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.