If a Gemini tutorial imports google.generativeai or vertexai.generative_models, first identify which SDK generation it describes. The maintained Google Gen AI Python package is google-genai, imported with from google import genai. It supports both the Gemini Developer API and Google Cloud’s Gemini interface. Credentials, project configuration and model availability still depend on the backend you choose.
This guide was source-checked on October 25, 2026. The package version checked was google-genai 2.33.0, which requires Python 3.10 or newer. Examples use a model ID supplied by the reader instead of embedding a model name that may retire. Configuration and Python syntax were checked offline; this is not a claim of successful paid API execution.
Identify the library before changing code
| Pattern in an older example | What to check now |
|---|---|
pip install google-generativeai | The legacy Gemini Developer API library. Google’s migration guide recommends the Google Gen AI SDK. |
import google.generativeai as genai | The older module layout. Current examples use from google import genai. |
from vertexai.generative_models import GenerativeModel | The deprecated generative module in the Vertex AI SDK; later SDK releases omit it. |
genai.Client(...) and client.models.generate_content(...) | The current client-based SDK shape. Confirm the installed version and selected backend. |
Google’s Vertex SDK migration guide states that the old generative modules are absent from SDK releases after June 24, 2026. This is a migration of those modules, not a statement that every feature in google-cloud-aiplatform has disappeared. The separate Gemini migration guide covers the Developer API’s older libraries.
Start with a clean environment
Check the Python interpreter and package in the same environment that runs your program. A successful install in one virtual environment will not repair a different interpreter selected by an editor or notebook.
python --version
python -m venv .venv
# Activate the environment using the command for your shell.
python -m pip install "google-genai==2.33.0"
python -m pip show google-genai
The version pin records the version checked for this example; it is not an instruction to ignore future security or compatibility updates. Review the current release notes before upgrading. Avoid naming your own file google.py or genai.py when diagnosing an import problem: local files can obscure the package you intended to import.
Choose the backend explicitly
The official SDK documentation describes both client modes. For the Developer API, use the credential appropriate to that API. For Google Cloud, configure the project, location, enabled service and authorized identity appropriate to your deployment. Do not copy a project or credential from an unrelated account simply because an example needs one.
import os
from google import genai
def developer_client():
return genai.Client(api_key=os.environ["GEMINI_API_KEY"])
def cloud_client():
return genai.Client(
vertexai=True,
project=os.environ["GOOGLE_CLOUD_PROJECT"],
location=os.environ["GOOGLE_CLOUD_LOCATION"],
)
The Cloud client uses the authentication supported by the SDK and environment. A development login, a deployed service identity and a downloaded service-account key are different mechanisms. A tutorial should not tell every reader to create an administrator key as a prerequisite for a text-generation example. Grant the access required for the actual workload and follow the provider’s authentication documentation.
Pass system instructions in generation configuration
With the current Python SDK, system instructions belong in GenerateContentConfig.system_instruction. They are separate from the user’s question. Putting a made-up role="system" into an ordinary content item is not a substitute for using the documented configuration field.
import os
from google.genai import types
def ask(client, question):
config = types.GenerateContentConfig(
system_instruction=(
"Explain the answer clearly. State missing information. "
"Do not claim that an example was tested."
),
max_output_tokens=512,
)
result = client.models.generate_content(
model=os.environ["GEMINI_MODEL"],
contents=question,
config=config,
)
return result.text
Set GEMINI_MODEL to a model that your chosen backend currently offers for this operation. The function makes a real, potentially billable request when called. The configuration object alone does not perform a request. Keep the system instruction on every independent call that needs it; do not assume that a previous unrelated request changed the model permanently.
Instructions influence behavior; they do not establish that an answer is factually correct, authorized or safe to execute. For application rules, also validate outputs and enforce permissions in application code. A prompt that says “use only approved data” is not an access-control boundary.
To check that local boundary first, download the Ithy offline configuration check. It imports the pinned SDK, constructs a client with a deliberately invalid example key and validates generation and Live configuration objects while blocking network connections. We ran that check with version 2.33.0. It checks no real credential and makes no model request; successful authentication and output still require a separate authorized test.
Using LangChain: check the integration version too
LangChain’s current ChatGoogleGenerativeAI documentation says that version 4.0.0 moved its integration to the consolidated Google Gen AI SDK and supports the Developer API and the Google Cloud backend. It supersedes certain Gemini classes in langchain-google-vertexai. That statement does not imply that all older integrations or every Cloud model share one migration path.
import os
from langchain_google_genai import ChatGoogleGenerativeAI
model = ChatGoogleGenerativeAI(model=os.environ["GEMINI_MODEL"])
reply = model.invoke([
("system", "Explain the result and identify missing information."),
("human", "What information would you need to compare two laptops?"),
])
This is the wrapper’s message interface, rather than a claim that the underlying SDK accepts an arbitrary system-role content object. Configure the backend and credentials according to the integration version you actually install. The original SDK example above and the wrapper example are alternatives; stacking two clients is unnecessary for a single request.
Diagnose a failure by its boundary
| Symptom | First check | What it does not establish |
|---|---|---|
| Import fails | Interpreter, installed distribution and local module names. | That the remote API or your account is unavailable. |
| A field is rejected | SDK version and the documented configuration type. | That changing the wording of the user prompt will fix the schema. |
| Authentication or permission error | Selected backend, identity, project and allowed operation. | That a different model name will grant access. |
| Model not found or unsupported operation | The provider’s current model availability for that backend and method. | That a model with a similar name supports the same method. |
| The answer ignores an instruction | The submitted configuration and the model’s actual output. | That a system instruction is an enforceable guarantee. |
Keep a minimal reproduction with synthetic input. Record the package version, backend, operation and error category. Remove keys, authorization headers, private prompts and customer data before sharing it. Reproduce the failing boundary before changing several dependencies at once.
A migration checklist you can actually verify
- Identify the old import and installed package.
- Select one backend and confirm an appropriate model is available.
- Move request configuration into the documented current type.
- Test imports and configuration construction independently from a network call.
- Run a small authorized request in your own environment and inspect its output.
- Test streaming, tools or structured output separately if your application uses them.
A successful text example does not prove that streaming, function calling, safety settings or Live API sessions work in the same application. The Live API guide explains the separate authentication, audio and connection boundaries.
