docs/get-started/installation.mdx

import { Tabs, TabItem } from '@astrojs/starlight/components';

# Gemini CLI installation, execution, and releases

This document provides an overview of Gemini CLI's system requirements,
installation methods, and release types.

## Recommended system specifications

- **Operating System:**
  - macOS 15+
  - Windows 11 24H2+
  - Ubuntu 20.04+
- **Hardware:**
  - "Casual" usage: 4GB+ RAM (short sessions, common tasks and edits)
  - "Power" usage: 16GB+ RAM (long sessions, large codebases, deep context)
- **Runtime:** Node.js 20.0.0+
- **Shell:** Bash, Zsh, or PowerShell
- **Location:**
  [Gemini Code Assist supported locations](https://developers.google.com/gemini-code-assist/resources/available-locations#americas)
- **Internet connection required**

## Install Gemini CLI

We recommend most users install Gemini CLI using one of the following
installation methods. Note that Gemini CLI comes pre-installed on
[**Cloud Shell**](https://docs.cloud.google.com/shell/docs) and
[**Cloud Workstations**](https://cloud.google.com/workstations).

<Tabs>
  <TabItem label="npm">

  Install globally with npm:

  ```bash
  npm install -g @google/gemini-cli
  ```

  </TabItem>
  <TabItem label="Homebrew (macOS/Linux)">

  Install globally with Homebrew:

  ```bash
  brew install gemini-cli
  ```

  </TabItem>
  <TabItem label="MacPorts (macOS)">

  Install globally with MacPorts:

  ```bash
  sudo port install gemini-cli
  ```

  </TabItem>
  <TabItem label="Anaconda">

  Install with Anaconda (for restricted environments):

  ```bash
  # Create and activate a new environment
  conda create -y -n gemini_env -c conda-forge nodejs
  conda activate gemini_env

  # Install Gemini CLI globally via npm (inside the environment)
  npm install -g @google/gemini-cli
  ```

  </TabItem>
</Tabs>

## Run Gemini CLI

For most users, we recommend running Gemini CLI with the `gemini` command:

```bash
gemini
```

For a list of options and additional commands, see the
[CLI cheatsheet](../cli/cli-reference.md).

You can also run Gemini CLI using one of the following advanced methods:

<Tabs>
  <TabItem label="npx">

  Run instantly with npx. You can run Gemini CLI without permanent installation.

  ```bash
  # Using npx (no installation required)
  npx @google/gemini-cli
  ```

  You can also execute the CLI directly from the main branch on GitHub, which is
  helpful for testing features still in development:

  ```bash
  npx https://github.com/google-gemini/gemini-cli
  ```

  </TabItem>
  <TabItem label="Docker/Podman Sandbox">

  For security and isolation, Gemini CLI can be run inside a container. This is
  the default way that the CLI executes tools that might have side effects.

  - **Directly from the registry:** You can run the published sandbox image
    directly. This is useful for environments where you only have Docker and want
    to run the CLI.
    ```bash
    # Run the published sandbox image for a specified CLI version
    docker run --rm -it us-docker.pkg.dev/gemini-code-dev/gemini-cli/sandbox:0.42.0-nightly.20260428.g59b2dea0e
    ```
  - **Using the `--sandbox` flag:** If you have Gemini CLI installed locally
    (using the standard installation described above), you can instruct it to run
    inside the sandbox container.
    ```bash
    gemini --sandbox -y -p "your prompt here"
    ```

  </TabItem>
  <TabItem label="From source">

  Contributors to the project will want to run the CLI directly from the source
  code.

  - **Development mode:** This method provides hot-reloading and is useful for
    active development.
    ```bash
    # From the root of the repository
    npm run start
    ```
  - **Production mode (React optimizations):** This method runs the CLI with React
    production mode enabled, which is useful for testing performance without
    development overhead.
    ```bash
    # From the root of the repository
    npm run start:prod
    ```
  - **Production-like mode (linked package):** This method simulates a global
    installation by linking your local package. It's useful for testing a local
    build in a production workflow.

    ```bash
    # Link the local cli package to your global node_modules
    npm link packages/cli

    # Now you can run your local version using the `gemini` command
    gemini
    ```

  </TabItem>
</Tabs>

## Releases

Gemini CLI has three release channels: stable, preview, and nightly. For most
users, we recommend the stable release, which is the default installation.

<Tabs>
  <TabItem label="Stable">

  Stable releases are published each week. A stable release is created from the
  previous week's preview release along with any bug fixes. The stable release
  uses the `latest` tag. Omitting the tag also installs the latest stable
  release by default.

  ```bash
  # Both commands install the latest stable release.
  npm install -g @google/gemini-cli
  npm install -g @google/gemini-cli@latest
  ```

  </TabItem>
  <TabItem label="Preview">

  New preview releases will be published each week. These releases are not fully
  vetted and may contain regressions or other outstanding issues. Try out the
  preview release by using the `preview` tag:

  ```bash
  npm install -g @google/gemini-cli@preview
  ```

  </TabItem>
  <TabItem label="Nightly">

  Nightly releases are published every day. The nightly release includes all
  changes from the main branch at time of release. It should be assumed there are
  pending validations and issues. You can help test the latest changes by
  installing with the `nightly` tag:

  ```bash
  npm install -g @google/gemini-cli@nightly
  ```

  </TabItem>
</Tabs>