# gpm uninstall

Remove a package from the current project.

## Usage

```bash
gpm uninstall <package> [flags]
```

## Arguments

* `<package>` - Package name to uninstall (e.g., `com.unity.analytics`)

## Flags

| Flag         | Description                              | Default |
| ------------ | ---------------------------------------- | ------- |
| `--global`   | Uninstall global package                 | `false` |
| `--save`     | Remove from package.json dependencies    | `false` |
| `--save-dev` | Remove from package.json devDependencies | `false` |
| `--json`     | Output results in JSON format            | `false` |

## Description

The `gpm uninstall` command removes a package from your game project, automatically detecting the engine and updating the project's package manifest safely. This command supports both local project packages and global packages.

### Supported Operations

* **Local Packages**: Remove from project dependencies
* **Global Packages**: Remove from global installation
* **Dependency Management**: Update package.json files
* **Engine Detection**: Automatic engine-specific removal

## Examples

### Basic Usage

```bash
# Remove package from project
gpm uninstall com.unity.analytics

# Remove with dependency update
gpm uninstall com.unity.analytics --save

# Remove development dependency
gpm uninstall com.company.test-utils --save-dev
```

### Global Packages

```bash
# Remove global package
gpm uninstall com.unity.analytics --global

# Remove global package with confirmation
gpm uninstall com.unity.analytics --global --verbose
```

### Advanced Usage

```bash
# JSON output for scripting
gpm uninstall com.unity.analytics --json

# Remove multiple packages
gpm uninstall com.unity.analytics com.unity.timeline --save
```

## Engine-Specific Behavior

### Unity

For Unity projects, `gpm uninstall` will:

1. Detect Unity project structure (`Assets/`, `ProjectSettings/`, `Packages/manifest.json`)
2. Remove package from `Packages/manifest.json` dependencies
3. Remove from scoped registries if no longer needed
4. Preserve existing structure and validate JSON
5. Create backup before making changes

**Example Unity manifest.json update:**

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

### Godot (Planned)

For Godot projects, `gpm uninstall` will:

* Remove content from `addons/<package>`
* Clean up `project.godot` references

### Unreal Engine (Planned)

For Unreal projects, `gpm uninstall` will:

* Remove content from `Plugins/<PackageName>`
* Update `.uproject` → "Plugins" array

## Package Dependencies

### Dependency Resolution

When uninstalling a package, GPM checks for:

* **Dependent packages**: Other packages that depend on the target
* **Circular dependencies**: Prevents breaking dependency chains
* **Optional dependencies**: Safely removes optional references

### Safe Removal

```bash
# Check what will be removed
gpm uninstall com.unity.analytics --verbose

# Remove with dependency check
gpm uninstall com.unity.analytics --save
```

## Output

### Human Format (Default)

```
Package Removed Successfully
─────────────────────────────
Engine:   unity
Project:  /path/to/project
Package:  com.unity.analytics
Registry: https://registry.gpm.sh
Backup:   /tmp/gpm-backup-20240101-120000
─────────────────────────────
Package com.unity.analytics removed successfully
```

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

```json
{
  "success": true,
  "engine": "unity",
  "project": "/path/to/project",
  "package": "com.unity.analytics",
  "registry": "https://registry.gpm.sh",
  "changed": true,
  "backup_path": "/tmp/gpm-backup-20240101-120000",
  "message": "Package com.unity.analytics removed successfully"
}
```

## Global Package Management

### Installing Global Packages

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

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

### Removing Global Packages

```bash
# Remove global package
gpm uninstall com.unity.analytics --global

# Remove with confirmation
gpm uninstall com.unity.analytics --global --verbose
```

## 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`
* **Dependency conflict**: `cannot remove package: other packages depend on it`
* **Project validation failed**: `project validation failed: not a valid Unity project`

### Backup and Recovery

`gpm uninstall` automatically creates backups before making changes:

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

### Dependency Conflicts

When removing packages with dependencies:

```bash
# Error: Dependency conflict
gpm uninstall com.unity.analytics
# Error: cannot remove package: com.unity.timeline depends on it

# Solution: Remove dependent packages first
gpm uninstall com.unity.timeline
gpm uninstall com.unity.analytics
```

## Best Practices

### Safe Removal

```bash
# Always use --save for production dependencies
gpm uninstall com.unity.analytics --save

# Use --save-dev for development dependencies
gpm uninstall com.company.test-utils --save-dev

# Check dependencies before removal
gpm list --depth 2
```

### Project Cleanup

```bash
# Remove unused packages
gpm list
gpm uninstall unused-package --save

# Clean up 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 update`](/cli-reference/cli/package-management/update.md) - Update 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)
* [Package Dependencies](https://github.com/gpm-sh/docs/blob/main/packages/dependencies.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/uninstall.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.