diff --git a/stubs/README.md b/stubs/README.md
new file mode 100644
index 00000000000..2c353d7818d
--- /dev/null
+++ b/stubs/README.md
@@ -0,0 +1,11 @@
+# Metaflow Stubs
+
+This package contains stub files for `metaflow` and thus offers type hints for various editors (such as `VSCode`) and language servers (such as `Pylance`).
+
+## Installation
+
+To install Metaflow Stubs in your local environment, you can install from [PyPi](https://pypi.org/project/metaflow/):
+
+```sh
+pip install metaflow-stubs
+```
diff --git a/stubs/setup.py b/stubs/setup.py
index 894eb717cc1..559837fef9b 100644
--- a/stubs/setup.py
+++ b/stubs/setup.py
@@ -8,6 +8,8 @@
     name="metaflow-stubs",
     version=version,
     description="Metaflow Stubs: Stubs for the metaflow package",
+    long_description=open("README.md").read(),
+    long_description_content_type="text/markdown",
     author="Metaflow Developers",
     author_email="help@metaflow.org",
     license="Apache Software License",