astral-sh/ruff · error

Expected a UTF-8 working directory

Error message

Expected a UTF-8 working directory

What it means

`ruff analyze graph` builds a project-wide import graph and writes all output paths relative to the current working directory. The command requires the CWD to be representable as UTF-8 (SystemPathBuf::from_path_buf fails on non-UTF-8 paths); when it is not, this expect panics instead of producing a graceful error.

Source

Thrown at crates/ruff/src/commands/analyze_graph.rs:36

use std::io::Write;
use std::path::{Path, PathBuf};
use std::sync::{Arc, Mutex};

/// Generate an import map.
pub(crate) fn analyze_graph(
    args: AnalyzeGraphArgs,
    config_arguments: &ConfigArguments,
) -> Result<ExitStatus> {
    // Construct the "default" settings. These are used when no `pyproject.toml`
    // files are present, or files are injected from outside the hierarchy.
    let pyproject_config = resolve(config_arguments, None)?;
    if pyproject_config.settings.analyze.preview.is_disabled() {
        warn_user!("`ruff analyze graph` is experimental and may change without warning");
    }

    // Write all paths relative to the current working directory.
    let root =
        SystemPathBuf::from_path_buf(CWD.clone()).expect("Expected a UTF-8 working directory");

    // Find all Python files.
    let files = resolve_default_files(args.files, false);
    let (mut paths, resolver) = project_files_in_path(&files, &pyproject_config, config_arguments)?;

    // Filter to only Python files
    paths.retain(|path| {
        if let Ok(ResolvedFile::Root(path) | ResolvedFile::Nested(path)) = path {
            matches!(SourceType::from(path), SourceType::Python(_))
        } else {
            true
        }
    });

    if paths.is_empty() {
        warn_user_once!("No Python files found under the given path(s)");
        return Ok(ExitStatus::Success);
    }

View on GitHub (pinned to 26f38c119c)

Solutions

1. cd to a directory whose full path is valid UTF-8 and re-run the command
2. Rename the offending ancestor directory/file to use only UTF-8 characters
3. Check the CWD with `pwd | iconv -t utf-8` / `echo $PWD | LC_ALL=C grep -axv '.*'` to locate the non-UTF-8 segment
4. Run from a project checkout located under a plain ASCII path such as /tmp or ~/src

Example fix

# before
$ cd /data/$(printf 'bad\xff')/project && ruff analyze graph
panic: Expected a UTF-8 working directory
# after
$ cd /data/project && ruff analyze graph

import subprocess, sys
cwd = subprocess.run(['pwd'], capture_output=True).stdout
try:
    cwd.decode('utf-8')
except UnicodeDecodeError:
    sys.exit('CWD is not valid UTF-8; move to a UTF-8 path before running ruff analyze graph')

When it happens

Trigger: Running `ruff analyze graph` (with analyze preview not enabled, or after the experimental warning) from a directory whose absolute path contains non-UTF-8 bytes (e.g. invalid UTF-8 from locale issues or exotic filenames in the path).

Common situations: Working inside a directory created with non-UTF-8 bytes on Linux; environments where the process CWD is inherited from a path with invalid encoding; CI containers with odd mount-point names.

Related errors

• truth source directory `{path}` contains invalid UTF-8
• path `{}` is not valid UTF-8
• extra use-def data should have been retained
• System should be writable
• should be set because `extract_if` only yields elements with

AI-assisted analysis of astral-sh/ruff@26f38c119c (2026-09-05). Data as JSON: /api/errors/36b31d85c7628a36. Report an issue: GitHub.