diff --git a/python/frameworks/fastapi.html.markerb b/python/frameworks/fastapi.html.markerb
index 42ed61848b..427409b41a 100644
--- a/python/frameworks/fastapi.html.markerb
+++ b/python/frameworks/fastapi.html.markerb
@@ -24,7 +24,6 @@ Deploying a FastAPI app on Fly.io is... well it's fast! You can be up and runnin
 
 <%= partial "/docs/python/partials/poetry_new", locals: { runtime: "FastAPI" }  %>
 
-
 Then we have to add the FastAPI dependency:
 
 ```cmd
diff --git a/python/partials/_poetry_new.erb b/python/partials/_poetry_new.erb
index 8e8a7cdb96..b3cda158d1 100644
--- a/python/partials/_poetry_new.erb
+++ b/python/partials/_poetry_new.erb
@@ -1,9 +1,11 @@
-For managing our project, we use [Poetry](https://python-poetry.org/). 
+For managing our project, we use [Poetry](https://python-poetry.org/).
 For more information on the initial setup with poetry, refer to [setting up a python environment](/docs/python/the-basics/initial-setup).
+
 We can initialize a new project like so:
 
 ```cmd
 poetry new <%= runtime.downcase %>-app
 cd <%= runtime.downcase %>-app
-poetry shell
-```
\ No newline at end of file
+```
+
+<div class="callout">If you're using Poetry 2.0+ (the default when installed via `pipx`), the `poetry shell` command is no longer built in. Use `poetry run` to run commands (e.g., `poetry run python main.py`), or activate the environment with `poetry env activate`. See the [initial setup guide](/docs/python/the-basics/initial-setup) for more details.</div>
diff --git a/python/the-basics/initial-setup.html.md b/python/the-basics/initial-setup.html.md
index 1236a65bdb..1bc4dfeaf0 100644
--- a/python/the-basics/initial-setup.html.md
+++ b/python/the-basics/initial-setup.html.md
@@ -17,7 +17,7 @@ We recommend the latest [supported versions](https://devguide.python.org/version
 
 ## Dependency Management
 
-For project and dependency management we use [Poetry](https://python-poetry.org/). Like most package managers, Poetry combines multiple tools in one. 
+For project and dependency management we use [Poetry](https://python-poetry.org/). Like most package managers, Poetry combines multiple tools in one.
 
 You have other options:
 - [venv](https://docs.python.org/3/library/venv.html) and [pip](https://pip.pypa.io/)
@@ -25,7 +25,7 @@ You have other options:
 - [pyenv](https://github.com/pyenv/pyenv)
 - [pip-tools](https://pypi.org/project/pip-tools/)
 
-If you are just starting out, it is easiest to follow along using `poetry`. 
+If you are just starting out, it is easiest to follow along using `poetry`.
 After installing it, you will have to set 2 flags for virtual environment management.
 
 ```cmd
@@ -33,7 +33,7 @@ poetry config virtualenvs.create true
 poetry config virtualenvs.in-project true
 ```
 
-This will make your development environment resemble what ends up happening inside the docker image. 
+This will make your development environment resemble what ends up happening inside the Docker image.
 
 You can create a new project using this command:
 
@@ -47,7 +47,7 @@ Once inside the project, you can add packages with the add command:
 poetry add <dep>
 ```
 
-This will automatically create a virtual environment for you. 
+This will automatically create a virtual environment for you.
 
 To interact with your virtual environment, you can prefix your commands with `poetry run`:
 
@@ -58,7 +58,14 @@ poetry run python main.py
 Alternatively, you can activate the environment:
 
 ```cmd
-poetry shell
+poetry env activate
+```
+
+This prints the activation command for your shell. To activate in one step:
+
+```cmd
+source $(poetry env activate)
 python main.py
 ```
 
+<div class="callout">If you're using Poetry 2.0+ (the default when installed via `pipx`), the `poetry shell` command is no longer built in. Use `poetry run` (recommended) or `poetry env activate` as shown above. If you prefer `poetry shell`, you can install it as a plugin: `poetry self add poetry-plugin-shell`.</div>