Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Servers, nginx and Docker

uWSGI fails at start with Fatal Python error: init_fs_encoding

ErrorFatal Python error: init_fs_encoding: failed to get the Python codec of the filesystem encoding

Short 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.

  • Applies to uWSGI (current docs), Python 3.11+, Ubuntu 24.04
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 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 --version
  2. 2Match what you see, then jump to its fix

    1. 1The 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. 2The error appears only in the service, not in your shellPYTHONHOME is set to a path that does not hold this Python's libraryFix
    3. 3uwsgi --python-version prints one minor version, the venv anotherThe uWSGI Python plugin and the virtualenv use different Python versionsFix

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.cfg

2Fix

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/venv

3Verify

Start uWSGI by hand with the same config.

uwsgi --ini /etc/uwsgi/apps-enabled/myapp.ini

Confirmed by docs.python.org

Did this fix it?

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 uwsgi

3Verify

Check that uWSGI starts and stays active.

systemctl status uwsgi --no-pager

Confirmed by docs.python.org

Did this fix it?

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 --version

2Fix

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/venv

3Verify

Compare versions again, then start uWSGI.

uwsgi --python-version
/path/to/venv/bin/python --version

Confirmed by docs.python.org

Did this fix it?

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:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.