uWSGI fails at start with Fatal Python error: init_fs_encoding
Fatal Python error: init_fs_encoding: failed to get the Python codec of the filesystem encodingShort answer
uWSGI embeds Python and could not find that Python's standard library, so it failed before any of your code ran. Check three things: the home or virtualenv option points to a real environment, PYTHONHOME is not set to a stray path, and the Python version of the uWSGI plugin matches the environment.
Fix it fast
1Find out which cause you have
Print which Python uWSGI was built for, and which Python your virtual environment holds. If the numbers differ, jump to the third cause.
uwsgi --python-version /path/to/venv/bin/python --version2Match what you see, then jump to its fix
- 1
The ini file or command line has home, virtualenv or -H, and the folder is missing, moved, or not an environment rootThe home (virtualenv) option points at the wrong folderFix - 2
The error appears only in the service, not in your shellPYTHONHOME is set to a path that does not hold this Python's libraryFix - 3
uwsgi --python-version prints one minor version, the venv anotherThe uWSGI Python plugin and the virtualenv use different Python versionsFix
- 1
What does the error look like?
Fatal Python error: init_fs_encoding: failed to get the Python codec of the filesystem encoding
Cause 1 of 3
The home (virtualenv) option points at the wrong folder
1Check
uWSGI's home option sets PYTHONHOME and the virtualenv. A virtualenv root holds a pyvenv.cfg file; if it is absent or the environment was moved, the path is wrong.
grep -n -E '^(home|virtualenv|venv|pyhome)' /etc/uwsgi/apps-enabled/*.ini
ls /path/to/venv/pyvenv.cfg2Fix
Point home at the environment root. A moved environment does not work, so recreate it where you want it.
python -m venv /path/to/venv
/path/to/venv/bin/python -m pip install -r requirements.txt
# uwsgi.ini
# home = /path/to/venv3Verify
Start uWSGI by hand with the same config.
uwsgi --ini /etc/uwsgi/apps-enabled/myapp.iniConfirmed by docs.python.org
Cause 2 of 3
PYTHONHOME is set to a path that does not hold this Python's library
1Check
When PYTHONHOME is set, it replaces the prefix where Python looks for its standard library. A leftover value in the unit file, profile or environment sends uWSGI to the wrong place.
env | grep PYTHONHOME
systemctl cat uwsgi | grep -i -E 'Environment|PYTHONHOME'2Fix
Remove the stray PYTHONHOME and set the home option to the environment root only.
# remove the line from the unit file, then
sudo systemctl daemon-reload
sudo systemctl restart uwsgi3Verify
Check that uWSGI starts and stays active.
systemctl status uwsgi --no-pagerConfirmed by docs.python.org
Cause 3 of 3
The uWSGI Python plugin and the virtualenv use different Python versions
1Check
A virtual environment is tied to the Python it was created from. If it was made with a different interpreter than the one uWSGI embeds, the library layout does not fit.
uwsgi --python-version
/path/to/venv/bin/python --version2Fix
Recreate the virtualenv with the Python that matches the uWSGI plugin, or load the plugin for the Python you use.
rm -rf /path/to/venv
python3 -m venv /path/to/venv3Verify
Compare versions again, then start uWSGI.
uwsgi --python-version
/path/to/venv/bin/python --versionConfirmed by docs.python.org
How do I stop it coming back?
- After any Python upgrade on the server, rebuild virtual environments and restart uWSGI.
- Keep the virtualenv path in one place, the uWSGI ini file.
- Do not move or rename a virtual environment; recreate it.
Sources
How was this page made?
I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.
Which stack is behind this page?
Projects of mine built on the same technologies:
- stegnor.comMy company site: 804 pages from a Python and Jinja generator, with 15 free browser tools.
- MenuloA restaurant discovery platform in Germany, kept current by a Python ingestion pipeline.
- ShopGoAn e-commerce aggregator with a Python scraping engine behind its catalog, past 10K Google Play downloads.
Related fixes
Servers
pip install confluent-kafka fails because librdkafka/rdkafka.h is missing
pip stops while building confluent-kafka from source
The error means pip is compiling confluent-kafka from source, and the compiler cannot find the librdkafka C headers.
3 causes, each with a fixServers
cv2.imshow raises 'not implemented' because the wrong OpenCV package is installed
cv2.imshow() works in one environment and fails in another
The headless OpenCV packages are built without any GUI code, so cv2.imshow cannot open a window.
2 causes, each with a fixServers
pip install Cython succeeded, but the shell cannot find cythonize
a pip warning that a script was installed to a directory outside PATH
pip put the cythonize script in a folder your shell does not search.
3 causes, each with a fixServers
Django returns a 500 behind Gunicorn and the traceback is nowhere
The traceback shows locally with runserver but not under Gunicorn
With DEBUG set to False, Django's default logging does not print errors to the console.
2 causes, each with a fixServers
Docker build fails with apk: not found in a Python or Ubuntu image
/bin/sh: 1: apk: not found
apk is the package manager of Alpine Linux only.
2 causes, each with a fixServers
You cannot pip install packages inside an Ubuntu Docker container
error: externally-managed-environment
If pip is missing, install the python3-pip package with apt, in the same RUN as apt-get update.
3 causes, each with a fix