Install & Compatibility
Where this runs
No compatibility data collected yet for this library.
Code
Verified usage
The `dagster-webserver` is typically launched via the `dagster dev` or `dg dev` command-line interface, which starts both the webserver and the Dagster daemon for local development. After installing, create a simple Dagster asset definition in a Python file (e.g., `definitions.py`) and then run `dagster dev -f definitions.py` from your project directory. This will make the UI accessible in your browser, usually at `http://localhost:3000`.
# 1. Create a directory for your project, e.g., `my_dagster_project`
# 2. Inside `my_dagster_project`, create a file named `definitions.py`:
# definitions.py
from dagster import Definitions, asset
@asset
def hello_world():
"""A simple asset that prints a message."""
print("Hello, Dagster!")
defs = Definitions(assets=[hello_world])
# 3. From the `my_dagster_project` directory, run the Dagster webserver:
# (Ensure you have `dagster-webserver` installed in your environment)
# The `dagster dev` command will launch both the webserver and the daemon.
# It will serve the Dagster UI at http://localhost:3000.
# You can also specify the file with -f definitions.py
# If you create a workspace.yaml file, you can run 'dagster dev' without arguments.
# For this quickstart, running `dagster dev -f definitions.py` in the project root is sufficient.
# To run in terminal:
# cd my_dagster_project
# dagster dev -f definitions.py
dagster-webserver --version
Debug
Known issues
breakingDagster has dropped support for Python 3.9, which has reached its end-of-life. The minimum supported Python version is now 3.10. Projects on older Python versions will need to upgrade.fixUpgrade your Python environment to 3.10 or higher. Ensure your `requires_python` in `pyproject.toml` or `setup.py` reflects this.
affects: >=1.12.0
breakingThe core `dagster` package (and by extension, `dagster-webserver`) now requires `pydantic>=2`. This may cause conflicts with existing environments or projects that depend on an older `pydantic` version.fixUpdate your `pydantic` dependency to version 2 or higher. Carefully review any code relying on `pydantic` V1 features if upgrading.
affects: >=1.12.0
gotcha`psycopg2-binary` has been removed as a direct dependency from `dagster-postgres` as of `dagster` 1.12.18. If your project uses `dagster-postgres` and implicitly relied on `psycopg2-binary` being installed, you will now need to explicitly add `psycopg2-binary` (or `psycopg2`) to your project's dependencies. Note that `psycopg2-binary` is generally discouraged for production environments due to its pre-compiled nature.fixExplicitly add `pip install psycopg2-binary` or `pip install psycopg2` to your project's dependencies if using `dagster-postgres`.
affects: >=1.12.18
gotchaA bug in `dagster-webserver` versions prior to 1.12.17 caused the Dagster UI to fail to load due to issues with the built webapp inclusion. Users on these specific versions would experience a non-functional UI.fixUpgrade `dagster-webserver` to version 1.12.17 or later to resolve the UI loading issue.
affects: <1.12.17
deprecatedThe `dagster dev` command is being superseded by `dg dev` for starting a local development deployment (webserver and daemon). While `dagster dev` still works, `dg dev` is the recommended new CLI command.fixPrefer `dg dev` over `dagster dev` when launching your local Dagster environment.
affects: All versions where `dg dev` is available.
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'your_module_name'
The Dagster webserver cannot find or import your user code module, usually because the Python environment where `dagster-webserver` is running does not have your code installed or the `PYTHONPATH` is not correctly configured.
fixEnsure your code is installed as an editable package (e.g., `pip install -e .` from your project's root) or that the directory containing your module is added to the `PYTHONPATH` environment variable. Also, verify that the module name provided to `dagster-webserver` (e.g., via `-m` or `workspace.yaml`) is correct.
PermissionError: [Errno 13] Permission denied
This error, particularly on Windows when running `dagster dev`, often occurs due to file permission issues or conflicts when Dagster tries to create or access temporary files.
fixTry running `dagster dev --use-legacy-code-server-behavior` as a workaround. If the issue persists, check that the user running Dagster has appropriate permissions for the temporary directory (often in `AppData\Local\Temp` on Windows) and ensure no other processes are locking the files. Downgrading Dagster to a slightly older version (e.g., `1.9.9` if on `1.9.10`) has also been noted as a temporary solution for specific version-related bugs.
DagsterUserCodeUnreachableError: Could not reach the user code server. gRPC Error code: UNAVAILABLE
The Dagster webserver or daemon is unable to establish a gRPC connection with the user code server that hosts your assets and jobs. This can be due to network issues, the code server crashing, or taking too long to start.
fixVerify that your user code server is running and accessible. Check the logs of both the webserver and the user code server for more specific errors. Increase the `code_servers.local_startup_timeout` in your `dagster.yaml` if your code takes a long time to load. In Kubernetes deployments, ensure proper service networking and consider enabling TCP keepalives to prevent idle connection drops.
Loading chunk X failed.
This UI error, often seen in the browser console, indicates that the Dagster UI failed to load necessary JavaScript or HTML chunks. This can happen if webserver assets are stale or cached incorrectly, or if there's a problem serving the UI files.
fixRestart the `dagster-webserver` to clear any stale caches. Try accessing the UI in an incognito window or clear your browser's cache. If running with a path prefix (e.g., in a reverse proxy setup), ensure the `--path-prefix` argument for `dagster-webserver` is correctly configured.
Error: The dagster-webserver Python package must be installed in order to use the dagster dev command.
Although `dagster dev` is a common command, it explicitly requires the `dagster-webserver` package to be installed in the current Python environment to launch the UI.
fixInstall the `dagster-webserver` package using `pip install dagster-webserver` within your active Python environment. If using `conda`, ensure it's installed in the activated `conda` environment.
Upgrade
Version history
1.12.22latest on PyPI · released Apr 2, 2026
Audit
Dependencies
dagsterrequiredCore Dagster library, providing the underlying data orchestration framework and APIs that the webserver interacts with.
pydantic>=2requiredRequired by the core `dagster` package as of recent versions, may cause conflicts with older Pydantic installations.
psycopg2-binaryoptionalFormerly a transitive dependency of `dagster-postgres`, now requires explicit installation if `dagster-postgres` is used. Often discouraged for production use.