diff --git a/README.md b/README.md
index ebd8238..2e1d12a 100644
--- a/README.md
+++ b/README.md
@@ -35,6 +35,19 @@ You can also pass `text_path` or `audio_path` to `model.get_events_dataframe` 
 
 For a full walkthrough with brain visualizations, see the [Colab demo notebook](https://colab.research.google.com/github/facebookresearch/tribev2/blob/main/tribe_demo.ipynb).
 
+## Requirements
+
+- Python 3.11+
+- Recommended: a dedicated virtual environment (e.g., conda)
+- For video/audio processing, ensure `ffmpeg` is installed and available on your PATH
+- Some components (e.g., the text encoder) require access to gated Hugging Face models
+
+## Common setup issues
+
+- If media loading fails, check that `ffmpeg` is installed (`brew install ffmpeg` on macOS).
+- If Hugging Face model downloads fail, ensure you are logged in with `huggingface-cli login` and have access to required models.
+- If dependencies are missing after creating a fresh environment, reinstall them with `pip install -e .`
+
 ## Installation
 
 **Basic** (inference only):