diff --git a/python/frameworks/fastapi.html.markerb b/python/frameworks/fastapi.html.markerb
index 42ed61848b..f15eb4f70e 100644
--- a/python/frameworks/fastapi.html.markerb
+++ b/python/frameworks/fastapi.html.markerb
@@ -24,13 +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
-poetry add "fastapi[standard]"
-```
-
 Now, let's create a simple FastAPI app in `main.py`:
 
 ```python
diff --git a/python/partials/_poetry_new.erb b/python/partials/_poetry_new.erb
index 8e8a7cdb96..ae805bc369 100644
--- a/python/partials/_poetry_new.erb
+++ b/python/partials/_poetry_new.erb
@@ -1,9 +1,40 @@
 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:
 
+**Note:** If you're using Poetry 2.0+, the `poetry shell` command is not available by default. 
+This guide uses `poetry run` to execute commands, which works with all Poetry versions.
+
+We can initialize a new project like so:
 ```cmd
 poetry new <%= runtime.downcase %>-app
 cd <%= runtime.downcase %>-app
-poetry shell
+```
+
+This creates a basic project structure. For Fly.io deployment, ensure your `pyproject.toml` uses the Poetry format with dependencies under `[tool.poetry.dependencies]`:
+```cmd
+[tool.poetry]
+name = "<%= runtime.downcase %>-app"
+version = "0.1.0"
+description = ""
+authors = ["Your Name <you@example.com>"]
+readme = "README.md"
+
+[tool.poetry.dependencies]
+python = "^3.10"
+fastapi = {extras = ["standard"], version = "^0.115.0"}
+
+[build-system]
+requires = ["poetry-core>=2.0.0"]
+build-backend = "poetry.core.masonry.api"
+```
+
+Then we have to add the FastAPI dependency if it's not already included:
+
+```cmd
+poetry add "fastapi[standard]"
+```
+
+To run commands, use `poetry run`:
+```cmd
+poetry run uvicorn <%= runtime.downcase %>_app.main:app --reload
 ```
\ No newline at end of file
diff --git a/python/the-basics/initial-setup.html.md b/python/the-basics/initial-setup.html.md
index 1236a65bdb..a87107fe2a 100644
--- a/python/the-basics/initial-setup.html.md
+++ b/python/the-basics/initial-setup.html.md
@@ -1,8 +1,11 @@
 ---
 title: "Setting up a Python Environment"
 layout: framework_docs
+fly_content_type: guide
+fly_framework: python
 objective: How to setup a functional python environment on your local machine.
 order: 0
+
 ---
 
 ## Initial Local Setup
@@ -50,15 +53,14 @@ poetry add <dep>
 This will automatically create a virtual environment for you. 
 
 To interact with your virtual environment, you can prefix your commands with `poetry run`:
-
 ```cmd
 poetry run python main.py
 ```
 
 Alternatively, you can activate the environment:
-
 ```cmd
-poetry shell
+poetry env activate
 python main.py
 ```
 
+**Note:** If you're using Poetry 2.0+ (the default when installed with `pipx`), the `poetry shell` command is not available by default. Use `poetry run` (recommended) or `poetry env activate` instead. If you need `poetry shell`, you can install it as a plugin: `poetry self add poetry-plugin-shell`