[Bug]: Static assets return 404 when installed via uv on Windows

[kbzsl]

Component

Server (server.*)

Severity

P2 - Medium (workaround exists)

Shiny Version

1.6.1

Python Version

3.12.11 and 3.13.5

Minimal Reproducible Example

from shiny.express import input, render, ui

ui.page_opts(title="Test")

with ui.sidebar():
    ui.input_action_button("btn", "Click me")

@render.text
def result():
    return f"Clicked {input.btn()} times"

Behavior

Description

When shiny is installed via uv (default settings) on Windows, all static assets (/lib/bootstrap-5.3.1/..., /lib/shiny-1.6.1/shiny.js, etc.) return 404. The HTML page renders but has no CSS, no JavaScript, and no interactivity.

Steps to Reproduce

1. Create a new project with uv init
2. uv add shiny
3. uv sync
4. Create a minimal Shiny Express app:

from shiny.express import input, render, ui

ui.page_opts(title="Test")

with ui.sidebar():
    ui.input_action_button("btn", "Click me")

@render.text
def result():
    return f"Clicked {input.btn()} times"

5. uv run shiny run app.py
6. Open http://127.0.0.1:8000 — page has no styling, button doesn't work

Expected Behavior

Static assets load correctly and the app is fully interactive.

Workaround

Add to pyproject.toml:

[tool.uv]
link-mode = "copy"

Then run:

uv sync --reinstall

Error Messages (if any)

PS > uv run shiny run .\app.py

INFO:     Started server process [29932]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
INFO:     127.0.0.1:50477 - "GET / HTTP/1.1" 200 OK
INFO:     127.0.0.1:50477 - "GET /lib/requirejs-2.3.6/require.min.js HTTP/1.1" 404 Not Found
INFO:     127.0.0.1:57875 - "GET /lib/jquery-3.6.0/jquery-3.6.0.min.js HTTP/1.1" 404 Not Found
INFO:     127.0.0.1:56154 - "GET /lib/shiny-1.6.1/shiny.js HTTP/1.1" 404 Not Found
INFO:     127.0.0.1:60520 - "GET /lib/shiny-busy-indicators-1.6.1/busy-indicators.css HTTP/1.1" 404 Not Found
INFO:     127.0.0.1:60632 - "GET /lib/bootstrap-5.3.1/bootstrap.min.css HTTP/1.1" 404 Not Found
INFO:     127.0.0.1:62991 - "GET /lib/bootstrap-5.3.1/bootstrap.bundle.min.js HTTP/1.1" 404 Not Found
INFO:     127.0.0.1:50477 - "GET /lib/htmltools-fill-0.5.9.9000/fill.css HTTP/1.1" 404 Not Found
INFO:     127.0.0.1:57875 - "GET /lib/bslib-components-0.10.0.9000/components.min.js HTTP/1.1" 404 Not Found
INFO:     127.0.0.1:56154 - "GET /lib/bslib-components-0.10.0.9000/web-components.min.js HTTP/1.1" 404 Not Found
INFO:     127.0.0.1:60520 - "GET /lib/ionrangeslider-2.3.1/js/ion.rangeSlider.min.js HTTP/1.1" 404 Not Found
INFO:     127.0.0.1:60632 - "GET /lib/strftime-0.9.2/strftime-min.js HTTP/1.1" 404 Not Found
INFO:     127.0.0.1:62991 - "GET /lib/bootstrap-datepicker-1.9.0/js/bootstrap-datepicker.min.js HTTP/1.1" 404 Not Found
INFO:     127.0.0.1:50477 - "GET /lib/selectize-0.12.6/js/selectize.min.js HTTP/1.1" 404 Not Found
INFO:     127.0.0.1:57875 - "GET /lib/selectize-0.12.6/accessibility/js/selectize-plugin-a11y.min.js HTTP/1.1" 404 Not Found
INFO:     127.0.0.1:57875 - "GET /favicon.ico HTTP/1.1" 404 Not Found

Environment

- OS: Windows 11
- Python: 3.12.11 and 3.13.5
- shiny: 1.6.1
- starlette: 1.0.0
- uv: 0.11.11

[jshaofa-ui]

Root Cause Analysis & Proposed Fix

Root Cause

When uv installs packages on Windows, it uses symlink mode by default (instead of copying files). The Python package files in .venv/Lib/site-packages/shiny/ are symlinks pointing to uv's global cache.

Shiny's StaticFiles (wrapping Starlette's StaticFiles) receives paths like:

C:\Users\...\.venv\Lib\site-packages\shiny\www\shared\bootstrap\

On Windows, Starlette's StaticFiles uses os.path.isfile() / pathlib.Path.is_file() to validate file existence before serving. Symlinked directories on Windows don't resolve correctly in certain Python/Starlette versions, causing all static asset requests to return 404.

Fix

In shiny/_app.py, resolve symlinks before passing the source path to StaticFiles:

# Line ~470, change:
StaticFiles(directory=paths["source"]),

# To:
from pathlib import Path
StaticFiles(directory=str(Path(paths["source"]).resolve())),

Similarly, in create_static_asset_route() (line ~566):

# Change:
StaticFiles(directory=static_asset_path),

# To:
StaticFiles(directory=str(static_asset_path.resolve())),

And in the __shared mount (line ~249):

# Change:
app=StaticFiles(directory=shared_dir),

# To:
app=StaticFiles(directory=str(Path(shared_dir).resolve())),

Why Path.resolve() works

• Path.resolve() follows symlinks and returns the canonical absolute path
• On Windows with uv's symlink mode, this converts the symlinked .venv/Lib/site-packages/shiny/ path to the actual uv cache location where files physically exist
• Starlette's StaticFiles can then correctly find and serve the files

Files to Modify

1. shiny/_app.py — 3 locations (lines ~249, ~470, ~566)
2. Add from pathlib import Path import if not already present

Testing

# Reproduce:
uv init test-shiny
cd test-shiny
uv add shiny
uv run shiny run app.py  # Should show 404 for all static assets

# After fix:
uv run shiny run app.py  # Static assets should load correctly

Workaround (for users)

Add to pyproject.toml:

[tool.uv]
link-mode = "copy"

Then uv sync --reinstall

[cpsievert]

Thanks for reporting! Have you confirmed that by making the changes you've proposed here that it fixes the problem for you?

[cpsievert]

Also, would it be possible to share your full pyproject.toml? We're having some trouble reproducing the behavior by following the steps you've provided.

[kbzsl]

My bad.

I have not noticed that this happens only on my company laptop, where I can still reproduce this issue as I described. But on my personal laptop it is working without any problem.

Most probably this is caused by some limitation of my company laptop. It's weird because I am using uv from a long time on both laptops, and this is the first time when I experienced something different.

You can close this issue, and I have to look elsewhere for the solution.

[kbzsl]

Sorry, previously I draw wrong conclusions.

It is true that it is working on my personal laptop; but without [tool.uv] link-mode = "copy", the uv is still downloading all the packages into the .venv sub-folder on this machine. This is a different topic altogether and I have to fix the uv cache on this machine.

On my company laptop, without specifying the link-mode = "copy" in the pyproject.toml the packages are installed using symlinks.
And in this case I am observing this issue described above: the shiny app is not rendered correctly and in terminal there are a lot of 404 Not Found errors.

After adding the link-mode = "copy" and reinstalling the environment, this small shiny app is working well, but this time all the packages are copied to .venv sub-folder.

I am adding some additional details by using this small check.py code:

import os, shiny
from pathlib import Path

p = Path(shiny.__file__).parent / "www" / "shared" / "bootstrap"
css = p / "bootstrap.min.css"

print(f"shiny dir:     {p}")
print(f"is_symlink(dir):  {p.is_symlink()}")
print(f"is_symlink(css):  {css.is_symlink()}")
print(f"realpath(dir):    {os.path.realpath(p)}")
print(f"realpath(css):    {os.path.realpath(css)}")
print(f"commonpath check: ", end="")

rp_file = os.path.realpath(css)
rp_dir = os.path.realpath(p)
try:
    result = os.path.commonpath([rp_file, rp_dir])
    print(f"PASS ({result})")
except ValueError as e:
    print(f"FAIL ({e})")

print(f"\nstarlette version: ", end="")
import starlette; print(starlette.__version__)
print(f"uv link type check:")
os.system(f'cmd /c "dir /AL {p}"')

1. without link-mode = "copy"

shiny dir:     c:\py_tutorials\debug_shiny__without_link-mode\.venv\Lib\site-packages\shiny\www\shared\bootstrap
is_symlink(dir):  False
is_symlink(css):  True
realpath(dir):    C:\py_tutorials\debug_shiny__without_link-mode\.venv\Lib\site-packages\shiny\www\shared\bootstrap
realpath(css):    C:\Users\USERNAME\AppData\Local\uv\cache\archive-v0\V17Y6OJc8Ql0M_qC\shiny\www\shared\bootstrap\bootstrap.min.css
commonpath check: PASS (C:\)

starlette version: 1.0.0
uv link type check:
 Volume in drive C is Windows

 Directory of c:\py_tutorials\debug_shiny__without_link-mode\.venv\Lib\site-packages\shiny\www\shared\bootstrap

05/12/2026  06:29 PM    <SYMLINK>      bootstrap.bundle.min.js [C:\Users\USERNAME\AppData\Local\uv\cache\archive-v0\V17Y6OJc8Ql0M_qC\shiny\www\shared\bootstrap\bootstrap.bundle.min.js]
05/12/2026  06:29 PM    <SYMLINK>      bootstrap.bundle.min.js.map [C:\Users\USERNAME\AppData\Local\uv\cache\archive-v0\V17Y6OJc8Ql0M_qC\shiny\www\shared\bootstrap\bootstrap.bundle.min.js.map]
05/12/2026  06:29 PM    <SYMLINK>      bootstrap.min.css [C:\Users\USERNAME\AppData\Local\uv\cache\archive-v0\V17Y6OJc8Ql0M_qC\shiny\www\shared\bootstrap\bootstrap.min.css]
05/12/2026  06:29 PM    <SYMLINK>      font.css [C:\Users\USERNAME\AppData\Local\uv\cache\archive-v0\V17Y6OJc8Ql0M_qC\shiny\www\shared\bootstrap\font.css]
05/12/2026  06:29 PM    <SYMLINK>      _version.json [C:\Users\USERNAME\AppData\Local\uv\cache\archive-v0\V17Y6OJc8Ql0M_qC\shiny\www\shared\bootstrap\_version.json]

2. after adding link-mode = "copy" and reinstalling the environment

shiny dir:     c:\py_tutorials\debug_shiny__link-mode_copy\.venv\Lib\site-packages\shiny\www\shared\bootstrap
is_symlink(dir):  False
is_symlink(css):  False
realpath(dir):    C:\py_tutorials\debug_shiny__link-mode_copy\.venv\Lib\site-packages\shiny\www\shared\bootstrap
realpath(css):    C:\py_tutorials\debug_shiny__link-mode_copy\.venv\Lib\site-packages\shiny\www\shared\bootstrap\bootstrap.min.css
commonpath check: PASS (C:\py_tutorials\debug_shiny__link-mode_copy\.venv\Lib\site-packages\shiny\www\shared\bootstrap)

starlette version: 1.0.0
uv link type check:
 Volume in drive C is Windows

 Directory of c:\py_tutorials\debug_shiny__link-mode_copy\.venv\Lib\site-packages\shiny\www\shared\bootstrap

File Not Found

I suspect that this issue is caused by the symlinks used by uv when installing the packages. Would passing follow_symlink=True to Starlette's StaticFiles when mounting Shiny's static asset directories fix this issue?