# gpm update

Update installed packages to their latest versions.

## Usage

```bash
gpm update [package...] [flags]
```

## Arguments

* `[package...]` - Optional package names to update (if not specified, updates all packages)

## Flags

| Flag               | Description                                       | Default     |
| ------------------ | ------------------------------------------------- | ----------- |
| `--dry-run`        | Show what would be updated without making changes | `false`     |
| `--global`         | Update global packages                            | `false`     |
| `--registry <url>` | Use specific registry                             | From config |
| `--save`           | Save updated versions to package.json             | `true`      |
| `--json`           | Output results in JSON format                     | `false`     |

## Description

The `gpm update` command updates installed packages to their latest versions. If no package names are specified, all packages in the dependencies will be updated to their latest versions. This command supports both local project packages and global packages.

### Update Behavior

* **Version Resolution**: Updates to latest compatible versions
* **Dependency Management**: Updates dependent packages as needed
* **Engine Detection**: Automatic engine-specific update handling
* **Safe Updates**: Creates backups before making changes

## Examples

### Basic Usage

```bash
# Update all packages
gpm update

# Update specific package
gpm update com.unity.analytics

# Update multiple packages
gpm update com.unity.analytics com.unity.timeline
```

### Dry Run

```bash
# See what would be updated
gpm update --dry-run

# Dry run for specific packages
gpm update com.unity.analytics --dry-run
```

### Global Packages

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

# Update specific global package
gpm update com.unity.analytics --global
```

### Advanced Usage

```bash
# Use specific registry
gpm update --registry https://company.gpm.sh

# JSON output for scripting
gpm update --json

# Update without saving to package.json
gpm update --save=false
```

## Engine-Specific Behavior

### Unity

For Unity projects, `gpm update` will:

1. Detect Unity project structure (`Assets/`, `ProjectSettings/`, `Packages/manifest.json`)
2. Check for available updates in registry
3. Update package versions in `Packages/manifest.json`
4. Update scoped registries if needed
5. Preserve existing structure and validate JSON
6. Create backup before making changes

**Example Unity manifest.json update:**

```json
{
  "dependencies": {
    "com.unity.analytics": "2.2.0",  // Updated from 2.1.0
    "com.unity.timeline": "1.7.5"   // Updated from 1.7.4
  },
  "scopedRegistries": [
    {
      "name": "GPM",
      "url": "https://registry.gpm.sh",
      "scopes": ["com.unity"]
    }
  ]
}
```

### Godot (Planned)

For Godot projects, `gpm update` will:

* Update packages in `addons/<package>`
* Update `project.godot` references

### Unreal Engine (Planned)

For Unreal projects, `gpm update` will:

* Update packages in `Plugins/<PackageName>`
* Update `.uproject` → "Plugins" array

## Version Resolution

### Update Strategy

* **Latest Compatible**: Updates to latest version within semver range
* **Breaking Changes**: Respects semver major version constraints
* **Dependency Updates**: Updates dependent packages as needed
* **Conflict Resolution**: Handles version conflicts intelligently

### Version Ranges

```bash
# Update within current major version
gpm update com.unity.analytics  # 2.1.0 → 2.2.0

# Update to latest major version
gpm update com.unity.analytics  # 2.1.0 → 3.0.0 (if available)
```

## Output

### Human Format (Default)

```
Package Updates
─────────────────────────────────────────
Engine:   unity
Project:  /path/to/project
Registry: https://registry.gpm.sh
─────────────────────────────────────────

Updated Packages:
  com.unity.analytics: 2.1.0 → 2.2.0
  com.unity.timeline:  1.7.4 → 1.7.5

No Updates Available:
  com.unity.textmeshpro: 3.0.6 (latest)

Backup: /tmp/gpm-backup-20240101-120000
─────────────────────────────────────────
2 packages updated successfully
```

### JSON Format (`--json`)

```json
{
  "success": true,
  "engine": "unity",
  "project": "/path/to/project",
  "registry": "https://registry.gpm.sh",
  "updated": [
    {
      "package": "com.unity.analytics",
      "old_version": "2.1.0",
      "new_version": "2.2.0"
    }
  ],
  "unchanged": [
    {
      "package": "com.unity.textmeshpro",
      "version": "3.0.6",
      "status": "latest"
    }
  ],
  "backup_path": "/tmp/gpm-backup-20240101-120000",
  "message": "2 packages updated successfully"
}
```

## Dry Run Mode

### Preview Updates

```bash
# See what would be updated
gpm update --dry-run

# Dry run for specific packages
gpm update com.unity.analytics --dry-run
```

### Dry Run Output

```
Update Preview
─────────────────────────────────────────
Engine:   unity
Project:  /path/to/project
Registry: https://registry.gpm.sh
─────────────────────────────────────────

Would Update:
  com.unity.analytics: 2.1.0 → 2.2.0
  com.unity.timeline:  1.7.4 → 1.7.5

Would Not Update:
  com.unity.textmeshpro: 3.0.6 (latest)

─────────────────────────────────────────
Run without --dry-run to apply updates
```

## Global Package Updates

### Updating Global Packages

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

# Update specific global package
gpm update com.unity.analytics --global

# List global packages
gpm list --global
```

### Global Package Behavior

* Updates packages installed with `--global` flag
* Maintains global package registry
* Supports global package dependencies

## Error Handling

### Common Errors

* **Package not found**: `package 'com.example.package' not found in project`
* **Engine not detected**: `no supported engine detected. Please specify --engine unity`
* **Version conflict**: `version conflict: cannot update package`
* **Network error**: `failed to fetch package information`

### Backup and Recovery

`gpm update` automatically creates backups before making changes:

* **Backup location**: `/tmp/gpm-backup-<timestamp>`
* **Automatic restoration**: On failure
* **Manual restoration**: Copy backup files back to project

### Version Conflicts

When updating packages with conflicts:

```bash
# Error: Version conflict
gpm update com.unity.analytics
# Error: version conflict: com.unity.timeline requires com.unity.analytics@2.1.0

# Solution: Update dependent packages first
gpm update com.unity.timeline
gpm update com.unity.analytics
```

## Best Practices

### Safe Updates

```bash
# Always use dry run first
gpm update --dry-run

# Update specific packages
gpm update com.unity.analytics

# Update all packages
gpm update
```

### Production Updates

```bash
# Update in development first
gpm update --dry-run
gpm update

# Test thoroughly
# Then update in production
```

### Global Package Management

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

# Clean up unused global packages
gpm list --global
gpm uninstall old-package --global
```

## Related Commands

* [`gpm add`](/cli-reference/cli/package-management/add.md) - Add packages to project
* [`gpm install`](/cli-reference/cli/package-management/install.md) - Install packages
* [`gpm list`](/cli-reference/cli/package-management/list.md) - List installed packages
* [`gpm uninstall`](/cli-reference/cli/package-management/uninstall.md) - Remove packages

## See Also

* [Package Management Overview](/cli-reference/cli/package-management.md)
* [Unity Engine Support](https://github.com/gpm-sh/docs/blob/main/engines/unity.md)
* [Version Management](https://github.com/gpm-sh/docs/blob/main/packages/versioning.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/update.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.