diff --git a/Makefile b/Makefile
index 2d7b207a9..0c02b9c46 100644
--- a/Makefile
+++ b/Makefile
@@ -4,6 +4,9 @@ CI_DIR=./ci
 CI_ENVIRONMENT_CONDA_DEFAULT_FILE=$(CI_DIR)/environment-conda-default.txt
 CI_ENVIRONMENT_CONDA_FORGE_FILE=$(CI_DIR)/environment-conda-forge.txt
 
+DOC_DIR=./doc
+DOC_ENVIRONMENT_CONDA_FILE=$(DOC_DIR)/environment.yml
+
 
 ifndef CONDA_PREFIX
 $(error Conda not active, please install conda and then activate it using \`conda activate\`))
@@ -93,8 +96,10 @@ $(VENV_DIR):  $(CI_ENVIRONMENT_CONDA_DEFAULT_FILE) $(CI_ENVIRONMENT_CONDA_FORGE_
 	# Install development setup
 	$(VENV_DIR)/bin/pip install -e .[tests,deploy]
 	# install docs requirements
-	cd doc; $(VENV_DIR)/bin/pip install -r requirements.txt
-	touch $(VENV_DIR)
+	# --name $(CONDA_DEFAULT_ENV) ensures we install in active environment (check at
+	# top of Makefile ensures that environment is not the base one)
+	$(CONDA_EXE) env update --name $(CONDA_DEFAULT_ENV) --file $(DOC_ENVIRONMENT_CONDA_FILE)
+# 	touch $(VENV_DIR)
 
 .PHONY: release-on-conda
 release-on-conda:  ## release pyam on conda
diff --git a/ci/environment-conda-forge.txt b/ci/environment-conda-forge.txt
index 097c3cb52..48f6642e2 100644
--- a/ci/environment-conda-forge.txt
+++ b/ci/environment-conda-forge.txt
@@ -1,5 +1,5 @@
 freetype=2.9.1
-matplotlib==3.0.3
+matplotlib==3.0.2
 matplotlib-base==3.0.3
 seaborn==0.9.0
 gdal
diff --git a/doc/README.md b/doc/README.md
index 8cf9c37e8..c096e1ef3 100644
--- a/doc/README.md
+++ b/doc/README.md
@@ -8,11 +8,7 @@ in the source code.
 Dependencies
 ------------
 
-1. `Sphinx <http://sphinx-doc.org/>`_ v1.1.2 or higher
-2. `sphinxcontrib.bibtex`
-3. `sphinxcontrib-fulltoc`
-4. `numpydoc`
-5. `cloud_sptheme`
+These can be found in ``environment.yml``.
 
 Writing in Restructed Text
 --------------------------
diff --git a/doc/environment.yml b/doc/environment.yml
index 96d9df1c5..95ff3984f 100644
--- a/doc/environment.yml
+++ b/doc/environment.yml
@@ -1,8 +1,8 @@
-name: pyam-docs
 channels:
   - oggm
 dependencies:
   - oggm-deps
+  - pip
   - pip:
     - ipython==7.2.0
     - matplotlib==3.0.2
diff --git a/doc/requirements.txt b/doc/requirements.txt
deleted file mode 100644
index 469ac28fc..000000000
--- a/doc/requirements.txt
+++ /dev/null
@@ -1,13 +0,0 @@
-sphinx
-sphinxcontrib-bibtex
-sphinxcontrib-fulltoc
-sphinxcontrib-programoutput
-sphinx-gallery
-nbsphinx
-numpydoc
-cloud_sptheme
-nbformat
-ipython
-jupyter
-jupyter_contrib_nbextensions
-pillow
diff --git a/doc/source/conf.py b/doc/source/conf.py
index 88c3ac99f..2b8d6810d 100644
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -12,6 +12,10 @@
 # All configuration values have a default; values that are commented out
 # serve to show the default.
 
+# has to go first for environment setup reasons
+import matplotlib
+matplotlib.use('agg')
+
 from datetime import datetime
 import pyam
 
diff --git a/doc/source/install.rst b/doc/source/install.rst
index 925dc2724..cc69ddb57 100644
--- a/doc/source/install.rst
+++ b/doc/source/install.rst
@@ -40,11 +40,11 @@ fully enumerated below.
 
 The required depedencies for |pyam| are:
 
-  .. program-output:: python -c 'import sys; sys.path.append("../.."); import setup; print("\n".join([r for r in setup.REQUIREMENTS]))'
+  .. program-output:: python -c 'import sys; sys.path.insert(0, "../.."); from setup import REQUIREMENTS; print("\n".join([r for r in REQUIREMENTS]))'
 
 The depedencies for building this documentation are:
 
-  .. include:: ../requirements.txt
+  .. include:: ../environment.yml
 	  :start-line: 0
 	  :literal:
 
diff --git a/setup.py b/setup.py
index fc069e925..cc30ca643 100755
--- a/setup.py
+++ b/setup.py
@@ -26,7 +26,7 @@
     'PyYAML',
     'xlrd',
     'xlsxwriter',
-    'matplotlib',
+    'matplotlib<=3.0.2',
     'seaborn',
     'six',
 ]