mirror of
https://github.com/google-gemini/gemini-cli.git
synced 2026-03-10 22:21:22 -07:00
Update installation guide (#18823)
This commit is contained in:
g-samroberts
@@ -29,10 +29,9 @@ Learn all about Gemini CLI in our [documentation](https://geminicli.com/docs/).
|
||||
|
||||
## 📦 Installation
|
||||
|
||||
### Pre-requisites before installation
|
||||
|
||||
- Node.js version 20 or higher
|
||||
- macOS, Linux, or Windows
|
||||
See
|
||||
[Gemini CLI installation, execution, and releases](./docs/get-started/installation.md)
|
||||
for recommended system specifications and a detailed installation guide.
|
||||
|
||||
### Quick Install
|
||||
|
||||
|
||||
@@ -1,43 +1,98 @@
|
||||
# Gemini CLI installation, execution, and deployment
|
||||
# Gemini CLI installation, execution, and releases
|
||||
|
||||
Install and run Gemini CLI. This document provides an overview of Gemini CLI's
|
||||
installation methods and deployment architecture.
|
||||
This document provides an overview of Gemini CLI's sytem requriements,
|
||||
installation methods, and release types.
|
||||
|
||||
## How to install and/or run Gemini CLI
|
||||
## Recommended system specifications
|
||||
|
||||
There are several ways to run Gemini CLI. The recommended option depends on how
|
||||
you intend to use Gemini CLI.
|
||||
- **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 or Zsh
|
||||
- **Location:**
|
||||
[Gemini Code Assist supported locations](https://developers.google.com/gemini-code-assist/resources/available-locations#americas)
|
||||
- **Internet connection required**
|
||||
|
||||
- As a standard installation. This is the most straightforward method of using
|
||||
Gemini CLI.
|
||||
## Install Gemini CLI
|
||||
|
||||
We recommend most users install Gemini CLI using one of the following
|
||||
installation methods:
|
||||
|
||||
- npm
|
||||
- Homebrew
|
||||
- MacPorts
|
||||
- Anaconda
|
||||
|
||||
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).
|
||||
|
||||
### Install globally with npm
|
||||
|
||||
```bash
|
||||
npm install -g @google/gemini-cli
|
||||
```
|
||||
|
||||
### Install globally with Homebrew (macOS/Linux)
|
||||
|
||||
```bash
|
||||
brew install gemini-cli
|
||||
```
|
||||
|
||||
### Install globally with MacPorts (macOS)
|
||||
|
||||
```bash
|
||||
sudo port install gemini-cli
|
||||
```
|
||||
|
||||
### 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
|
||||
```
|
||||
|
||||
## 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](/docs/cli/cli-reference.md).
|
||||
|
||||
You can also run Gemini CLI using one of the following advanced methods:
|
||||
|
||||
- Run instantly with npx. You can run Gemini CLI without permanent installation.
|
||||
- In a sandbox. This method offers increased security and isolation.
|
||||
- From the source. This is recommended for contributors to the project.
|
||||
|
||||
### 1. Standard installation (recommended for standard users)
|
||||
### Run instantly with npx
|
||||
|
||||
This is the recommended way for end-users to install Gemini CLI. It involves
|
||||
downloading the Gemini CLI package from the NPM registry.
|
||||
```bash
|
||||
# Using npx (no installation required)
|
||||
npx @google/gemini-cli
|
||||
```
|
||||
|
||||
- **Global install:**
|
||||
You can also execute the CLI directly from the main branch on GitHub, which is
|
||||
helpful for testing features still in development:
|
||||
|
||||
```bash
|
||||
npm install -g @google/gemini-cli
|
||||
```
|
||||
```bash
|
||||
npx https://github.com/google-gemini/gemini-cli
|
||||
```
|
||||
|
||||
Then, run the CLI from anywhere:
|
||||
|
||||
```bash
|
||||
gemini
|
||||
```
|
||||
|
||||
- **NPX execution:**
|
||||
|
||||
```bash
|
||||
# Execute the latest version from NPM without a global install
|
||||
npx @google/gemini-cli
|
||||
```
|
||||
|
||||
### 2. Run in a sandbox (Docker/Podman)
|
||||
### Run in a sandbox (Docker/Podman)
|
||||
|
||||
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.
|
||||
@@ -56,7 +111,7 @@ the default way that the CLI executes tools that might have side effects.
|
||||
gemini --sandbox -y -p "your prompt here"
|
||||
```
|
||||
|
||||
### 3. Run from source (recommended for Gemini CLI contributors)
|
||||
### Run from source (recommended for Gemini CLI contributors)
|
||||
|
||||
Contributors to the project will want to run the CLI directly from the source
|
||||
code.
|
||||
@@ -79,63 +134,41 @@ code.
|
||||
gemini
|
||||
```
|
||||
|
||||
---
|
||||
## Releases
|
||||
|
||||
### 4. Running the latest Gemini CLI commit from GitHub
|
||||
Gemini CLI has three release channels: nightly, preview, and stable. For most
|
||||
users, we recommend the stable release, which is the default installation.
|
||||
|
||||
You can run the most recently committed version of Gemini CLI directly from the
|
||||
GitHub repository. This is useful for testing features still in development.
|
||||
### Stable
|
||||
|
||||
New stable releases are published each week. The stable release is the promotion
|
||||
of last week's `preview` release along with any bug fixes. The stable release
|
||||
uses `latest` tag, but omitting the tag also installs the latest stable release
|
||||
by default:
|
||||
|
||||
```bash
|
||||
# Execute the CLI directly from the main branch on GitHub
|
||||
npx https://github.com/google-gemini/gemini-cli
|
||||
# Both commands install the latest stable release.
|
||||
npm install -g @google/gemini-cli
|
||||
npm install -g @google/gemini-cli@latest
|
||||
```
|
||||
|
||||
## Deployment architecture
|
||||
### Preview
|
||||
|
||||
The execution methods described above are made possible by the following
|
||||
architectural components and processes:
|
||||
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:
|
||||
|
||||
**NPM packages**
|
||||
```bash
|
||||
npm install -g @google/gemini-cli@preview
|
||||
```
|
||||
|
||||
Gemini CLI project is a monorepo that publishes two core packages to the NPM
|
||||
registry:
|
||||
### Nightly
|
||||
|
||||
- `@google/gemini-cli-core`: The backend, handling logic and tool execution.
|
||||
- `@google/gemini-cli`: The user-facing frontend.
|
||||
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:
|
||||
|
||||
These packages are used when performing the standard installation and when
|
||||
running Gemini CLI from the source.
|
||||
|
||||
**Build and packaging processes**
|
||||
|
||||
There are two distinct build processes used, depending on the distribution
|
||||
channel:
|
||||
|
||||
- **NPM publication:** For publishing to the NPM registry, the TypeScript source
|
||||
code in `@google/gemini-cli-core` and `@google/gemini-cli` is transpiled into
|
||||
standard JavaScript using the TypeScript Compiler (`tsc`). The resulting
|
||||
`dist/` directory is what gets published in the NPM package. This is a
|
||||
standard approach for TypeScript libraries.
|
||||
|
||||
- **GitHub `npx` execution:** When running the latest version of Gemini CLI
|
||||
directly from GitHub, a different process is triggered by the `prepare` script
|
||||
in `package.json`. This script uses `esbuild` to bundle the entire application
|
||||
and its dependencies into a single, self-contained JavaScript file. This
|
||||
bundle is created on-the-fly on the user's machine and is not checked into the
|
||||
repository.
|
||||
|
||||
**Docker sandbox image**
|
||||
|
||||
The Docker-based execution method is supported by the `gemini-cli-sandbox`
|
||||
container image. This image is published to a container registry and contains a
|
||||
pre-installed, global version of Gemini CLI.
|
||||
|
||||
## Release process
|
||||
|
||||
The release process is automated through GitHub Actions. The release workflow
|
||||
performs the following actions:
|
||||
|
||||
1. Build the NPM packages using `tsc`.
|
||||
2. Publish the NPM packages to the artifact registry.
|
||||
3. Create GitHub releases with bundled assets.
|
||||
```bash
|
||||
npm install -g @google/gemini-cli@nightly
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user